Skip to content

Tutorials

A complete analysis, in order, on one small dataset. Every notebook on this page was executed against that data before it was published — the numbers and figures you see are what the code actually produced.

Each notebook stands on its own: they all start from the same .h5ad and recompute what they need, so you can drop into any of them.

Setup
Demo data What the example dataset is and how to get it.
Build the cell table From raw mcmicro quantification to an AnnData.

Cell phenotyping

Two routes to the same destination — cells with labels.
Prior-knowledge phenotyping Gates plus a hierarchical workflow table. Reproducible across datasets.
Unsupervised clustering Let the data group itself, then work out what each group is.
Add ROIs Get regions of interest into the object.
Explore cell types Composition, proportions, and differences between samples.

Spatial analysis
Distance measurement How far each cell type sits from every other.
Co-occurrence analysis Which pairs are adjacent more often than chance.
Proximity scores How much of a sample is in an interaction zone.
Search patterns Find everywhere that resembles a region you picked out.

Cellular neighbourhoods

Beyond pairs, to the recurring multi-cell structures that make up tissue.
Latent motifs Neighbourhood composition, clustered or factorised (LDA, NMF).
Neighbourhood lag The same idea over marker expression rather than cell type.

SCIMAP Pro extras

Neither of these has a scimap equivalent.
SpatialData workflow Convert to a .zarr store and analyse it in place.
Streaming large files Run out of core against a file that will not fit in memory.

Helpers
Export data CSV, .h5ad, figures, .zarr.
Other helpers Relabelling, tidying, batch correction, k-NN graphs.

Demo data

Everything runs on one exemplar mcmicro image: 11,201 cells, 9 markers, with centroids and morphology. Small enough that a whole analysis takes seconds; big enough that the spatial statistics mean something.

It is not shipped inside the package — the raw image alone exceeds GitHub's 100 MB file limit — so it is downloaded separately into example_data/ at the root of the repository checkout:

example_data/
├── adata_scimap.h5ad        the prepared cell table
├── manual_gates.csv         hand-picked gates, one column per image
├── phenotype_workflow.csv   the hierarchical gating table
├── quantification/          the raw mcmicro output
├── registration/            the registered OME-TIFF
└── segmentation/            the cell masks

Every notebook opens with the same cell, which finds the directory whether you run from the repository root or from docs/tutorials/nbs/:

DATA = next(
    path for path in (Path("example_data"), Path("../../../example_data"))
    if path.exists()
)

Point it somewhere else if your copy lives elsewhere.

What is not executed here

Three things open a window, so they cannot run in a published notebook or in any headless environment. They are shown as code you can copy, and marked as such:

Where the demo dataset cannot support a demonstration — it is one image, and some functions compare groups — the notebook says so and builds a clearly labelled synthetic split rather than implying the result is biological.

Coming from scimap?

Start with Migrating from scimap. These tutorials follow the same arc as scimap's, so a chapter you know has a counterpart here, but every call has been rewritten for the scimappro API.