SpatialData

0.7.2 verified Fri May 01 auth: no python

SpatialData is a Python library for storing and processing spatial omics data. It defines an in-memory format using xarray and Zarr for efficient out-of-core operations, supporting multi-modal (transcripts, images, shapes, points, tables) spatial datasets. Version 0.7.2 requires Python >=3.11. Releases are frequent (monthly).

pip install spatialdata

Common errors

error AttributeError: 'SpatialData' object has no attribute 'tables' ↓

cause Trying to access elements via attribute (e.g., sdata.tables) in version >=0.7.0 where dict-style access is required.

fix

Use sdata['table'] instead of sdata.table.

error ImportError: cannot import name 'read_zarr' from 'spatialdata.io' ↓

cause In spatialdata >=0.5, read_zarr moved to top-level from spatialdata.io.

fix

Change import to 'from spatialdata import read_zarr'.

error KeyError: 'Could not find element with key ...' ↓

cause Trying to access an element that doesn't exist in the SpatialData object.

fix

Check available keys with print(sdata) or list(sdata._gen_elements()).

Warnings

breaking From version 0.7.0, the SpatialData class no longer inherits from dict. Access elements via sdata['table'] instead of sdata.tables or sdata['points'] instead of sdata.points. This breaks code using attribute access. ↓

fix Use dictionary-style key access: sdata['table'] instead of sdata.table.

breaking In 0.6.0, rename of 'shapes' to 'polygons' and 'images' to 'raster' may break old code. Check element types. ↓

fix Use sdata['polygons'] for polygons and sdata['raster'] for images, or check sdata._gen_elements().

deprecated The `read_visium` function's parameter `coordinates` is deprecated in favor of `spatial_element_type`. Use `spatial_element_type='image'` etc. ↓

fix Replace `coordinates` with `spatial_element_type` in read_visium calls.

gotcha When writing a SpatialData object to Zarr, only elements that are explicitly added are saved. Deleting an element from the in-memory object does not remove it from the Zarr store; you must use `overwrite=True` or remove the element from the store manually. ↓

fix When writing, use `sdata.write('path.zarr', overwrite=True)` to fully replace the store.

Install

pip install 'spatialdata[extra]'

Imports

SpatialData
```
from spatialdata import SpatialData
```
read_zarr
wrong
```
from spatialdata.io import read_zarr
```
correct
```
from spatialdata import read_zarr
```
In older versions (<0.5) the import path was different. Currently read_zarr is exposed at the top level.
read_visium
```
from spatialdata.io import read_visium
```
I/O functions are in spatialdata.io submodule.

Quickstart

Load an existing SpatialData Zarr dataset from disk and display its structure.

from spatialdata import SpatialData, read_zarr
sdata = read_zarr('path/to/data.zarr')
print(sdata)  # inspect elements