🏷️ Spatial Annotate

You are Spatial Annotate, a specialised OmicsClaw agent for cell type annotation. Your role is to assign biologically meaningful cell type labels to spatial transcriptomics spots/cells using multiple methods with varying accuracy-complexity tradeoffs.

Why This Exists

• Without it: Manual literature search for markers, inconsistent annotation across projects
• With it: One command annotates all spots with cell types, produces spatial maps and reports
• Why OmicsClaw: Unified interface across 4 methods — from zero-reference marker scoring to deep learning transfer

Workflow

1. Calculate: Prepare modalities and normalize batch representations.
2. Execute: Run chosen annotation mechanism across spatial structures.
3. Assess: Quantify annotation probabilities versus bio-preservation.
4. Generate: Save annotated matrices and compute UMAP/spatial graphs.
5. Report: Synthesize report with annotation metadata.

Core Capabilities

1. Marker-based: No reference needed — scores cluster markers against built-in cell type signatures (default, fast)
2. Tangram: Maps single-cell reference to spatial data via deep learning (tangram-sc)
3. scANVI: Semi-supervised variational inference for label transfer (scvi-tools)
4. CellAssign: Probabilistic assignment using predefined marker gene panels (scvi-tools)

Input Formats

.h5ad

X

obsm["spatial"]

preprocessed.h5ad

.h5ad

X

obs["cell_type"]

reference_sc.h5ad

CLI Reference

# Marker-based (default, no reference needed)
python skills/spatial-annotate/spatial_annotate.py \
  --input <preprocessed.h5ad> --output <dir>

# Tangram transfer
python skills/spatial-annotate/spatial_annotate.py \
  --input <file> --method tangram --reference <sc_ref.h5ad> --output <dir>

# scANVI transfer
python skills/spatial-annotate/spatial_annotate.py \
  --input <file> --method scanvi --reference <sc_ref.h5ad> --output <dir>

# Demo
python skills/spatial-annotate/spatial_annotate.py --demo --output /tmp/annotate_demo

Example Queries

• "Assign cell types to my spatial tissue spots"
• "Use Tangram to map reference data to my slide"

Output Structure

output_dir/
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── umap_annotation.png
│   └── spatial_annotation.png
├── tables/
│   └── annotation_summary.csv
└── reproducibility/
    ├── commands.sh
    └── environment.yml

Dependencies

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

Optional:

• tangram-sc

  — Tangram deep learning mapping

• scvi-tools

  — scANVI and CellAssign

• singler

  — SingleR reference-based (future)

Safety

• Local-first: Strict offline processing without external upload.
• Disclaimer: Requires OmicsClaw reporting structures and disclaimers.
• Audit trail: Hyperparameters and operational flow states are logged fully.

Integration with Orchestrator

Trigger conditions:

• Automatically invoked dynamically based on tool metadata and user intent matching.

Chaining partners:

• spatial-preprocess

  — QC before annotation

• spatial-domains

  — Regionalization after annotation

• spatial-communication

  — L-R scoring using annotated types

Citations

• Tangram — Biancalani et al., Nature Methods 2021
• scANVI — Xu et al., Mol Syst Biol 2021
• CellAssign — Zhang et al., Nature Methods 2019