Imaging-based spatial
Imaging-based transcriptomic datasets can include a cell-by-gene matrix, segmented cell boundaries, fluorescence images and transcript coordinates. The viewer displays cells as points at overview zoom, with boundaries and transcripts available at higher zoom. The following examples cover Xenium, MERSCOPE and CosMx inputs; other platforms can use the same table formats with explicit column mappings.
Required input
An object with cells × genes and coordinates in microns is enough:
spatialscape init "xenium/*/adata.h5ad" --id xen # quoted: one glob entry, one sample per folder
spatialscape build xen.yaml && spatialscape serve bundles --opensamples:
- glob: xenium/*/adata.h5ad
platform: xenium # or merfish; other platforms: other
id: "xen_{name}"
fields: { celltype: cell_type, total_counts: transcript_counts }Coordinates are taken as microns for xenium and merfish. A platform that writes pixels (CosMx) needs the scale: microns: { microns_per_unit: 0.12028 }.
The optional layers
Each is one key on the sample. For a Xenium outs/ folder init writes all of them when it finds the files; for other platforms it writes the keys as comments with the column names to fill in.
| Layer | Key | Xenium (defaults) | MERSCOPE | CosMx |
|---|---|---|---|---|
| Fluorescence image | images: auto, or a path | morphology_focus/ found on its own, read at 0.85 µm/px | images/mosaic_DAPI_z3.tif with pixel_size and translate from micron_to_mosaic_pixel_transform.csv | per-FOV TIFFs; stitch first |
| Cell boundaries | polygons: | cell_boundaries.parquet (cell_id, vertex_x, vertex_y) | export the geometry to a long table (below) | *-polygons.csv: cellID, x_global_px, y_global_px |
| Nuclei, for comparison | segmentations: | nucleus_boundaries.parquet found next to the cell boundaries | a second long table | – |
| Transcripts | molecules: | transcripts.parquet (feature_name, x_location, y_location, qv ≥ 20, cell_id, overlaps_nucleus) | detected_transcripts.csv: gene, global_x, global_y, cell_id (−1 = none) | *_tx_file.csv: target, x_global_px, y_global_px, cell_ID (0 = none), CellComp |
Tables are Parquet, CSV or TSV, gzipped or not. Control features are dropped by name (10x's NegControl* and Unassigned*, Vizgen's Blank-*, NanoString's NegPrb*, SystemControl*, FalseCode*). Each column is built in the examples: xenium-mouse-brain, merscope-mouse-brain and cosmx-nsclc.
Xenium
- glob: xenium/*/outs/adata.h5ad
platform: xenium
id: "xen_{name}"
polygons: { path: "{dir}/cell_boundaries.parquet" } # shapes; nuclei are found next to it
molecules: { path: "{dir}/transcripts.parquet" } # 170-400 MB per section; delete the line to leave them outimages: auto (the default) finds the morphology image (morphology_focus/ in XOA 2 and later, morphology_focus.ome.tif in XOA 1) and the pixel size from experiment.xenium. The files are JPEG 2000 and need pip install "spatialscape[images]"; without it the image is skipped with a note. Cell ids must match: the boundary and transcript files of a re-segmentation (Xenium Ranger, Baysor, Proseg) go with the matrix of that run, not the original, and the build log reports the match rate.
If the object's coordinates were transposed or mirrored after segmentation (an export through another tool), set polygons.affine once; the molecules and the nuclei inherit it, and images take transpose / flip. Troubleshooting has the recipe.
MERSCOPE
- path: region_0/adata.h5ad
platform: merfish
id: mer_r0
polygons: { path: region_0/boundaries_long.parquet, id_column: cell, x_column: x, y_column: y }
molecules: { path: region_0/detected_transcripts.csv, feature_column: gene, x_column: global_x, y_column: global_y, qv_column: null, cell_column: cell_id, nucleus_column: null }
images:
- { path: region_0/images/mosaic_DAPI_z3.tif, kind: multichannel, pixel_size: 0.108, translate: [0, 0] }Vizgen's cell_boundaries.parquet holds one WKB geometry per cell, not one row per vertex. Flatten it once:
import geopandas as gpd, pandas as pd
g = gpd.read_parquet("region_0/cell_boundaries.parquet")
rows = [(cid, x, y) for cid, geom in zip(g["EntityID"], g.geometry) for x, y in geom.exterior.coords]
pd.DataFrame(rows, columns=["cell", "x", "y"]).to_parquet("region_0/boundaries_long.parquet")The mosaic's placement comes from micron_to_mosaic_pixel_transform.csv: pixel_size is 1 over its scale, translate its offset divided by the scale and negated. Coordinates and transcripts are already microns.
CosMx
- path: slide1/adata.h5ad
platform: other
id: cosmx_s1
microns: { microns_per_unit: 0.12028 } # global pixels -> um
point_radius: 5
polygons: { path: slide1/slide1-polygons.csv, id_column: cellID, x_column: x_global_px, y_column: y_global_px }
molecules: { path: slide1/slide1_tx_file.csv.gz, feature_column: target, x_column: x_global_px, y_column: y_global_px, qv_column: null, cell_column: cell_ID, nucleus_column: CellComp }The flat files number cells per FOV (cell_ID) while AtoMx exports name them c_<slide>_<fov>_<cell>; the boundary ids must spell the matrix's obs_names the same way, and the build log says how many matched. One microns: covers coordinates, boundaries and transcripts, since all three share the global pixel frame.
CODEX, PhenoCycler, MICS, IMC (multiplexed protein imaging)
Antibody panels of 30 to 100 markers imaged on one section give a many-channel image, a segmentation mask and a cells × markers intensity table, usually with gated cell types on top. The scverse toolbox spatialproteomics keeps all of that in one object (an xarray Dataset saved as Zarr), and spatialscape reads that object directly:
defaults:
platform: codex
microns: { microns_per_unit: 0.5 } # the scan's pixel size: coordinates are pixels (PhenoCycler-Fusion 0.5, Keyence 20x 0.377)
expression: { normalized: raw } # per-cell intensities summarised by spatialproteomics, kept as they are
fields: { cell_type: labels, neighborhood: neighborhoods, pd1_positive: PD-1_binarized, degree: degree }
samples:
- glob: cores/LN_*.zarr # one object per core
id: "{stem}"
polygons: { labels: "{dir}/{stem}.zarr/_segmentation" } # the label mask, traced into cell outlines
images:
- { id: stains, name: Stains, path: "{dir}/{stem}.zarr/_image_raw", kind: multichannel, pixels_per_unit: 1.0, crop: false }What the reader takes from the object: _intensity (cells × channels) as the expression layer, with the channel names as features; _obs as annotations, _labels and _neighborhoods turned into names through the object's property tables and their colours kept, every <marker>_binarized column as a positive / negative category, the gating tree's levels (labels_0, labels_1, ...) as categories too, and the centroids as coordinates. The image is the _image_raw (or _image) array, written band by band with the channel names from the object; _segmentation becomes the cell shapes. A label mask from any other pipeline (MCMICRO, Cytokit, QuPath) works the same way as a TIFF or PNG with polygons: { labels: mask.tif }, next to a table of cells read as any other AnnData.
In the viewer the channel list shows every marker; up to six draw at once, chosen by clicking, and only those are fetched. A panel's first six channels are rarely the ones to open on, so name them at the top of the yaml: default_channels: [DAPI, CD20, CD3, CD68, Ki-67, CD31]. Colour cells by any marker's intensity from the gene box, or by a gating-tree level from the annotations.
Layer size and loading
The following are approximate storage sizes for the Xenium examples. Image resolution, polygon complexity and the number of transcripts affect both size and build time. See the example dataset READMEs for run-specific requirements.
| Layer | Approximate bundle size | Viewer behavior |
|---|---|---|
| Image at 0.85 µm/px | 200 MB per section | loads tiles for the visible area |
| Cell shapes | 10 MB per 250k cells | replaces points when a cell is about 6 px across; up to 40,000 cells per pane |
| Nuclei | 7–10 MB per section | draws dashed boundaries and reports cell counts and median area |
| Transcripts | 3.5 bytes per molecule | limits the number drawn according to the visible density |
Add or remove a layer by editing the sample's configuration and rerunning build. Only affected samples are rebuilt.
Next
- Comparing segmentations and molecules in the viewer.
- Preparing data for R objects, SpatialData stores and image placement.
- Making changes maps every edit to the line to change.