Bio Spatial Transcriptomics Spatial Data Io

Version Compatibility

Reference examples tested with: spatialdata 0.2+, spatialdata-io 0.1.5+, squidpy 1.4+, scanpy 1.10+, anndata 0.10+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Spatial Data I/O

"Load my spatial data" -> Parse a platform's output bundle into one coordinate frame holding the expression matrix, coordinates, images, and (for imaging) the molecule table and segmentation shapes.

• Imaging/in-situ (Xenium, MERSCOPE/MERFISH, CosMx, seqFISH): spatialdata_io.{xenium, merscope, cosmx} -> SpatialData with a per-transcript points table AND a derived per-cell tables matrix.
• Sequencing/capture (Visium, Visium HD, Slide-seq/Curio, Stereo-seq): squidpy.read.visium or spatialdata_io.{visium, visium_hd, curio, stereoseq} -> spot/bin matrix + coordinates; NO molecule table.

Governing Principle

The single most consequential I/O fact is that the two platform classes emit different primary objects, and one class emits two of them that are easy to confuse.

Imaging/in-situ platforms emit TWO physically distinct primary objects. The first is a per-TRANSCRIPT molecule table -- one row per decoded molecule with x, y (and often z), gene, a decoding-quality value, and a cell-assignment-or-unassigned. The second is a per-CELL expression matrix, genes-by-cells, DERIVED by overlaying a segmentation and counting the molecules that fall inside each boundary. The matrix looks exactly like scRNA-seq and is therefore wrongly trusted as ground truth, but it is a downstream product: it inherits every segmentation error and is usually quality-filtered (Xenium keeps Q>=20 in the matrix while the transcript table keeps everything). The molecule table is the source of truth and the ONLY object that lets the analyst re-segment, recover unassigned molecules, or do subcellular work. A loader that returns only the cell matrix has silently discarded the re-segmentable layer.

Sequencing/capture platforms (Visium, Slide-seq, Stereo-seq) have NO molecule table -- a spot/bead/bin is mini-bulk over the cells beneath it, captured as a single barcoded profile. Do not go looking for a transcript table that does not exist; the only objects are the barcode-by-gene matrix, the coordinates, and the tissue image.

A second trap is coordinate frames. Images, spot/cell coordinates, and molecule points each live in their own intrinsic pixel or array axes; overlaying transcripts on histology, or building a neighbor graph with a micron radius, requires the right transform (Visium scalefactors; imaging micron-to-pixel matrices). SpatialData makes the frames explicit (intrinsic vs a shared extrinsic "global" system); the legacy AnnData layout hides them in uns['spatial'][library_id]['scalefactors']. Mixing frames silently places points off the image or builds a graph at the wrong scale.

The Platform-Class Fork

The first question of any spatial dataset is which side of the fork it sits on, because it decides what objects exist and what the rest of the pipeline must do.

Object-Model Landscape

Each toolkit is a strategy for co-storing four things in one frame: an expression matrix, geometry (spot circles, cell/nucleus polygons, centroids), raster images (H&E, DAPI, multiplex IF -- often gigapixel), and (imaging only) the molecule point cloud. They differ in how separately they keep these and which is the forward path.

SpatialData is the forward-path Python standard because it is the only framework that natively keeps the molecule table, multiscale OME-NGFF images, and segmentation shapes as first-class, frame-aware elements. Because a SpatialData table IS an AnnData, all of squidpy.gr.* runs on it unchanged.

Platform-to-Reader Map

squidpy.read provides ONLY visium, vizgen, and nanostring -- it has no xenium or slideseq reader. For Xenium, Slide-seq/Curio, Stereo-seq, and Visium HD, use the spatialdata_io reader. scanpy.read_visium is deprecated as of scanpy 1.11 -- prefer squidpy.read.visium (identical obsm/uns layout) or spatialdata_io.visium.

Load Visium (Spot/Capture)

Goal: Read a Space Ranger bundle into an AnnData with coordinates, image, and scalefactors, without reaching for the deprecated scanpy reader.

Approach: Use squidpy.read.visium; coordinates land in obsm['spatial'] (pixels of the full-res image), image and scalefactors in uns['spatial'][library_id].

import squidpy as sq

adata = sq.read.visium('spaceranger_out/')         # filtered matrix + spatial/; NOT a cell -- each spot is a 1-10-cell mixture
library_id = list(adata.uns['spatial'].keys())[0]
scalef = adata.uns['spatial'][library_id]['scalefactors']
# obsm['spatial'] is in FULL-RES pixels; multiply by tissue_hires_scalef to index the hires image
print(adata.n_obs, 'spots', adata.n_vars, 'genes', '| spot diameter (px):', scalef['spot_diameter_fullres'])

Load Imaging Data and Keep the Molecule Table

Goal: Load Xenium (or MERSCOPE/CosMx) so BOTH the per-transcript molecule table and the derived cell matrix are available, not just the matrix.

Approach: Use the spatialdata_io reader, which returns a SpatialData object; the molecule table lives in sdata.points, the cell matrix in sdata.tables, segmentation polygons in sdata.shapes, images in sdata.images. Inspect element names with print(sdata) -- they vary by platform and reader version.

import spatialdata_io as sdio

sdata = sdio.xenium('xenium_out/')                 # needs experiment.xenium manifest
print(sdata)                                       # lists points/tables/shapes/images element names

transcripts = sdata.points['transcripts']          # dask DataFrame: x, y, z, feature_name, qv, cell_id -- ALL Q-scores
adata = sdata.tables['table']                      # AnnData cell matrix -- Q>=20 filtered, inherits segmentation error
# the matrix is a DERIVED product; the molecule table is the re-segmentable source of truth
print('molecules:', transcripts.shape[0].compute(), '| cells in matrix:', adata.n_obs)

For MERSCOPE substitute sdio.merscope('merscope_out/'); for CosMx sdio.cosmx('cosmx_out/'). As an AnnData-only alternative for MERSCOPE, sq.read.vizgen(path, counts_file='cell_by_gene.csv', meta_file='cell_metadata.csv') returns the cell matrix but discards the molecule table.