spatialdata-io: convenient readers for loading common formats into SpatialData

We encourage contributions from the community and from developers of spatial technologies. Please see the "How to Contribute" section below.

This package contains reader functions to load common spatial omics formats into SpatialData. Currently, we provide support for:

• 10x Genomics Visium®
• 10x Genomics Visium HD®
• 10x Genomics Xenium®
• Akoya PhenoCycler® (formerly CODEX®)
• Curio Seeker®
• DBiT-seq
• MCMICRO (output data)
• NanoString CosMx®
• Spatial Genomics GenePS® (seqFISH)
• Steinbock (output data)
• STOmics Stereo-seq®
• Vizgen MERSCOPE® (MERFISH)
• MACSima® (MACS® iQ View output)

Note: all mentioned technologies are registered trademarks of their respective companies.

Please refer to the list of open Pull Requests for readers that are currently being developed. The list of closed but unmerged PRs may also contain useful code from old drafts of readers. Please get in touch if you would like to contribute and iterate on a PR, or reopen a closed one.

Known limitations

Contributions for addressing the below limitations are very welcomed.

• Only Stereo-seq 7.x is supported, 8.x is not currently supported. https://github.com/scverse/spatialdata-io/issues/161

How to Contribute

1. Open a GitHub Issue: Start by opening a new issue or commenting on an existing one in the repository. Clearly describe the problem and your proposed changes to avoid overlapping efforts with others.

2. Submit a Pull Request (PR): Once the issue is discussed, submit a PR to the spatialdata-io repository. If you are contributing a new reader, or extending the reader for a new versions of a technologies, please consult our contribution guide, which describes the steps to ensure that the pull request can be tested on suitable example data and reviewed efficiently.

Getting started

Please refer to the documentation. In particular, the

• API documentation.
• CLI documentation.

Installation

You need to have Python 3.8 or newer installed on your system. If you don't have Python installed, we recommend installing Miniconda.

There are several alternative options to install spatialdata-io:

1. Install the latest release of spatialdata-io from PyPI:

pip install spatialdata-io

2. Install the latest development version:

pip install git+https://github.com/scverse/spatialdata-io.git@main

Contact

For questions and help requests, you can reach out in the scverse discourse. If you found a bug, please use the issue tracker.

Readers from third-party libraries

Technologies that can be read into SpatialData objects using third-party libraries:

• METASPACE (MALDI, ...): metaspace-converter
• PhenoCycler®: SOPA
• MACSima®: SOPA
• Hyperion® (Imaging Mass Cytometry): SOPA

Disclaimer

This library is community maintained and is not officially endorsed by the aforementioned spatial technology companies. As such, we cannot offer any warranty of the correctness of the representation. Furthermore, we cannot ensure the correctness of the readers for every data version as the technologies evolve and update their formats. If you find a bug or notice a misrepresentation of the data please report it via our Bug Tracking System so that it can be addressed either by the maintainers of this library or by the community.

Solutions to common problems

Problem: I cannot visualize the data, everything is slow

Solution: after parsing the data with spatialdata-io readers, you need to write it to Zarr and read it again. Otherwise the performance advantage given by the SpatialData Zarr format will not available.

from spatialdata_io import xenium
from spatialdata import read_zarr

sdata = xenium("raw_data")
sdata.write("data.zarr")
sdata = read_zarr("sdata.zarr")

Citation

Marconato, L., Palla, G., Yamauchi, K.A. et al. SpatialData: an open and universal data framework for spatial omics. Nat Methods (2024). https://doi.org/10.1038/s41592-024-02212-x

spatialdata-io is part of the scverse® project (website, governance) and is fiscally sponsored by NumFOCUS. If you like scverse® and want to support our mission, please consider making a tax-deductible donation to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.