spatialrefinery

A toolkit for turning raw spatial-omics vendor outputs into analysis-ready data: 10x Genomics Xenium bundles become SpatialData zarr stores, and whole-slide/microscopy images become pyramidal OME-TIFF.

Why spatialrefinery

spatialrefinery was built for Phoenix, which predicts spatial transcriptomics from routine histology and needs training data assembled the same way across every Xenium sample: an aligned H&E image and transcript-derived pseudo-bulk spots at several resolutions, all in one SpatialData object. Rather than re-deriving that pipeline per sample, spatialrefinery turns a raw Xenium bundle – transcripts, cell/nucleus boundaries, aligned H&E – into a zarr store with pseudo-spots binned at whatever sizes a given resolution needs (e.g. 55um, 100um), and converts the paired whole-slide image to a pyramidal OME-TIFF for fast viewing. Run it over a batch of raw bundles and you get one common, multi-resolution dataset to train Phoenix on.

What spatialrefinery does, end to end

from spatialrefinery import download_xenium_study, xenium_to_spatialdata, convert_to_ometiff

# 1. Fetch a Xenium study's raw asset bundle from a `curl -O <url>` manifest
download_xenium_study("manifest.txt", outdir="raw_files", kinds=["outs"])

# 2. Convert the raw bundle into a SpatialData zarr store, with pseudo-spots
xenium_to_spatialdata(
    dataset_path="raw_files/my_study",
    output_path="processed",
    create_spots=True,
    spot_sizes=[55, 100],
)

# 3. Convert an associated whole-slide image to pyramidal OME-TIFF
convert_to_ometiff(source="raw_files/my_study/slide.svs", output_dir="processed")

Highlights

Download

Fetch a Xenium study’s raw assets from a curl -O <url> manifest, with retries, atomic writes, and parallel workers.

Convert to SpatialData

Turn a raw Xenium bundle – transcripts, cell/nucleus boundaries, aligned H&E – into one SpatialData zarr store.

Pseudo-spots

Bin transcripts or cell boundaries into Visium-like circular or hexagonal spots at any size, with configurable overlap.

Pyramidal imaging

Convert whole-slide images (.svs, .ndpi, .tif, .czi, …) to tiled, multi-resolution OME-TIFF for fast viewing at any zoom level.

Which entry point do I want?

Task	Function	Tutorial
Download a Xenium study’s raw assets	download_xenium_study	Downloading Xenium data
Convert a Xenium bundle to a SpatialData zarr store	xenium_to_spatialdata	Xenium to SpatialData zarr
…and package it as a zip for transfer	xenium_to_spatialdata_zip	Xenium to SpatialData zarr
Convert a whole-slide image to pyramidal OME-TIFF	convert_to_ometiff	Converting images to OME-TIFF
Segment nuclei in an H&E slide and store them as SpatialData	segment_wsi	Nucleus segmentation to SpatialData zarr