tooluniverse-spatial-transcriptomics

What this skill does

# Spatial Transcriptomics Analysis

Comprehensive analysis of spatially-resolved transcriptomics data to understand gene expression patterns in tissue architecture context. Combines expression profiling with spatial coordinates to reveal tissue organization, cell-cell interactions, and spatially variable genes.

## LOOK UP, DON'T GUESS
When uncertain about any scientific fact, SEARCH databases first rather than reasoning from memory. A database-verified answer is always more reliable than a guess.

## When to Use This Skill

**Triggers**:
- User has spatial transcriptomics data (Visium, MERFISH, seqFISH, etc.)
- Questions about tissue architecture or spatial organization
- Spatial gene expression pattern analysis
- Cell-cell proximity or neighborhood analysis requests
- Tumor microenvironment spatial structure questions
- Integration of spatial with single-cell data
- Spatial domain identification
- Tissue morphology correlation with expression

**Example Questions**:
1. "Analyze this 10x Visium dataset to identify spatial domains"
2. "Which genes show spatially variable expression in this tissue?"
3. "Map the tumor microenvironment spatial organization"
4. "Find genes enriched at tissue boundaries"
5. "Identify cell-cell interactions based on spatial proximity"
6. "Integrate spatial transcriptomics with scRNA-seq annotations"

---

## Core Capabilities

- **Data Import**: 10x Visium, MERFISH, seqFISH, Slide-seq, STARmap, Xenium formats
- **Quality Control**: Spot/cell QC, spatial alignment verification, tissue coverage
- **Normalization**: Spatial-aware normalization accounting for tissue heterogeneity
- **Spatial Clustering**: Identify spatial domains with similar expression profiles
- **Spatial Variable Genes**: Find genes with non-random spatial patterns
- **Neighborhood Analysis**: Cell-cell proximity, spatial neighborhoods, niche identification
- **Integration**: Merge with scRNA-seq for cell type mapping (Cell2location, Tangram, SPOTlight)
- **Ligand-Receptor Spatial**: Map cell communication in tissue context via OmniPath

## Supported Platforms

- **10x Visium**: 55um spots (~50 cells/spot), genome-wide, includes H&E image — most common
- **MERFISH/seqFISH**: Single-cell resolution, 100-10,000 targeted genes, imaging-based
- **Slide-seq/V2**: 10um beads, genome-wide — higher resolution than Visium
- **Xenium**: Single-cell/subcellular, 300+ targeted genes (10x platform)

---

## Workflow Overview

```
Input: Spatial Transcriptomics Data + Tissue Image
    |
    v
Phase 1: Data Import & QC
    |-- Load spatial coordinates + expression matrix
    |-- Load tissue histology image
    |-- Quality control per spot/cell (min 200 genes, 500 UMI, <20% MT)
    |-- Align spatial coordinates to tissue
    |
    v
Phase 2: Preprocessing
    |-- Normalization (spatial-aware methods)
    |-- Highly variable gene selection (top 2000)
    |-- Dimensionality reduction (PCA)
    |-- Spatial lag smoothing (optional)
    |
    v
Phase 3: Spatial Clustering
    |-- Build spatial neighbor graph (squidpy)
    |-- Graph-based clustering with spatial constraints (Leiden)
    |-- Annotate domains with marker genes (Wilcoxon)
    |-- Visualize domains on tissue
    |
    v
Phase 4: Spatial Variable Genes
    |-- Test spatial autocorrelation (Moran's I, Geary's C)
    |-- Filter significant spatial genes (FDR < 0.05)
    |-- Classify pattern types (gradient, hotspot, boundary, periodic)
    |
    v
Phase 5: Neighborhood Analysis
    |-- Define spatial neighborhoods (k-NN, radius)
    |-- Calculate neighborhood composition (squidpy nhood_enrichment)
    |-- Identify interaction zones between domains
    |
    v
Phase 6: Integration with scRNA-seq
    |-- Cell type deconvolution (Cell2location, Tangram, SPOTlight)
    |-- Map cell types to spatial locations
    |-- Validate with marker genes
    |
    v
Phase 7: Spatial Cell Communication
    |-- Identify proximal cell type pairs
    |-- Query ligand-receptor database (OmniPath)
    |-- Score spatial interactions (squidpy ligrec)
    |-- Map communication hotspots
    |
    v
Phase 8: Generate Spatial Report
    |-- Tissue overview with domains
    |-- Spatially variable genes
    |-- Cell type spatial maps
    |-- Interaction networks in tissue context
```

