/spatial-mapping-tangram

name: "spatial-mapping-tangram"
description: "Tangram (tangram-sc) mapping of scRNA-seq onto spatial transcriptomics (Visium, Slide-seq, MERFISH, Xenium), one skill for every Tangram task: marker training genes, cells/clusters/constrained mode, per-spot cell type proportions, held-out gene validation (training scores, compare_spatial_geneexp, AUC, k-fold CV), imputation of unmeasured or dropout genes (project_genes; gimVI alternative), and Visium deconvolution into segmented nuclei with the tissue image (squidpy watershed, target_count, deconvolve_cell_annotations). Task-specific routes follow the main workflow. For probabilistic spot abundances with uncertainty use spatial-transcriptomics-deconvolution-cell2location."
license: "CC-BY-4.0"

Spatial Mapping with Tangram

Overview

Tangram fits a cell-by-spot probability matrix so that the expression of the mapped single cells reproduces the spatial expression of shared training genes. Every Tangram task starts from that matrix: per-spot cell type proportions, predicted expression of genes the panel did not measure, and, with a histology image, a cell type for every segmented nucleus. The mapping always converges to something, so this skill validates it on genes held out of training before any result is reported. The reference must come from the same tissue and state as the section and share informative genes with it.

| Task | Route | |---|---| | Cell type proportions per spot / labels on single-cell-resolution data | Workflow Steps 1-7 | | Predict unmeasured or dropout-affected genes | Steps 1-6, then Route: Gene Imputation | | One cell type per segmented nucleus (Visium + full-resolution image) | Route: Nuclei Deconvolution (replaces Step 1, then Steps 2-3, Nucleus 2-4, Step 6) | | Deeper quality checks (k-fold CV, cells vs clusters, seed stability) | After Step 6, Route: Advanced Validation |

All routes are in `## Task Routes` below the Workflow.

When to Use

• Placing scRNA-seq cell types onto a Visium, Slide-seq, MERFISH or Xenium section
• Getting per-spot cell type proportions without a histology image
• Showing the spatial pattern of genes a targeted panel did not measure, or that Visium lost to dropout
• Labelling every segmented nucleus in a Visium spot when the full-resolution image is available
• Deciding whether a Tangram mapping is good enough to report, from held-out genes
• Mapping one reference onto several sections for a consistent comparison
• Use `spatial-transcriptomics-deconvolution-cell2location` instead when you need posterior uncertainty for spot abundances
• For label transfer on Xenium/MERFISH as the primary annotation, use `spatial-transcriptomics-cell-type-annotation` (Tangram labels are a second opinion)

Prerequisites

• **Spatial data**: AnnData with `obsm["spatial"]` (Visium: Step 1 of

`spatial-transcriptomics-deconvolution-cell2location`; Xenium: Step 1 of `spatial-transcriptomics-cell-type-annotation`)

• **Reference**: scRNA-seq with a cell type column, tissue- and state-matched

(search/download: Steps 3-4 of `spatial-transcriptomics-cell-type-annotation`, with `GENES = None` and `MAX_PER_TYPE = 300` - markers are ranked over every gene)

• **Python packages**: `tangram-sc`, `squidpy`, `scanpy`. They are not

pre-installed; `tangram-sc` pulls PyTorch, whose Linux wheel brings CUDA libraries (several GB). The first install takes minutes; say so to the user before starting.

• **Compute**: CPU works. `mode="cells"` holds a reference-cells x spots

matrix plus optimiser state (roughly 16 bytes per entry): ~2 GB for 30k cells x 5k spots, but tens of GB for single-cell-resolution sections with 100k+ cells. Use `mode="clusters"` or subsample there (Step 4 prints the estimate).

# Install only what `import` reports missing. `--pypi` keeps the env's scanpy/numba
# stack; a conda add can swap it and bare pip can shadow it.
pixi add --pypi squidpy scanpy tangram-sc

Pre-flight Interview

decisions:
  - id: D1
    param: TASK
    kind: required
    source: user
    ask: "What should the mapping give you: cell type proportions per spot (or labels per cell), predicted expression of genes the panel did not measure, or a cell type for every nucleus seen in the tissue image?"
    default: "cell type proportions"

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

  - id: D3
    param: CELL_TYPE_KEY
    kind: required
    source: data
    depends_on: [D2]
    ask: "Which column of the reference holds the cell types to map?"
    default: null

  - id: D4
    param: MODE
    kind: required
    source: user
    depends_on: [D1]
    ask: "Do the reference and the spatial section come from the same specimen (or a biological replicate), or from different samples/studies?"
    default: "clusters when from different samples or when the Step 4 memory estimate exceeds the sandbox; cells otherwise; constrained for the nucleus task"

  - id: D5
    param: density_prior
    kind: required
    source: data
    depends_on: [D1]
    ask: "This section looks like <spot data / single-cell-resolution data>: weight each location by its RNA count, or treat every location as one cell?"
    default: "per-spot total counts on spot data; uniform on single-cell-resolution data; nucleus counts for the nucleus task"

  - id: D6
    param: TARGETS
    kind: required
    source: user
    depends_on: [D1]
    skip_if: "TASK is not gene imputation"
    ask: "Which genes or gene signatures do you want predicted on the tissue?"
    default: null

  - id: D7
    param: STAIN
    kind: required
    source: data
    depends_on: [D1]
    skip_if: "TASK is not the nucleus task"
    ask: "Is the full-resolution image H&E (dark nuclei) or fluorescent DAPI (bright nuclei)?"
    default: null

  - id: D8