/spatial-transcriptomics-cell-type-annotation

name: "spatial-transcriptomics-cell-type-annotation"
description: "Spatial transcriptomics cell type annotation for single-cell-resolution platforms (Xenium, MERFISH, CosMx, SeqFISH): CELLxGENE reference download, Harmony label transfer, per-cluster marker evidence naming lineages then subtypes, spatial niches. Visium/Slide-seq spots: GPU -> spatial-transcriptomics-deconvolution-cell2location; CPU -> spatial-mapping-tangram (cell types: per-spot proportions); no reference -> spatial-domain-detection (regions: domains from markers). Beyond labels (microenvironment, arrangement, spatial patterns): read spatial-transcriptomics-analysis-squidpy before asking the user."
license: "CC-BY-4.0"

Spatial Cell Type Annotation (single-cell resolution)

Overview

Annotates cells and tissue niches in imaging-based spatial data, where each observation is one segmented cell. A tissue- and state-matched scRNA-seq reference is pulled from CELLxGENE, its labels are transferred with Harmony, and each cluster is then named from a table that puts its markers next to the transferred labels. Output: an AnnData with per-cell labels, confidence and niches, plus the evidence table behind every name.

Check the platform before anything else:

| Signal | Single-cell resolution -> this skill | Spot-based -> `spatial-transcriptomics-deconvolution-cell2location` | |---|---|---| | Genes | ~100-5,000 targeted panel | ~18,000-33,000 (whole transcriptome) | | Files | `cell_feature_matrix.h5`, `cells.csv(.gz)`, `experiment.xenium` | `filtered_feature_bc_matrix.h5`, `spatial/tissue_positions*.csv` | | Platforms | Xenium, MERFISH, CosMx, SeqFISH | Visium, Visium HD bins, Slide-seq, ST |

A spot mixes several cells; naming each spot with one label is wrong, so a Visium request to "annotate cell types" goes to deconvolution.

When to Use

• Naming the cell types in a Xenium, MERFISH, CosMx or SeqFISH section
• Transferring labels from a published scRNA-seq atlas onto a targeted gene panel
• Checking whether transferred labels are supported by the panel's own markers
• Finding tissue niches (tumour core, immune-rich stroma) from neighbourhood composition
• Preparing labels for spatial cell-cell communication (`spatial-transcriptomics-cell-cell-communication`)
• Use `spatial-transcriptomics-deconvolution-cell2location` instead when the data is Visium or another spot-based platform
• For dissociated scRNA-seq without coordinates, use `cell-type-annotation` instead

Prerequisites

• **Input**: Xenium output folder (`cell_feature_matrix.h5`, `cells.csv.gz`) or an `.h5ad` with raw counts and `obsm["spatial"]`
• **Network**: CELLxGENE Discover API and Census (public, no key)
• **Python packages**: `scanpy`, `cellxgene-census`, `harmonypy`, `scikit-learn`, `squidpy` (niches only)

# Install only what `import` reports missing. 
pixi add --pypi harmonypy cellxgene-census   # scanpy, scikit-learn are usually present
pixi add --pypi squidpy                      # Step 7 (niches) only

Pre-flight Interview

decisions:
  - id: D1
    param: STATE
    kind: required
    source: user
    ask: "Which tissue, and in what state (healthy, or which tumour or disease)?"
    default: null

  - id: D2
    param: referenceSource
    kind: required
    source: user
    ask: "Do you have a matched scRNA/snRNA-seq reference (h5ad with raw counts and a cell type column), or should I search public data (CELLxGENE) for one?"
    default: null

  - id: D3
    param: annotationRoute
    kind: required
    source: user
    ask: "Transfer labels from a reference (recommended, slow; CellTypist only if installing the transfer tools fails), run CellTypist (fast, not recommended: less accurate on this panel), or name clusters from markers only?"
    default: null

  - id: D4
    param: MIN_COUNTS
    kind: optional
    source: user
    ask: "Keep cells with at least how many transcripts?"
    default: "10"

Ask D1-D3 together, and give each D3 option its cost:

• **Reference transfer (recommended, slow)**: Harmony + classifier (Step 5),

Tangram or scANVI, installed at run time. Fetching a public reference is not guaranteed: install, query and download take minutes or longer, and the dataset can be missing from Census or exhaust memory (Step 4). Transfer is also long: on ~154k cells, UMAP took ~45 s and Leiden ~2 min before Harmony and training even start. Install the transfer tools first, even though CellTypist is pre-installed. Only if that install or import fails, stop, tell the user the error, then fall back to CellTypist with the caveat below and say so in the result.

• **CellTypist (fast, not recommended)**: pre-installed, but its models are

trained on whole-transcriptome scRNA-seq, so on a targeted panel only the overlapping genes are used and labels are less accurate. State this whenever its labels are reported, and check them with markers (Step 6).

• **Markers only**: no reference; see the Marker-Only recipe.

When the user asks whether anything else must be uploaded, answer from D2: the Xenium output is enough to start, and a matched reference of their own is the fastest and most reliable route. Never describe the reference fetch or the transfer as immediate or guaranteed.

Workflow

Step 1: Load Xenium Output

import pandas as pd
import scanpy as sc

XENIUM_DIR = "path/to/xenium_outs"  # folder with cell_feature_matrix.h5 + cells.csv.gz

adata = sc.read_10x_h5(f"{XENIUM_DIR}/cell_feature_matrix.h5", gex_only=False)
# Control probes/codewords are not genes; keep Gene Expression only.
adata = adata[:, adata.var["feature_types"] == "Gene Expression"].copy()
cells = pd.read_csv(f"{XENIUM_DIR}/cells.csv.gz", index_col="cell_id")
adata.obs = adata.obs.join(cells, how="left")
adata.obsm["spatial"] = adata.obs[["x_centroid", "y_centroid"]].to_numpy()  # microns

print(adata)
print(f"panel: {adata.n_vars} genes; median transcripts/cell: {adata.obs['total_counts'].median():.0f}")
``