---

## Phase Summaries

### Phase 1: Data Import & QC
Load platform-specific data (scanpy read_visium for Visium). Apply QC filters: min 200 genes/spot, min 500 UMI/spot, max 20% mitochondrial. Verify spatial alignment with tissue image overlay.

### Phase 2: Preprocessing
Normalize to median total counts, log-transform, select top 2000 HVGs. Optional spatial smoothing via neighbor averaging (useful for noisy data but blurs boundaries).

### Phase 3: Spatial Clustering
PCA (50 components) followed by spatial neighbor graph construction (squidpy). Leiden clustering with spatial constraints yields spatial domains. Find domain markers via Wilcoxon rank-sum test.

### Phase 4: Spatially Variable Genes
Moran's I statistic tests spatial autocorrelation: I > 0 = clustering, I ~ 0 = random, I < 0 = checkerboard. Filter by FDR < 0.05. Classify patterns as gradient, hotspot, boundary, or periodic.

### Phase 5: Neighborhood Analysis
Neighborhood enrichment analysis (squidpy) tests whether cell types/domains are co-localized beyond random expectation. Identify interaction zones at domain boundaries using k-NN spatial graphs.

### Phase 6: scRNA-seq Integration
Cell type deconvolution maps single-cell annotations to spatial spots. Methods: Cell2location (recommended for Visium), Tangram, SPOTlight. Produces cell type fraction estimates per spot.

### Phase 7: Spatial Cell Communication

Combine spatial proximity with ligand-receptor databases. Key ToolUniverse tools:
- `OmniPath_get_ligand_receptor_interactions` — 14,000+ L-R pairs from CellPhoneDB, CellChatDB, etc. Use `partners` param for specific genes.
- `OmniPath_get_intercell_roles` — classify proteins as ligand/receptor/ECM. Use `proteins` param.
- `OmniPath_get_cell_communication_annotations` — CellPhoneDB/CellChatDB pathway annotations. Use `proteins` param.
- `OmniPath_get_signaling_interactions` — intracellular signaling downstream of receptors.

Score interactions by co-expression of L-R pairs in proximal cells. Map hotspots where interaction scores peak.

### Phase 7.5: Data Discovery & Gene Context (ToolUniverse API tools)

For dataset discovery and gene annotation (API-based, no local computation needed):
- `geo_search_datasets` / `OmicsDI_search_datasets` / `NCBI_SRA_search_runs` — find spatial TX datasets
- `UniProt_get_function_by_accession` — protein function for stroma/immune markers
- `STRING_get_network` — protein interaction networks for key markers
- `kegg_search_pathway` / `kegg_get_pathway_info` — relevant metabolic/signaling pathways
- `DGIdb_get_drug_gene_interactions` — druggable targets in the spatial context
- `PubMed_search_articles` — literature for spatial biology context

> **API tools vs. local computation**: Phases 1-2 (data import, QC) and Phases 3-6 (clustering, SVGs, neighborhoods, deconvolution) require local Python with squidpy/scanpy. Phase 7 L-R databases and Phase 7.5 gene context use ToolUniverse API tools.

### Phase 8: Report Generation
See [report_template.md](report_template.md) for full example output.

---

## Integration with ToolUniverse Skills

- `tooluniverse-single-cell`: scRNA-seq reference for deconvolution (Phase 6) and L-R database (Phase 7)
- `tooluniverse-gene-enrichment`: Pathway enrichment for spatial domain marker genes (Phase 3)
- `tooluniverse-multi-omics-integration`: Integration with other omics layers (Phase 8)

## ToolUniverse Data Retrieval Tools

### HuBMAP Spatial Atlas Tools

Use HuBMAP tools to discover published spatial biology datasets for reference, validation, or cross-study comparison.

> **Availability Note**: `HuBMAP_search_datasets`, `HuBMAP_list_organs`, and `HuBMAP_get_dataset` may not be registered in your ToolUniverse instance. Verify wit