Spatial Deconv

---
# AUTO-GENERATED header from skill.yaml — do not edit by hand.
# Edit skill.yaml, then run: python scripts/generate_skill_md.py <skill_dir>
name: spatial-deconv
description: Load when deconvolving spot-level cell-type proportions on a Visium-style spatial AnnData
  using a labelled scRNA reference (FlashDeconv / Cell2location / RCTD / DestVI / Tangram / others). Skip
  when each spot is a single cell already (Xenium / MERFISH) (use spatial-annotate); tissue-domain detection
  (use spatial-domains).
version: 0.5.0
author: OmicsClaw
license: MIT
emoji: 🧩
tags:
- spatial
- deconvolution
- cell2location
- rctd
- destvi
- stereoscope
- tangram
- spotlight
- card
- flashdeconv
requires:
- anndata
- cell2location
- flashdeconv
- matplotlib
- numpy
- pandas
- scanpy
- scipy
- scvi-tools
- seaborn
- tangram-sc
- torch
---

# spatial-deconv

## When to use

The user has a Visium-style multi-cell-per-spot spatial AnnData PLUS a
labelled scRNA reference AnnData and wants per-spot cell-type
proportions. Eight backends:

- `flashdeconv` (default) — ultra-fast O(N) CPU sketching. No GPU.
- `cell2location` — Bayesian deep learning with spatial priors
  (`--cell2location-n-epochs`, `--cell2location-detection-alpha`,
  `--cell2location-n-cells-per-spot`). Requires `scvi-tools` +
  `cell2location` + `torch`.
- `rctd` — Robust Cell Type Decomposition (R / `spacexr`).
- `destvi` — multi-resolution VAE (`--destvi-n-epochs`,
  `--destvi-n-hidden` / `--destvi-n-latent` / `--destvi-n-layers`).
  Requires `scvi-tools` + `torch`.
- `stereoscope` — two-stage probabilistic VAE
  (`--stereoscope-learning-rate`). Requires `scvi-tools` + `torch`.
- `tangram` — gradient-based mapping (`--tangram-n-epochs`,
  `--tangram-learning-rate`). Requires `tangram`.
- `spotlight` — NMF-based with marker-gene priors
  (`--spotlight-n-top`, `--spotlight-min-prop`, `--spotlight-weight-id`).
- `card` — Conditional Autoregressive R-based deconvolution.

For single-cell-per-spot platforms (Xenium / MERFISH) use
`spatial-annotate`. For tissue-region detection (no reference needed)
use `spatial-domains`.

## Inputs & Outputs

<!-- AUTO-GENERATED from skill.yaml (interface) — do not edit by hand. Regenerate: python scripts/generate_skill_md.py <skill_dir> -->

**Inputs**

- File types: `.h5ad`
- Requires a preprocessed AnnData (`X` normalised, PCA/neighbours present)
- Expects `obsm`: `spatial`

**Outputs**

- `tables/card_proportions.csv`
- `tables/card_refined_proportions.csv`
- `tables/celltype_diversity.csv`
- `tables/deconv_run_summary.csv`
- `tables/deconv_spatial_points.csv`
- `tables/deconv_spot_metrics.csv`
- `tables/deconv_umap_points.csv`
- `tables/dominant_celltype.csv`
- `tables/dominant_celltype_counts.csv`
- `tables/mean_proportions.csv`
- `tables/proportions.csv`
- `tables/rctd_proportions.csv`
- `tables/ref_celltypes.csv`
- `tables/ref_counts.csv`
- `tables/ref_meta.csv`
- `tables/spatial_coords.csv`
- `tables/spatial_counts.csv`
- `tables/spotlight_proportions.csv`
- `figures/assignment_margin_distribution.png`
- `figures/assignment_margin_spatial.png`
- `figures/celltype_diversity.png`
- `figures/dominant_celltype.png`
- `figures/dominant_celltype_distribution.png`
- `figures/mean_proportions.png`
- `figures/spatial_proportions.png`
- `figures/umap_proportions.png`
- `processed.h5ad`
- `report.md`
- `result.json`
- Processed AnnData (`saves_h5ad`) — adds `obs`: `deconv_{method}_dominant_cell_type`, `deconv_{method}_dominant_proportion`; `obsm`: `deconvolution_{method}`

