🧩 Spatial Deconv

You are Spatial Deconv, the OmicsClaw skill for estimating per-spot cell type composition from a spatial transcriptomics dataset plus a single-cell reference. The wrapper keeps output structure standardized, but the parameter surface is now method-specific instead of pretending that all deconvolution methods have the same scientific knobs.

Why This Exists

Without it: users have to remember eight different APIs, matrix assumptions, R/Python runtime differences, and incompatible output formats.
With it: one command runs a method-correct deconvolution workflow and exports consistent proportion tables, figures, and reproducibility metadata.
Why OmicsClaw: the wrapper exposes real method-specific controls, preserves a stable output contract, and adds guardrail documents for parameter explanation before execution.

Core Capabilities

FlashDeconv: ultra-fast sketching-based deconvolution with public sketch and spatial-regularization controls.
Cell2location: Bayesian spatial mapping with N_cells_per_location and detection_alpha.
RCTD: R / spacexr count-based decomposition with public doublet_mode.
DestVI: scvi-tools VAE-based deconvolution with exposed CondSCVI architecture controls.
Stereoscope: scvi-tools two-stage probabilistic deconvolution with separate RNA and spatial training budgets.
Tangram: non-negative expression mapping with public mode, num_epochs, and learning_rate.
SPOTlight: R-based NMF deconvolution with public weight_id, n_top, model, min_prop, and scale.
CARD: spatial-correlation-aware R method with optional imputation and refined proportion export.
Standard Python gallery: emits a recipe-driven deconvolution gallery with overview, diagnostic, supporting, and uncertainty panels backed by the shared skills/spatial/_lib/viz layer.
Figure-ready exports: writes figure_data/ CSVs plus a gallery manifest so downstream Python or R plotting code can restyle the same run without recomputing deconvolution.
Structured exports: report, result JSON, processed h5ad, tables, gallery figures, figure data, and reproducibility helpers.

Input Formats

Format	Extension	Required Fields	Example
Spatial AnnData	`.h5ad`	`X`, `obsm["spatial"]`	`processed.h5ad`
Reference AnnData	`.h5ad`	`X`, `obs["cell_type"]` or other label column	`reference_sc.h5ad`

Input Matrix Convention

Different deconvolution methods assume different matrix representations:

Method	Main Expression Input	Notes
`cell2location`	raw counts (`layers["counts"]`, `raw`, or counts in `X`)	Count model; current wrapper restores counts when possible
`rctd`	raw counts	Requires spatial coordinates and enough reference cells per type
`destvi`	raw counts	Count-based scvi model on shared genes
`stereoscope`	raw counts	Count-based scvi model on shared genes
`card`	raw counts	Requires spatial coordinates; optional imputation step
`tangram`	normalized, non-negative expression in `adata.X`	Do not pass scaled / z-scored matrices with negative values
`spotlight`	normalized, non-negative expression	Current wrapper builds marker weights and forwards SPOTlight args
`flashdeconv`	flexible in current wrapper	Keep gene identifiers aligned and spatial coordinates present

Important:

Count-based methods should not be described as valid on scaled or centered matrices.
Tangram and SPOTlight should not be run on matrices containing negative values.
All methods require enough shared genes between spatial and reference datasets.

Workflow

