spatialdata

library0.7.3pypypi✓ verified 84d ago

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).

data database

pip install spatialdata

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SPATIALDATA

spatialdata

datapythonv0.7.3

Install

57.1s avg

Import

7224ms

Disk

1823MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 57.1s · import 7.224s · 1740.8MB

1823MB installed

● package 1823MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SpatialData

✓ from spatialdata import SpatialData

read_zarr

✓ from spatialdata import read_zarr

✗ from spatialdata.io 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.

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

Debug

Known issues

breakingFrom 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.

affects: >=0.7.0

breakingIn 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().

affects: >=0.6.0, <0.7.0

deprecatedThe `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.

affects: >=0.5.5

gotchaWhen 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.

affects: all

Errors

Common errors & fixes

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

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.

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

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

fix

Change import to 'from spatialdata import read_zarr'.

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

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()).

Upgrade

Version history

0.7.3latest on PyPI · released May 6, 2026

Audit

Dependencies

zarroptionalRequired for chunked, compressed array storage.

xarrayoptionalRequired for labeled multi-dimensional arrays.

anndataoptionalRequired for table (annotation) support.

daskoptionalOptional but recommended for out-of-core/lazy computations.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/scverse/spatialdata.git ↗

packagehttps://pypi.org/project/spatialdata/ ↗

homepagehttps://spatialdata.scverse.org ↗

docshttps://spatialdata.scverse.org/en/latest ↗