domains / science / spatial-transcriptomics-data-loading / spatial-data-io

spatial-data-io

Skill card

combined

The two skills cover the same task but with different depth and scope. The first copy (OpenClaw) is a practical, code-heavy recipe book for loading specific platforms (Visium, Xenium, MERFISH, Slide-seq, CosMx, Stereo-seq) using Squidpy and SpatialData, including creating data from scratch and subsetting. The second copy (GPTomics) is a conceptual guide that emphasizes the distinction between imaging/in-situ (molecule tables) and sequencing/capture (spot matrices) platforms, warns about coordinate frame mismatches, and provides a decision framework for choosing the right reader. The GPTomics version contains critical conceptual constraints (e.g., 'molecule table is source of truth', 'Visium has no molecule table') and version compatibility checks that the OpenClaw version lacks. Conversely, the OpenClaw version has specific code examples for creating AnnData from scratch and subsetting by region that are not present in the GPTomics version. Combining them yields a more robust skill that handles both the 'what to load' decision logic and the 'how to load' implementation details.

Repositories

Other copies

Combined skill

---
name: bio-spatial-transcriptomics-spatial-data-io
description: Load spatial transcriptomics data from Visium, Xenium, MERFISH, Slide-seq, and other platforms using Squidpy and SpatialData. Decide between imaging (molecule table) and sequencing (spot matrix) platforms, verify versions, and access spatial coordinates.
tool_type: python
primary_tool: spatialdata
---

# Spatial Data I/O

## 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 code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API.

## Platform Class Decision

1. **Imaging/In-situ (Xenium, MERFISH, CosMx):**
   - Primary objects: Molecule table (source of truth) + Segmentation-derived cell matrix.
   - Use `spatialdata_io.{xenium, merscope, cosmx}`.
   - Note: The cell matrix inherits segmentation errors; the molecule table allows re-segmentation.
2. **Sequencing/Capture (Visium, Slide-seq, Stereo-seq):**
   - Primary objects: Spot/bin matrix + coordinates + image.
   - No molecule table exists.
   - Use `squidpy.read.visium` or `spatialdata_io.{visium, curio, stereoseq}`.

## Required Imports

```python
import squidpy as sq
import scanpy as sc
import anndata as ad
import spatialdata as sd
import spatialdata_io as sdio
import numpy as np
import pandas as pd
```

## Load Data

### 10X Visium
```python
# Standard method
adata = sq.read.visium('path/to/spaceranger/output/')

# Or with SpatialData
sdata = sdio.visium('path/to/spaceranger/output/')
```

### 10X Xenium
```python
# SpatialData (Recommended for access to molecule table)
sdata = sdio.xenium('path/to/xenium/output/')

# Or Squidpy
adata = sq.read.xenium('path/to/xenium/output/')
```

### MERFISH (Vizgen MERSCOPE)
```python
sdata = sdio.merscope('path/to/merscope/output/')
# Or AnnData
adata = sq.read.vizgen('path/to/vizgen/output/', counts_file='cell_by_gene.csv', meta_file='cell_metadata.csv')
```

### Slide-seq
```python
adata = sq.read.slideseq('beads.csv', coordinates_file='coords.csv')
```

### CosMx
```python
sdata = sdio.cosmx('path/to/cosmx/output/')
```

### Stereo-seq
```python
sdata = sdio.stereoseq('path/to/stereoseq/output/')
```

## Access Spatial Data

### Coordinates
```python
# From AnnData
coords = adata.obsm['spatial']

# From SpatialData
# Access via sdata.shapes or sdata.points depending on platform
```

### Images
```python
# From AnnData
library_id = list(adata.uns['spatial'].keys())[0]
hires_img = adata.uns['spatial'][library_id]['images']['hires']
scalef = adata.uns['spatial'][library_id]['scalefactors']
```

## Create Spatial AnnData from Scratch

```python
X = np.random.poisson(5, size=(1000, 500))
spatial_coords = np.random.rand(1000, 2) * 1000

adata = ad.AnnData(X)
adata.obs_names = [f'spot_{i}' for i in range(1000)]
adata.var_names = [f'gene_{i}' for i in range(500)]
adata.obsm['spatial'] = spatial_coords

adata.uns['spatial'] = {
    'library_id': {
        'scalefactors': {'tissue_hires_scalef': 1.0, 'spot_diameter_fullres': 50},
    }
}
```

## Subset by Spatial Region

```python
x_min, x_max = 1000, 2000
y_min, y_max = 1500, 2500

coords = adata.obsm['spatial']
in_region = (coords[:, 0] >= x_min) & (coords[:, 0] <= x_max) & (coords[:, 1] >= y_min) & (coords[:, 1] <= y_max)

adata_region = adata[in_region].copy()
```