mims-harvard/tooluniverse-spatial-omics-analysis

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 parameter specifications per phase.

---

Report Structure

Create file: {tissue}_{disease}_spatial_omics_report.md

# Spatial Multi-Omics Analysis Report: {Tissue Type}
**Report Generated**: {date} | **Technology**: {platform}
**Tissue**: {tissue_type} | **Disease**: {disease or "Normal tissue"}
**Total SVGs**: {count} | **Spatial Domains**: {count}
**Spatial Omics Integration Score**: (calculated after analysis)

## Executive Summary
## 1. Tissue & Disease Context
## 2. Spatially Variable Gene Characterization
  - 2.1 Gene ID Resolution
  - 2.2 Tissue Expression Patterns
  - 2.3 Subcellular Localization
  - 2.4 Disease Associations
## 3. Pathway Enrichment Analysis
  - 3.1 STRING, 3.2 Reactome, 3.3-3.5 GO (BP, MF, CC)
## 4. Spatial Domain Characterization (per-domain + comparison)
## 5. Cell-Cell Interaction Inference
  - 5.1 PPI, 5.2 Ligand-Receptor, 5.3 Signaling Pathways
## 6. Disease & Therapeutic Context
  - 6.1 Disease Gene Overlap, 6.2 Druggable Targets, 6.3 Drug Mechanisms, 6.4 Trials
## 7. Multi-Modal Integration (if data available)
## 8. Immune Microenvironment (if relevant)
## 9. Literature & Validation Context
## Spatial Omics Integration Score (breakdown table)
## Completeness Checklist
## References (tools used, database versions)

See report-template.md for full template with table structures.

---

Completeness Checklist

• [ ] Gene ID resolution complete
• [ ] Tissue expression patterns analyzed (HPA)
• [ ] Subcellular localization checked (HPA)
• [ ] Pathway enrichment complete (STRING + Reactome)
• [ ] GO enrichment complete (BP + MF + CC)
• [ ] Spatial domains characterized individually
• [ ] Domain comparison performed
• [ ] PPI analyzed (STRING)
• [ ] Ligand-receptor pairs identified
• [ ] Disease associations checked (OpenTargets)
• [ ] Druggable targets identified
• [ ] Multi-modal integration performed (if data available)
• [ ] Immune microenvironment characterized (if relevant)
• [ ] Literature search completed
• [ ] Validation recommendations provided
• [ ] Integration Score calculated
• [ ] Executive summary written
• [ ] All sections have source citations

---

Common Use Cases

1. Cancer Spatial Heterogeneity: Visium with tumor/stroma/immune domains -> pathways, immune infiltration, druggable targets, checkpoints
2. Brain Tissue Zonation: MERFISH with neuronal subtypes -> synaptic signaling, receptors, hippocampal zonation
3. Liver Metabolic Zonation: Periportal vs pericentral -> CYP450, Wnt gradient, drug metabolism enzymes
4. Tumor-Immune Interface: DBiTplus RNA+protein -> checkpoint L-R pairs, immune exclusion, multi-modal concordance
5. Developmental Patterns: Morphogen gradients (Wnt, BMP, FGF, SHH), TF patterns, cell fate genes
6. Disease Progression: Disease gradient -> inflammatory response, neuronal loss, therapeutic windows

---

Reference Files

• phase-procedures.md - Detailed phase workflows, decision logic, tool usage per phase
• tool-reference.md - Tool parameter names, response formats, fallback strategies, limitations
• reference-data.md - Cell type markers, ligand-receptor pairs, immune checkpoint reference
• report-template.md - Full report template with all table structures
• test_spatial_omics.py - Test suite

---

Summary

Spatial Multi-Omics Analysis provides:

1. Gene characterization (ID resolution, function, localization, tissue expression)
2. Pathway & functional enrichment (STRING, Reactome, GO, KEGG)
3. Spatial domain characterization (per-domain and cross-domain)
4. Cell-cell interaction inference (PPI, ligand-receptor, signaling)
5. Disease & therapeutic context (disease genes, druggable targets, trials)
6. Multi-modal integration (RNA-protein concordance, metabolic pathways)
7. Immune microenvironment (cell types, checkpoints, immunotherapy)
8. Literature context & validation recommendations

Outputs: Markdown report with Spatial Omics Integration Score (0-100) Uses: 70+ ToolUniverse tools across 9 analysis phases Time: ~10-20 minutes depending on gene list size