/spatial-transcriptomics-deconvolution-cell2location

name: "spatial-transcriptomics-deconvolution-cell2location"
description: "Visium and other spot-based spatial transcriptomics (Slide-seq, ST) cell type deconvolution with cell2location: load Space Ranger output, get a tissue-matched scRNA-seq reference from CELLxGENE, learn cell type signatures, estimate cell type abundance per spot with posterior uncertainty, and check the maps against marker genes. Default route for 'annotate cell types' on Visium when a GPU is available. Limits: needs a tissue- and state-matched reference; the default 30000 epochs take hours on CPU, so without a GPU it runs only with fewer epochs (exploratory maps) and can exceed one execution call's time limit. For fast per-spot proportions on CPU use spatial-mapping-tangram (clusters mode); for single-cell-resolution data (Xenium, MERFISH, CosMx) use spatial-transcriptomics-cell-type-annotation."
license: "CC-BY-4.0"

Spot Deconvolution with cell2location

Overview

Each Visium spot (55 um) holds several cells, so cell types are reported as an abundance per spot, not one label per spot. cell2location learns a signature per cell type from a scRNA-seq reference, then explains every spot's counts as a mixture of those signatures. Output: estimated cell counts and proportions per spot and type, maps on the tissue, and a marker check of each map.

When to Use

• Asked to "annotate cell types" or "find where cell types are" on Visium, Slide-seq or ST data
• Mapping a published scRNA-seq atlas onto a spot-based section
• Comparing cell type composition between tissue regions or sections
• Producing per-spot compositions for downstream niche or communication analysis
• Getting abundance estimates with posterior uncertainty (5% quantile)
• Use `spatial-transcriptomics-cell-type-annotation` instead when each observation is one cell (Xenium, MERFISH, CosMx)
• Use `spatial-mapping-tangram` (constrained deconvolution route) instead when you need single cells placed on segmented nuclei of the histology image

Prerequisites

• **Input**: Space Ranger output (`filtered_feature_bc_matrix.h5` and the `spatial/` folder) with raw counts
• **Reference**: scRNA-seq with raw counts and `obs["cell_type"]` (Step 2 fetches one)
• **Compute**: GPU strongly preferred. On CPU the spatial model (Step 4) needs fewer epochs than the

default, chosen by the timing probe there; the reference model (Step 3) takes minutes

• **Python packages**: `cell2location` (pulls torch, scvi-tools, pyro; large), `scanpy`

# 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 scanpy cell2location

Pre-flight Interview

decisions:
  - id: D1
    param: STATE
    kind: required
    source: user
    ask: "Which tissue is this, 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 scRNA/snRNA-seq reference from the same tissue and state (h5ad with raw counts and 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 reference column holds the cell types, and at what level: major lineages or fine subtypes?"
    default: null

  - id: D4
    param: COMPUTE_ROUTE
    kind: required
    source: user
    ask: "Without a GPU, cell2location runs only with fewer training epochs (exploratory maps, still long). Run it that way, or get per-spot proportions quickly with Tangram (clusters mode)?"
    default: "cell2location with MAX_EPOCHS from the Step 4 timing probe, reported as exploratory"

  - id: D5
    param: N_CELLS_PER_SPOT
    kind: required
    source: user
    depends_on: [D1]
    ask: "About how many nuclei does one spot hold in this tissue? I can use the tutorial value of 30 if you do not know."
    default: "30"

  - id: D6
    param: SAMPLE_KEY
    kind: required
    source: data
    skip_if: "a single section"
    ask: "There are several sections: fit them in one model (shared cell type signatures, per-section sensitivity) or each on its own?"
    default: "one model with batch_key = section"

  - id: D7
    param: DETECTION_ALPHA
    kind: optional
    source: user
    ask: "Does RNA detection vary strongly across the slide (uneven tissue quality)?"
    default: "20 (uneven detection); 200 when detection is even"

  - id: D8
    param: REF_BATCH_KEY
    kind: optional_conditional
    source: data
    depends_on: [D2]
    ask: "The reference pools several donors or studies: correct the signatures for that column?"
    default: "batch_key = donor_id when the reference has more than one donor"

Ask D1, D2 and D4 together, with D6 when there is more than one section. The tissue and state come from the user: a sample name will not be found in public databases, so do not search the web for it. Spot data cannot tell a tumour from healthy tissue reliably; if the user does not know, propose a tissue from the top marker genes and ask them to confirm. If D4 picks Tangram, use `spatial-mapping-tangram` with `MODE = "clusters"` and the same reference.

Workflow

Step 1: Load Visium Output

import os
import numpy as np
import pandas as pd
import scanpy as sc

H5 = "path/to/filtered_feature_bc_matrix.h5"
SPATIAL_DIR = "path/to/spatial"

st = sc.read_10x_h5(H5)
st.var_names_make_unique()
if os.path.exists(f"{SPATIAL_DIR}/tissue_positions.csv"):           # Space Ranger >= 2.0
    pos = pd.read_csv(f"{SPATIAL_DIR}/tissue_positions.csv", index_col=0)
else:                                                                  # older, no header
    pos = pd.read_csv(f"{SPATIAL_DIR}/tissue_positions_list.csv", header=None, index_col=0,
                      names=["barcode", "in_tissue", "array_row", "array_col",
                             "pxl_row_in_fullres", "p