tooluniverse-spatial-omics-analysis

What this skill does

# Spatial Multi-Omics Analysis Pipeline

Comprehensive biological interpretation of spatial omics data. Transforms spatially variable genes (SVGs), domain annotations, and tissue context into actionable biological insights.

**KEY PRINCIPLES**:
1. **Report-first approach** - Create report file FIRST, then populate progressively
2. **Domain-by-domain analysis** - Characterize each spatial region independently before comparison
3. **Gene-list-centric** - Analyze user-provided SVGs and marker genes with ToolUniverse databases
4. **Biological interpretation** - Go beyond statistics to explain biological meaning of spatial patterns
5. **Disease focus** - Emphasize disease mechanisms and therapeutic opportunities when disease context is provided
6. **Evidence grading** - Grade all evidence as T1 (human/clinical) to T4 (computational)
7. **Multi-modal thinking** - Integrate RNA, protein, and metabolite information when available
8. **Validation guidance** - Suggest experimental validation approaches for key findings
9. **Source references** - Every statement must cite tool/database source
10. **English-first queries** - Always use English terms in tool calls

---

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

---

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

## When to Use This Skill

Apply when users:
- Provide spatially variable genes from spatial transcriptomics experiments
- Ask about biological interpretation of spatial domains/clusters
- Need pathway enrichment of spatial gene expression data
- Want to understand cell-cell interactions from spatial data
- Ask about tumor microenvironment heterogeneity from spatial omics
- Need druggable targets in specific spatial regions
- Ask about tissue zonation patterns (liver, brain, kidney)
- Want to integrate spatial transcriptomics + proteomics data

**NOT for**: Single gene interpretation (use target-research), variant interpretation, drug safety, bulk RNA-seq, GWAS analysis.

---

## Input Parameters

| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
| **svgs** | Yes | Spatially variable genes | `['EGFR', 'CDH1', 'VIM', 'MYC', 'CD3E']` |
| **tissue_type** | Yes | Tissue/organ type | `brain`, `liver`, `lung`, `breast` |
| **technology** | No | Spatial omics platform | `10x Visium`, `MERFISH`, `DBiTplus` |
| **disease_context** | No | Disease if applicable | `breast cancer`, `Alzheimer disease` |
| **spatial_domains** | No | Domain -> marker genes dict | `{'Tumor core': ['MYC','EGFR']}` |
| **cell_types** | No | Cell types from deconvolution | `['Epithelial', 'T cell']` |
| **proteins** | No | Proteins detected (multi-modal) | `['CD3', 'PD-L1', 'Ki67']` |
| **metabolites** | No | Metabolites (SpatialMETA) | `['glutamine', 'lactate']` |

---

## Spatial Omics Integration Score (0-100)

**Data Completeness (0-30)**: SVGs (5), Disease context (5), Spatial domains (5), Cell types (5), Multi-modal (5), Literature (5)

**Biological Insight (0-40)**: Pathway enrichment FDR<0.05 (10), Cell-cell interactions (10), Disease mechanism (10), Druggable targets (10)

**Evidence Quality (0-30)**: Cross-database validation 3+ DBs (10), Clinical validation (10), Literature support (10)

| Score | Tier | Interpretation |
|-------|------|----------------|
| 80-100 | Excellent | Comprehensive characterization, strong insights, druggable targets |
| 60-79 | Good | Good pathway/interaction analysis, some therapeutic context |
| 40-59 | Moderate | Basic enrichment, limited domain comparison |
| 0-39 | Limited | Minimal data, gene-level annotation only |

### Evidence Grading

| Tier | Criteria | Examples |
|------|----------|----------|
| [T1] | Direct human/clinical evidence | FDA-approved drug, validated biomarker |
| [T2] | Experimental evidence | Validated spatial pattern, known L-R pair |
| [T3] | Computational/database evidence | PPI prediction, pathway enrichment |
| [T4] | Annotation/prediction only | GO annotation, text-mined association |

