Overview#

spora [io] loads datasets in the spora [data] format. Choose the loading level that matches your task. All loaders expect an existing spora [data] directory; they do not download or register images.

Loading Interfaces#

Loading interfaces#

Class

What it provides

HEImagingDataset

RGB H&E tissues and tiles; ImageNet, HIBOU, or identity normalization presets.

SingleIHCImagingDataset

Single-marker RGB IHC, stored in a marker-specific directory.

MultiplexImagingDataset

IMC, CODEX, CyCIF, and MIBI; channel annotations, QC and UniProt filtering, and standardization.

ComposedImagingDataset

Multiple modalities from one cohort, associated through shared tissue IDs.

SporaDataset

A combined index across cohorts, with tissue or tile sampling.

All unimodal datasets inherit from BaseImagingDataset, which handles the metadata, the shared tissue and cell masks, and the tile coordinates. ComposedImagingDataset wraps several unimodal datasets of one cohort, and SporaDataset wraps several composed datasets.

Lazy Loading and OME-Zarr#

Images are stored as OME-Zarr 0.5 stores on Zarr v3: each image is a chunked, compressed (C, H, W) array, written in 256-pixel chunks grouped into 1024-pixel shards. Every chunk spans all channels of the image. Instantiating a dataset class does not load any images. Each request opens the image store read-only and reads only the region it needs: a tile reads the chunks that overlap its window. Because the chunks hold all channels, every read loads all channels of that region. Sampling tiles from whole-slide images therefore stays fast, and memory use scales with the tile rather than the image. Loading a whole tissue reads the full array.

Typed Outputs#

Loading a tissue or tile returns a typed dataclass:

  • HETissue: a torch.Tensor of shape (3, H, W), or (H, W, 3) depending on image_mode.

  • MultiplexTissue: a tensor of shape (C, H, W) with channel_names, measured_mask, image_loading_mask, and optional uniprot_ids.

  • IHCTissue: an RGB IHC image with its marker name.

  • ComposedTissue: a dictionary mapping modality names to their tissue objects.

  • TissueMask and CellMask: binary or integer segmentation masks.

Images, Masks, and Tiles#

Load whole tissues or spatial windows from channel-first Zarr arrays. Tissue and cell masks live in a shared segmentation directory. Tile coordinates are generated once per resolution, strategy, and tile size. Non-default grid strategies support zero-padding at image boundaries.

Multiplex Preprocessing#

Use kind="complete" to retain measured channels, qc_filtered for channels passing QC, or uniprot_filtered for QC-passing channels with accepted UniProt identifiers. Channel availability is tracked separately from intensities. Intensities are standardized with identity preprocessing or statistics-backed quantile clipping, optionally with a log1p transform; see Standardization.

Multimodal and Multi-cohort Access#

Composed datasets expose the union of tissue IDs across their modalities. Query get_modalities_of_tissue(tissue_id) before assuming all modalities are present. The loaders associate records; they do not calculate spatial registration.

SporaDataset samples uniformly from its combined tissue or tile index. Larger cohorts therefore contribute more entries; equal weighting of cohorts or patients requires a separate sampling policy. A split argument selects existing metadata labels; it does not generate train/test splits.

Where to Go Next#