BioTender-max Version Compatibility
Reference examples tested with: anndata 0.10+, numpy 1.26+, pandas 2.2+, scanpy 1.10+, spatialdata 0.1+, squidpy 1.3+
Before using code patterns, verify installed versions match. If versions differ:
- Python:
pip show <package>thenhelp(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 Visium spatial data" → Read spatial transcriptomics outputs (Visium, Xenium, MERFISH, Slide-seq) into AnnData objects with spatial coordinates and tissue images.
- Python:
squidpy.read.visium('spaceranger_out/'),spatialdata.read_zarr()
Load and work with spatial transcriptomics data from various platforms.
Required Imports
import squidpy as sq
import scanpy as sc
import anndata as ad
import spatialdata as sd
import spatialdata_io as sdio
Load 10X Visium Data
Goal: Load Visium spatial transcriptomics data from Space Ranger output into an AnnData object.
Approach: Use Squidpy's read.visium to parse the output directory, which loads expression, spatial coordinates, and tissue images.
# Load Space Ranger output (standard method)
adata = sq.read.visium('path/to/spaceranger/output/')
print(f'Loaded {adata.n_obs} spots, {adata.n_vars} genes')
# Spatial coordinates are in adata.obsm['spatial']
print(f"Spatial coords shape: {adata.obsm['spatial'].shape}")
# Image is in adata.uns['spatial']
library_id = list(adata.uns['spatial'].keys())[0]
print(f'Library ID: {library_id}')
Load Visium with Scanpy
Goal: Load Visium data using Scanpy's built-in reader as an alternative to Squidpy.
Approach: Use sc.read_visium to parse Space Ranger output, then access images and scale factors from adata.uns['spatial'].
# Alternative using Scanpy directly
adata = sc.read_visium('path/to/spaceranger/output/')
# Access tissue image
img = adata.uns['spatial'][library_id]['images']['hires']
scale_factor = adata.uns['spatial'][library_id]['scalefactors']['tissue_hires_scalef']
Load 10X Xenium Data
Goal: Load single-cell resolution Xenium spatial data.
Approach: Use Squidpy's read.xenium to parse Xenium output, yielding per-cell expression and coordinates.
# Load Xenium output
adata = sq.read.xenium('path/to/xenium/output/')
print(f'Loaded {adata.n_obs} cells')
# Xenium has single-cell resolution
print(f"Cell coordinates: {adata.obsm['spatial'].shape}")
Load with SpatialData (Recommended for New Projects)
Goal: Load spatial data into SpatialData objects for unified multi-modal representation.
Approach: Use spatialdata-io readers per platform, which organize expression, shapes, and images into a single object.
import spatialdata_io as sdio
# Load Visium as SpatialData object
sdata = sdio.visium('path/to/spaceranger/output/')
print(sdata)
# Load Xenium
sdata = sdio.xenium('path/to/xenium/output/')
# Access components
table = sdata.tables['table'] # AnnData with expression
shapes = sdata.shapes # Spatial shapes (spots, cells)
images = sdata.images # Tissue images
Load MERFISH Data
Goal: Load MERFISH (Vizgen MERSCOPE) spatial data.
Approach: Use spatialdata-io or Squidpy readers to parse MERSCOPE output with cell-by-gene counts and metadata.
# MERFISH (Vizgen MERSCOPE)
sdata = sdio.merscope('path/to/merscope/output/')
# Or as AnnData
adata = sq.read.vizgen('path/to/vizgen/output/', counts_file='cell_by_gene.csv', meta_file='cell_metadata.csv')
Load Slide-seq Data
# Slide-seq / Slide-seqV2
adata = sq.read.slideseq('beads.csv', coordinates_file='coords.csv')
Load Nanostring CosMx
# CosMx spatial molecular imaging
sdata = sdio.cosmx('path/to/cosmx/output/')
Load Stereo-seq Data
# Stereo-seq (BGI)
sdata = sdio.stereoseq('path/to/stereoseq/output/')
Load from H5AD with Spatial Coordinates
# If you have h5ad with spatial already stored
adata = sc.read_h5ad('spatial_data.h5ad')
# Verify spatial data exists
if 'spatial' in adata.obsm:
print('Has spatial coordinates')
if 'spatial' in adata.uns:
print('Has image data')
Create Spatial AnnData from Scratch
Goal: Construct a spatial AnnData object from raw expression and coordinate arrays.
Approach: Build an AnnData with spatial coordinates in obsm['spatial'] and minimal metadata in uns['spatial'] for Squidpy compatibility.
import numpy as np
import pandas as pd
# Expression matrix
X = np.random.poisson(5, size=(1000, 500))
# Spatial coordinates
spatial_coords = np.random.rand(1000, 2) * 1000 # x, y in pixels
# Create AnnData
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
# Add minimal spatial metadata for Squidpy
adata.uns['spatial'] = {
'library_id': {
'scalefactors': {'tissue_hires_scalef': 1.0, 'spot_diameter_fullres': 50},
}
}
Access Spatial Coordinates
# Get coordinates as numpy array
coords = adata.obsm['spatial']
x_coords = coords[:, 0]
y_coords = coords[:, 1]
# Get coordinates as DataFrame
coord_df = pd.DataFrame(adata.obsm['spatial'], index=adata.obs_names, columns=['x', 'y'])
Access Tissue Images
# Get high-resolution image
library_id = list(adata.uns['spatial'].keys())[0]
hires_img = adata.uns['spatial'][library_id]['images']['hires']
lowres_img = adata.uns['spatial'][library_id]['images']['lowres']
# Scale factors
scalef = adata.uns['spatial'][library_id]['scalefactors']
print(f"Hires scale: {scalef['tissue_hires_scalef']}")
print(f"Spot diameter: {scalef['spot_diameter_fullres']}")
Convert Between Formats
Goal: Convert spatial data between SpatialData and AnnData representations.
Approach: Extract tables and coordinate arrays from SpatialData, then save as h5ad or zarr.
# SpatialData to AnnData
sdata = sdio.visium('path/to/data/')
adata = sdata.tables['table'].copy()
adata.obsm['spatial'] = np.array(sdata.shapes['spots'][['x', 'y']])
# Save as h5ad
adata.write_h5ad('spatial_converted.h5ad')
# Save SpatialData
sdata.write('spatial_data.zarr')
Load Multiple Samples
Goal: Load and merge spatial data from multiple Visium samples into a single AnnData.
Approach: Iterate over sample directories, tag each with a sample label, then concatenate with ad.concat.
# Load and concatenate multiple Visium samples
samples = ['sample1', 'sample2', 'sample3']
adatas = []
for sample in samples:
adata = sq.read.visium(f'data/{sample}/')
adata.obs['sample'] = sample
adatas.append(adata)
# Concatenate
adata_combined = ad.concat(adatas, label='sample', keys=samples)
print(f'Combined: {adata_combined.n_obs} spots')
Subset by Spatial Region
Goal: Extract spots within a rectangular spatial region of interest.
Approach: Apply coordinate-based boolean masking on obsm['spatial'] to filter spots by x/y bounds.
# Select spots in a rectangular region
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()
print(f'Selected {adata_region.n_obs} spots')
Related Skills
- spatial-preprocessing - QC and normalization after loading
- spatial-visualization - Plot spatial data
- single-cell/data-io - Non-spatial scRNA-seq data loading