---

## Analysis Phases Overview

### Phase 0: Input Processing & Disambiguation (ALWAYS FIRST)
Resolve tissue/disease identifiers, establish analysis context. Get MONDO/EFO IDs for disease queries.
- Tools: `OpenTargets_get_disease_id_description_by_name`, `OpenTargets_get_disease_description_by_efoId`, `HPA_search_genes_by_query`

### Phase 1: Gene Characterization
Resolve gene IDs, annotate functions, tissue specificity, subcellular localization.
- Tools: `MyGene_query_genes`, `UniProt_get_function_by_accession`, `HPA_get_subcellular_location`, `HPA_get_rna_expression_by_source`, `HPA_get_comprehensive_gene_details_by_ensembl_id`, `HPA_get_cancer_prognostics_by_gene`, `UniProtIDMap_gene_to_uniprot`

### Phase 2: Pathway & Functional Enrichment
Identify enriched pathways globally and per-domain. Filter FDR < 0.05.
- Tools: `STRING_functional_enrichment` (PRIMARY), `ReactomeAnalysis_pathway_enrichment`, `GO_get_annotations_for_gene`, `kegg_search_pathway`, `WikiPathways_search`

### Phase 3: Spatial Domain Characterization
Characterize each domain biologically, assign cell types from markers, compare domains.
- Tools: Phase 2 tools + `HPA_get_biological_processes_by_gene`, `HPA_get_protein_interactions_by_gene`

### Phase 4: Cell-Cell Interaction Inference
Predict communication from spatial patterns. Check ligand-receptor pairs across domains.
- Tools: `STRING_get_interaction_partners`, `STRING_get_protein_interactions`, `intact_search_interactions`, `Reactome_get_interactor`, `DGIdb_get_drug_gene_interactions`

### Phase 5: Disease & Therapeutic Context
Connect to disease mechanisms, identify druggable targets, find clinical trials.
- Tools: `OpenTargets_get_associated_targets_by_disease_efoId`, `OpenTargets_get_target_tractability_by_ensemblID`, `OpenTargets_get_associated_drugs_by_target_ensemblID`, `search_clinical_trials`, `DGIdb_get_gene_druggability`, `civic_search_genes`

### Phase 6: Multi-Modal Integration
Integrate protein/RNA/metabolite data. Compare spatial RNA with protein detection.
- Tools: `HPA_get_subcellular_location`, `HPA_get_rna_expression_in_specific_tissues`, `Reactome_map_uniprot_to_pathways`, `kegg_get_pathway_info`

### Phase 7: Immune Microenvironment (Cancer/Inflammation only)
Classify immune cells, check checkpoint expression, assess Hot vs Cold vs Excluded patterns.
- Tools: `STRING_functional_enrichment`, `OpenTargets_get_target_tractability_by_ensemblID`, `iedb_search_epitopes`

### Phase 8: Literature & Validation Context
Search published evidence, suggest validation experiments (smFISH, IHC, PLA).
- Tools: `PubMed_search_articles`, `openalex_literature_search`

### Data Discovery: HuBMAP Spatial Atlas Tools

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

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `HuBMAP_search_datasets` | Search published spatial datasets by organ/assay/keyword | `organ` (code: "LK"=Kidney, "BR"=Brain, "LU"=Lung, etc.), `dataset_type` ("RNAseq", "CODEX", "MALDI"), `query`, `limit` |
| `HuBMAP_list_organs` | List all available organs with codes and UBERON IDs | (no required params) |
| `HuBMAP_get_dataset` | Get detailed metadata for a specific HuBMAP dataset | `hubmap_id` (e.g. "HBM626.FHJD.938") |

**When to use**: Phase 0 (find reference datasets for the tissue), Phase 8 (cross-reference findings with published HuBMAP atlas data).

See **phase-procedures.md** for detailed workflows, decision logic, and tool param