spatial-annotate

name	spatial-annotate
description	Cell type annotation for spatial transcriptomics data using marker-based scoring, Tangram mapping, scANVI transfer, or CellAssign probabilistic models.
version	0.2.0
author	SpatialClaw
license	MIT
tags	["spatial","annotation","cell-type","tangram","scanvi","cellassign","marker-genes"]
metadata	{"omicsclaw":{"domain":"spatial","requires":{"bins":"[Truncated]","env":"[Truncated]","config":"[Truncated]"},"emoji":"🏷️","homepage":"https://github.com/zhou-1314/OmicsClaw","os":["macos","linux"],"install":["[Truncated]"],"trigger_keywords":["cell type annotation","annotate cell types","Tangram","scANVI","CellAssign","marker genes"]}}

🏷️ 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

Format	Extension	Required Fields	Example
AnnData (preprocessed)	.h5ad	X, obsm["spatial"], clusters	preprocessed.h5ad
Reference (for tangram/scanvi)	.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