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