tooluniverse-expression-data-retrieval

Gene Expression & Omics Data Retrieval

Retrieve gene expression experiments and multi-omics datasets with disambiguation and quality assessment.

IMPORTANT: Always use English terms in tool calls. Respond in the user's language.

LOOK UP DON'T GUESS: Never assume which datasets exist or their accessions. Always search to confirm.

Domain Reasoning

Before retrieving, determine: organism, tissue, experimental design (case-control/time-series/dose-response). These affect which database to search and how to interpret results. RNA-seq provides wider dynamic range; microarray has extensive legacy data. Prioritize experiments with >=3 biological replicates, complete annotations, and both raw+processed data.

Workflow

Phase 0: Clarify (if ambiguous) → Phase 1: Disambiguate → Phase 2: Search & Retrieve → Phase 3: Report

---

Phase 0: Clarification (When Needed)

Ask ONLY if: gene name ambiguous, tissue/condition unclear, organism not specified. Skip for: specific accessions (E-MTAB-, E-GEOD-, S-BSST*), clear disease/tissue+organism, explicit platform requests.

---

Phase 1: Query Disambiguation

Resolve official gene symbol (HGNC for human, MGI for mouse). Note common aliases for search expansion.

User Query Type	Search Strategy
Specific accession	Direct retrieval
Gene + condition	"[gene] [condition]" + species filter
Disease only	"[disease]" + species filter
Technology-specific	Add platform keywords

---

Phase 2: Data Retrieval (Internal)

Search silently. Do NOT narrate the process.

# ArrayExpress search
result = tu.tools.arrayexpress_search_experiments(keywords="[gene/disease]", species="[species]", limit=20)

# Get experiment details, samples, files
details = tu.tools.arrayexpress_get_experiment(accession=accession)
samples = tu.tools.arrayexpress_get_experiment_samples(accession=accession)
files = tu.tools.arrayexpress_get_experiment_files(accession=accession)

# BioStudies for multi-omics
biostudies = tu.tools.biostudies_search(query="[keywords]", limit=10)
study = tu.tools.biostudies_get_study(accession=study_accession)
study_files = tu.tools.biostudies_get_study_files(accession=study_accession)

Fallback Chains

Primary	Fallback
ArrayExpress search	BioStudies search
arrayexpress_get_experiment	biostudies_get_study
arrayexpress_get_experiment_files	Note "Files unavailable"

---

Phase 3: Report Dataset Profile

Present as a Dataset Search Report. Hide search process. Include:

1. Search Summary: query, databases searched, result count
2. Top Experiments (per experiment):
   • Accession, organism, type (RNA-seq/microarray), platform, sample count, date
   • Description, experimental design (conditions, replicates, tissue)
   • Sample groups table, data files table
   • Quality assessment (●●●/●●○/●○○)
3. Multi-Omics Studies (from BioStudies): accession, type, data types included
4. Summary Table: all experiments ranked
5. Recommendations: best dataset for user's purpose, integration notes
6. Data Access: download links, database URLs

---

Data Quality Tiers

Tier	Symbol	Criteria
High	●●●	>=3 bio replicates, complete metadata, processed data available
Medium	●●○	2-3 replicates OR some metadata gaps
Low	●○○	No replicates, sparse metadata, or access issues
Caution	○○○	Single sample, no replication, outdated platform

---

Reasoning Framework

Dataset quality: Prioritize >=3 biological replicates, complete annotations, both raw+processed data. Single-replicate experiments can inform but not be sole evidence.

Platform comparison: RNA-seq = wider dynamic range, novel transcripts. Microarray = probe-limited but extensive legacy data. Cross-platform combining requires batch correction.

Metadata scoring: Rate 0-5 on: (1) sample annotations, (2) design documented, (3) pipeline described, (4) raw data deposited, (5) publication linked. Score <=2 warrants caution.

GEO vs ArrayExpress: GEO has broader coverage (older studies); ArrayExpress enforces stricter metadata. BioStudies captures multi-omics. Search both.

Synthesis Questions

1. Does the dataset have sufficient replication and metadata for the intended analysis?
2. Are there batch effects or confounding variables?
3. Do multiple datasets show concordant patterns, and can they be integrated?

---

Error Handling

Error	Response
"No experiments found"	Broaden keywords, remove species filter, try synonyms
"Accession not found"	Verify format, check if withdrawn
"Files not available"	Note: "Data files restricted by submitter"
"API timeout"	Retry once, note "(metadata retrieval incomplete)"

---

Tool Reference

ArrayExpress: arrayexpress_search_experiments (search), arrayexpress_get_experiment (metadata), arrayexpress_get_experiment_files (downloads), arrayexpress_get_experiment_samples (annotations)

BioStudies: biostudies_search (search), biostudies_get_study (metadata+sections), biostudies_get_study_files (files)

Additional Sources:

• GEO_search_rnaseq_datasets / geo_search_datasets -- GEO (largest RNA-seq repo)
• OmicsDI_search_datasets -- cross-repository aggregation (GEO+ArrayExpress+PRIDE+MassIVE)
• GTEx_get_expression_summary -- baseline tissue expression (54 normal tissues, param: gene_symbol)
• ENAPortal_search_studies -- sequencing studies (param: query with description="...")
• CxGDisc_search_datasets -- single-cell datasets (needs exact disease ontology terms)
• PubMed_search_articles -- dataset discovery via publications

---

Search Parameters

ArrayExpress: keywords (free text), species (scientific name), array (platform filter), limit BioStudies: query (free text), limit