Technology-specific advice

Harpy is designed to support all spatial technologies at single-cell resolution, with a focus on spatial proteomics and targeted/untargeted transcriptomics.

Use this page to pick the right readers, example datasets, and recommended steps for each technology. Each section links to the relevant API objects and tutorials.

Quick links:

• API reference

---

Spatial proteomics platforms

Readers

• MACSima: harpy.io.macsima()

Example datasets

• MACSima: harpy.datasets.macsima_colorectal_carcinoma(), harpy.datasets.macsima_tonsil(), harpy.datasets.macsima_example().

• CODEX: harpy.datasets.codex_example().

• MIBI-TOF: harpy.datasets.mibi_example().

• Vectra Polaris: harpy.datasets.vectra_example().

Segmentation

We recommend Cellpose (version > 4.0) or InstanSeg via harpy.im.segment() with harpy.im.cellpose_callable() or harpy.im.instanseg_callable().

When Cellpose is used for segmentation, multiple masks can be merged using harpy.im.merge_labels() and harpy.im.match_labels_to_reference().

Create the AnnData table

Use harpy.tb.allocate_intensity() to compute mean intensities (or other statistics) per marker and instance.

Shallow feature extraction

Use harpy.tb.add_feature_matrix() to compute per-instance feature matrices from labels and optional image data, and store the resulting per-channel intensity and morphology features in a table’s .obsm. This is the recommended format for integration with napari-harpy.

Custom embeddings

Use harpy.tb.featurize() to generate cell embeddings with a user-provided computer vision or foundation model.

Tutorials

• MACSima: Segmentation with Cellpose, feature extraction and Leiden clustering; Computational benchmark.

• Vectra Polaris: Segmentation with InstanSeg.

• CODEX: Creating cell embeddings; Generating single-cell representations and intergration with PyTorch.

• MIBI-TOF: Pixel and cell clustering with FlowSOM.

---

Imaging based Spatial transcriptomics platforms

Readers

• Xenium and Merscope: harpy.io.xenium(), harpy.io.merscope()

• Transcripts only:

  • Merscope: harpy.io.read_merscope_transcripts()

  • Xenium and CosMx: harpy.io.read_transcripts()

  • Resolve: harpy.io.read_resolve_transcripts()

Example datasets

• Xenium: harpy.datasets.xenium_human_lung_cancer(), harpy.datasets.xenium_human_ovarian_cancer()

• Merscope: harpy.datasets.merscope_mouse_liver()

• Resolve: harpy.datasets.resolve_example()

Segmentation

We recommend Cellpose via harpy.im.segment() with harpy.im.cellpose_callable(). See the harpy.im.segment() docstring for an example.

For multi-modal segmentation, use harpy.im.merge_labels() or harpy.im.merge_labels_nuclei() (tutorial coming soon).

Create the AnnData table

Use harpy.tb.allocate() to create a count matrix from a segmentation mask and detected transcripts.

Tutorials

• Xenium: Human Ovarian Cancer, Scalable Spatial Transcriptomics Analysis with Harpy.

• Xenium: Human Ovarian Cancer, full dataset.

• Resolve: How to start with targeted transcriptomics and how to work with multiple coordinate systems.

• Merscope: Integration of annotations.

• CosMx: coming soon

---

Sequencing based Spatial transcriptomics platforms

Readers

• Visium and VisiumHD: harpy.io.visium(), harpy.io.visium_hd()

• Transcripts only:

  • BGI Stereo-seq: harpy.io.read_stereoseq_transcripts()

Example datasets

• VisiumHD: harpy.datasets.visium_hd_example(), harpy.datasets.visium_hd_example_custom_binning()

Segmentation

For custom segmentation on H&E, use Cellpose (version > 4.0) via harpy.im.segment() with harpy.im.cellpose_callable().

Custom binning

• Binning with a custom segmentation mask or raster: harpy.tb.bin_counts()

• Create a custom raster grid (tessellation): harpy.im.add_grid_labels()

Tutorials

Coming soon.