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.

---

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

---

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

---

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

---

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

Expression Data Retrieval Checklist

Use this checklist to ensure complete dataset reports.

Query Disambiguation

• [ ] Gene name resolved (if gene-focused search)
• [ ] Organism confirmed
• [ ] Search keywords optimized

Per Experiment (Required)

• [ ] Accession number with database link
• [ ] Organism
• [ ] Experiment type (RNA-seq/microarray/etc.)
• [ ] Platform specified
• [ ] Sample count
• [ ] Brief description
• [ ] Quality assessment (●●●/●●○/●○○/○○○)

Quality Assessment Criteria

• [ ] Replicate count evaluated
• [ ] Metadata completeness checked
• [ ] Data accessibility confirmed
• [ ] Platform recency noted

Search Summary

• [ ] Query parameters stated
• [ ] Number of results
• [ ] Databases searched (ArrayExpress, BioStudies)

Recommendations

• [ ] Best dataset identified for user's purpose
• [ ] Alternative options listed
• [ ] Data access notes included

Multi-Omics (If Applicable)

• [ ] BioStudies searched
• [ ] Data types listed (transcriptomics, proteomics, etc.)
• [ ] Integration potential noted

Report Quality

• [ ] Search process NOT shown in output
• [ ] Clean tabular format used
• [ ] Download links provided
• [ ] Retrieval date included

Error Handling

• [ ] Empty search → broader keywords suggested
• [ ] Files unavailable → noted in report
• [ ] API errors → noted as "(retrieval incomplete)"

Expression Data Retrieval Examples

Example 1: Find Diabetes Gene Expression Studies

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Search ArrayExpress
result = tu.tools.arrayexpress_search_experiments(
    keywords="diabetes",
    species="Homo sapiens",
    limit=10
)

# Display results
for exp in result["data"]["experiments"][:5]:
    print(f"{exp['accession']}: {exp['name']}")
    print(f"  Samples: {exp['samples']}")
    print(f"  Type: {exp.get('experimenttype', 'N/A')}")

Example 2: Get Complete Experiment Details

# Get experiment metadata
accession = "E-MTAB-5214"

details = tu.tools.arrayexpress_get_experiment(
    accession=accession
)

print(f"Title: {details['data']['title']}")
print(f"Description: {details['data']['description']}")
print(f"Samples: {details['data']['samples']}")

# Get associated files
files = tu.tools.arrayexpress_get_experiment_files(
    accession=accession
)

print("\nAvailable files:")
for file in files["data"]["files"]:
    print(f"  {file['name']} ({file['size']})")

Example 3: Search RNA-seq Experiments

# Search for RNA-seq studies
result = tu.tools.arrayexpress_search_experiments(
    keywords="RNA-seq cancer",
    species="Homo sapiens",
    limit=20
)

# Filter for RNA-seq specifically
rnaseq_studies = [
    exp for exp in result["data"]["experiments"]
    if "rna-seq" in exp.get("experimenttype", "").lower()
]

print(f"Found {len(rnaseq_studies)} RNA-seq studies")

Example 4: Multi-Omics Study from BioStudies

# Search BioStudies for proteomics
result = tu.tools.biostudies_search(
    query="proteomics breast cancer",
    limit=10
)

# Get first study
study_acc = result["data"]["studies"][0]["accession"]

# Get detailed information
details = tu.tools.biostudies_get_study(
    accession=study_acc
)

print(f"Study: {details['data']['title']}")
print(f"Type: {details['data']['type']}")

# Get files
files = tu.tools.biostudies_get_study_files(
    accession=study_acc
)

Example 5: Compare Multiple Experiments

# Search for related experiments
result = tu.tools.arrayexpress_search_experiments(
    keywords="liver tissue",
    species="Mus musculus",
    limit=10
)

# Get details for each
experiments = []
for exp in result["data"]["experiments"][:5]:
    details = tu.tools.arrayexpress_get_experiment(
        accession=exp["accession"]
    )
    experiments.append({
        "accession": exp["accession"],
        "samples": details["data"]["samples"],
        "type": details["data"].get("experimenttype")
    })

# Compare sample sizes
for exp in experiments:
    print(f"{exp['accession']}: {exp['samples']} samples")

Example 6: Download Experiment Data

# Get experiment files
accession = "E-MTAB-1234"

files = tu.tools.arrayexpress_get_experiment_files(
    accession=accession
)

# Find processed data file
for file in files["data"]["files"]:
    if "processed" in file["name"].lower():
        print(f"Processed data: {file['url']}")
        # Use file download tool to get actual file