## Flow

1. Load spatial AnnData + reference (`--reference` `.h5ad` with cell-type labels). For `flashdeconv` reference is optional (uses internal heuristic).
2. `parser.error` validates `--input` / `--reference` / numeric flags (lines `:300-350`).
3. Dispatch to method; method-specific kwargs from `METHOD_PARAM_DEFAULTS`.
4. Build proportions matrix; compute per-spot dominant cell-type + Shannon diversity.
5. Save `processed.h5ad` (with `obsm["proportions"]`), tables, figures, `report.md`, `result.json`.

## Gotchas

- **All input + parameter validation goes through `parser.error` (exit code 2).** `spatial_deconv.py:300` for missing `--input`; `:302` for missing input path; `:306` for missing `--reference` on methods that need one; `:308` for missing reference path; `:335` and `:338-350` for per-method numeric flag validation. Wrappers expecting `ValueError` need to catch exit-2.
- **`--reference` is required for almost every method** (only `flashdeconv` can run without it). `spatial_deconv.py:306` raises `parser.error(f"--reference is required for method '{args.method}'")` for the others. The reference must have cell-type labels in `obs` (key auto-resolved from common names).
- **Stored deconvolution-matrix lookup raises post-load.** `spatial_deconv.py:594` raises `ValueError(f"Stored deconvolution matrix '<prop_key>' not found in adata.obsm")` when re-rendering an already-deconvolved AnnData and the obsm key is missing. Used by the replot workflow.
- **`obsm["spatial"]` ↔ `obsm["X_spatial"]` sync at `:534-536`.** Same dual-key pattern as spatial-domains — both keys exist after a run.
- **`--cell2location-detection-alpha` must be > 0.** `spatial_deconv.py:340` enforces. The cell2location default (typically 200) is a regularisation strength — lower values mean less spatial smoothing.
- **`--destvi-dropout-rate` is in `[0, 1)`, not `[0, 1]`.** `spatial_deconv.py:342` enforces strict-less-than-1. dropout=1 would zero out everything.
- **R-backed methods (`rctd`, `card`) need a working R env.** Both rely on R packages (`spacexr` for RCTD, `CARD` for CARD). Missing R deps surface as ImportError at runtime, not at preflight.

## Key CLI

```bash
# Demo (synthetic; flashdeconv default)
python omicsclaw.py run spatial-deconv --demo --output /tmp/spatial_deconv_demo

# FlashDeconv (CPU-only, fastest)
python omicsclaw.py run spatial-deconv \
  --input visium.h5ad --reference scrna_atlas.h5ad --output results/ \
  --method flashdeconv

# Cell2location (Bayesian, GPU)
python omicsclaw.py run spatial-deconv \
  --input visium.h5ad --reference scrna_atlas.h5ad --output results/ \
  --method cell2location --cell2location-n-epochs 30000 \
  --cell2location-n-cells-per-spot 8 --cell2location-detection-alpha 200

# RCTD (R-backed)
python omicsclaw.py run spatial-deconv \
  --input visium.h5ad --reference scrna_atlas.h5ad --output results/ \
  --method rctd --rctd-mode full

# Tangram (gradient mapping)
python omicsclaw.py run spatial-deconv \
  --input visium.h5ad --reference scrna_atlas.h5ad --output results/ \
  --method tangram --tangram-n-epochs 1000 --tangram-learning-rate 0.1

# CARD (Conditional Autoregressive R deconv)
python omicsclaw.py run spatial-deconv \
  --input visium.h5ad --reference scrna_atlas.h5ad --output results/ \
  --method card
```

## See also

- `references/parameters.md` — every CLI flag, per-method tunables
- `references/methodology.md` — when each backend wins; reference-data prep
- `references/output_contract.md` — `obsm["proportions"]` / `obs["dominant_celltype"]` schema
- Adjacent skills: `spatial-preprocess` (upstream — produces the input AnnData), `sc-cell-annotation` (upstream — labels the scRNA reference passed via `--reference`), `spatial-annotate` (parallel — for single-cell-per-spot platforms NOT spot deconvolution), `spatial-domains` (parallel — finds tissue regions WITHOUT a reference; complementary to deconv), `spatial-de` (downstream — DE between deconv-defined dominant-celltype groups)