Load: read the spatial h5ad plus the single-cell reference.
Validate: check cell type labels, shared genes, matrix assumptions, and method-specific CLI parameters.
Run the selected backend.
Standardize outputs: store the method-specific proportion matrix and metadata into processed.h5ad.
Derive summaries: export dominant-cell-type, diversity, assignment-margin, and mean-proportion tables.
Render the standard gallery: build the OmicsClaw narrative gallery with spatial proportion overviews, diversity diagnostics, supporting composition summaries, and uncertainty panels.
Export figure-ready data: write figure_data/*.csv and figure_data/manifest.json for downstream customization.
Report and export: write report.md, result.json, processed.h5ad, tables, gallery figures, and reproducibility helpers.

Visualization Contract

OmicsClaw treats spatial-deconv visualization as a two-layer system:

Python standard gallery: the canonical result layer users should inspect first.
R customization layer: an optional styling and publication layer that reads figure_data/ and does not rerun Cell2location, RCTD, Tangram, or other deconvolution backends.

The standard gallery is declared as a recipe instead of hard-coded plotting branches. Current gallery roles include:

overview: multi-panel spatial proportions and dominant cell-type maps
diagnostic: tissue diversity maps and UMAP composition views
supporting: mean proportion summaries and dominant-type distributions
uncertainty: assignment-margin maps and confidence histograms

CLI Reference

# Default alias used by OmicsClaw
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --output <dir>

# FlashDeconv
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method flashdeconv \
  --flashdeconv-lambda-spatial auto --flashdeconv-sketch-dim 1024 --output <dir>

# Cell2location
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method cell2location \
  --cell2location-n-cells-per-spot 30 --cell2location-detection-alpha 20 --output <dir>

# RCTD
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method rctd \
  --rctd-mode doublet --output <dir>

# DestVI
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method destvi \
  --destvi-condscvi-epochs 300 --destvi-n-epochs 2500 --destvi-n-latent 8 --output <dir>

# Stereoscope
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method stereoscope \
  --stereoscope-rna-epochs 400 --stereoscope-spatial-epochs 400 \
  --stereoscope-learning-rate 0.01 --output <dir>

# Tangram
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method tangram \
  --tangram-mode clusters --tangram-n-epochs 1000 --output <dir>

# SPOTlight
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method spotlight \
  --spotlight-weight-id weight --spotlight-n-top 50 --spotlight-model ns --output <dir>

# CARD with imputation
oc run spatial-deconvolution \
  --input <spatial.h5ad> --reference <ref.h5ad> --method card \
  --card-imputation --card-num-grids 2000 --card-ineibor 10 --output <dir>

# Direct script entrypoint
python skills/spatial/spatial-deconv/spatial_deconv.py \
  --input <spatial.h5ad> --reference <ref.h5ad> --method rctd --output <dir>

Every successful standard OmicsClaw wrapper run, including oc run and conversational skill execution, also writes a top-level README.md and reproducibility/analysis_notebook.ipynb to make the output directory easier to inspect and rerun. Direct script execution primarily produces the skill outputs plus reproducibility/commands.sh.

Example Queries

"Run Cell2location on my spatial data and explain the prior settings before running."
"Use RCTD instead, but tell me whether doublet or full is more appropriate."
"Try Tangram first because my matrix is normalized already."
"Use CARD and also enable imputation."

Output Structure

output_dir/
├── README.md                                 # wrapper mode
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── manifest.json
│   ├── spatial_proportions.png
│   ├── dominant_celltype.png
│   ├── celltype_diversity.png
│   ├── mean_proportions.png
│   ├── dominant_celltype_distribution.png
│   ├── assignment_margin_spatial.png
│   ├── assignment_margin_distribution.png
│   └── umap_proportions.png
├── figure_data/
│   ├── manifest.json
│   ├── proportions.csv
│   ├── deconv_spot_metrics.csv
│   ├── dominant_celltype.csv
│   ├── celltype_diversity.csv
│   ├── mean_proportions.csv
│   ├── dominant_celltype_counts.csv
│   ├── deconv_run_summary.csv
│   ├── deconv_spatial_points.csv
│   ├── deconv_umap_points.csv
│   └── card_refined_proportions.csv          # CARD imputation only
├── tables/
│   ├── proportions.csv
│   ├── dominant_celltype.csv
│   ├── celltype_diversity.csv
│   ├── mean_proportions.csv
│   ├── deconv_spot_metrics.csv
│   ├── dominant_celltype_counts.csv
│   └── card_refined_proportions.csv          # CARD imputation only
└── reproducibility/
    ├── analysis_notebook.ipynb               # wrapper mode
    ├── commands.sh
    ├── environment.txt
    └── r_visualization.sh

The repository also bundles starter R templates under:

skills/spatial/spatial-deconv/r_visualization/
├── README.md
└── deconv_publication_template.R

Dependencies

Required: scanpy, anndata, numpy, pandas, scipy, matplotlib

Optional:

flashdeconv — FlashDeconv Python package
cell2location + scvi-tools + torch — Cell2location
scvi-tools + torch — DestVI and Stereoscope
tangram-sc — Tangram
Rscript + packages spacexr, SPOTlight, CARD — R-based methods

Safety

Local-first: no external upload.
Method-aware matrix assumptions: counts-only and normalized-expression methods are documented separately and should be explained separately to users.
Audit trail: reports, result JSON, and reproducibility scripts keep only the parameters relevant to the chosen method.
Two-layer visualization design: Python plots are the canonical standard gallery; the optional R layer consumes figure_data/ for publication-style refinement without recomputing the science.

Integration with Orchestrator

Trigger conditions:

cell type deconvolution
cell proportion estimation
spatial cell composition

Chaining partners:

spatial-preprocess — preprocessing and count preservation
spatial-domains — summarize tissue domains using deconvolution outputs
spatial-annotate — compare reference-driven annotation with deconvolution proportions

Citations

Cell2location — Kleshchevnikov et al., Nature Biotechnology 2022
RCTD — Cable et al., Nature Biotechnology 2022
DestVI — Lopez et al., Nature Biotechnology 2022
Stereoscope — Andersson et al., Communications Biology 2020
Tangram — Biancalani et al., Nature Methods 2021
SPOTlight — Elosua-Bayes et al., Nucleic Acids Research 2021
CARD — Ma and Zhou, Nature Biotechnology 2022

spatial-deconv

SKILL.mdSkills/spatial/spatial-deconv/SKILL.md