Claude Cursor Skill

geo-connector

Search, query, and cross-reference NCBI GEO (Gene Expression Omnibus) datasets with ENCODE experiments. Use when the user wants to find GEO accessions for ENCODE experiments, search GEO for complementary datasets, download GEO metadata or series matrices, cross-reference ENCODE a

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download ammawla-encode-toolkit-plugin_skills_geo-connector-36836c8.zip · 10 KB

Install

skills CLI npx skills add https://github.com/ammawla/encode-toolkit/tree/main/plugin/skills/geo-connector
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ammawla-encode-toolkit@llmmart
Git git clone https://github.com/ammawla/encode-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ammawla/encode-toolkit collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Search and Cross-Reference NCBI GEO with ENCODE

When to Use

  • User wants to find complementary datasets in NCBI GEO to supplement ENCODE data
  • User asks about "GEO", "Gene Expression Omnibus", "supplementary data", or "find related datasets"
  • User needs to cross-reference ENCODE experiments with GEO series for additional replicates or conditions
  • User wants to link ENCODE accessions to GEO/SRA identifiers for data sharing or citation
  • Example queries: "find GEO datasets for pancreatic islet RNA-seq", "link this ENCODE experiment to GEO", "search GEO for complementary ATAC-seq data"

Query the Gene Expression Omnibus programmatically to find complementary datasets, cross-reference ENCODE experiments, and download metadata.

Scientific Rationale

The question: "What additional expression or epigenomic datasets exist in GEO that complement my ENCODE analysis?"

GEO hosts >200,000 series across all organisms and assay types. Many ENCODE experiments are deposited in GEO as secondary archives (ENCODE Portal is primary). GEO also contains vast amounts of non-ENCODE data — disease cohorts, perturbation experiments, time courses — that complement ENCODE's reference epigenomes.

GEO ↔ ENCODE Relationship

  • ENCODE processed data is deposited at GEO as standard GSE submissions
  • Raw sequencing data goes to SRA (linked from both GEO and ENCODE)
  • The ENCODE Portal is canonical; GEO is secondary archive
  • GEO accessions are stored in ENCODE's dbxrefs field as GEO:GSExxxxx
  • NCBI maintains a dedicated ENCODE listing: https://www.ncbi.nlm.nih.gov/geo/encode/

GEO Entity Hierarchy

Series (GSE) — An experiment/study
  ├── Sample (GSM) — Individual measurements
  │     ├── references → Platform (GPL)
  │     ├── has → Supplementary files (raw data)
  │     └── has → Data table (normalized values)
  │
  └── curated into → DataSet (GDS) [not all GSE get curated]
        └── generates → Profiles (gene-level summaries)

Step 1: Find GEO Accessions for ENCODE Experiments

From ENCODE → GEO

ENCODE experiments may have GEO cross-references in their metadata. After tracking an experiment:

encode_track_experiment(accession="ENCSR...")

Check the experiment's dbxrefs field for GEO:GSExxxxx entries. If found, link it:

encode_link_reference(
    experiment_accession="ENCSR...",
    reference_type="geo_accession",
    reference_id="GSE12345"
)

From GEO → ENCODE

Search GEO for ENCODE-deposited data:

# Via NCBI E-utilities
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=ENCODE[KEYWORD]+AND+gse[ETYP]&retmax=100&usehistory=y&tool=encode_mcp&email=YOUR_EMAIL"

Step 2: Search GEO for Complementary Datasets

E-utilities Search Syntax

Base URL: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi

Required parameters: db=gds, term=QUERY, tool=encode_mcp, email=YOUR_EMAIL

Rate limit: 3 req/sec without API key, 10 req/sec with key. Get a key at https://www.ncbi.nlm.nih.gov/account/

Search Field Qualifiers

Qualifier Purpose Example
[ETYP] Entry type gse[ETYP], gds[ETYP]
[ORGN] Organism "Homo sapiens"[ORGN]
[PDAT] Publication date 2024[PDAT]
[ACCN] Accession GPL96[ACCN]
[suppFile] Supplementary file type bed[suppFile], bw[suppFile]

Example Searches

# Human pancreas ATAC-seq datasets with BED files
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=pancreas+AND+ATAC-seq+AND+%22Homo+sapiens%22[ORGN]+AND+gse[ETYP]+AND+bed[suppFile]&retmax=50&tool=encode_mcp&email=YOUR_EMAIL"

# ChIP-seq datasets from a specific year
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=ChIP-seq+AND+H3K27ac+AND+gse[ETYP]+AND+2024[PDAT]&retmax=50&tool=encode_mcp&email=YOUR_EMAIL"

# Datasets associated with a PubMed ID
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&db=gds&id=PMID&tool=encode_mcp&email=YOUR_EMAIL"

Step 3: Retrieve GEO Metadata

Get Summary for GEO Records

# Step 1: Search (returns UIDs, NOT accessions)
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=GSE12345[ACCN]&tool=encode_mcp&email=YOUR_EMAIL"

# Step 2: Get summary (use UID from step 1)
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gds&id=UID&version=2.0&tool=encode_mcp&email=YOUR_EMAIL"

Direct Record Access (acc.cgi)

# Get full SOFT-format record
curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=self&view=full&form=text"

# Get XML (MINiML) format
curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=self&view=full&form=xml"

# Get all sample metadata for a series
curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=gsm&view=brief&form=text"

Step 4: Download GEO Data Files

FTP Directory Convention

GEO uses a "nnn" directory pattern: replace last 3 digits with "nnn".

Accession FTP Path
GSE12345 ftp://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/
GSM575 ftp://ftp.ncbi.nlm.nih.gov/geo/samples/GSMnnn/GSM575/

Key Download Paths

Content Path Under Series Directory
Series matrix (expression table) matrix/GSE12345_series_matrix.txt.gz
SOFT metadata soft/GSE12345_family.soft.gz
MINiML (XML) miniml/GSE12345_family.xml.tgz
All supplementary files suppl/GSE12345_RAW.tar
Individual supplementary suppl/FILENAME.gz

Download Commands

# Download series matrix (fastest for expression data)
wget "https://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/matrix/GSE12345_series_matrix.txt.gz"

# Download all supplementary files
wget "https://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/suppl/GSE12345_RAW.tar"

Format Selection Guide

Use Case Format Speed
Expression matrix analysis Series matrix Fastest (10-100x vs SOFT)
Full metadata extraction SOFT Complete but slow
XML processing MINiML Good for programmatic parsing
Peak/BED files Supplementary Direct download
Raw sequencing reads SRA (not GEO) Use SRA Toolkit

Step 5: Cross-Reference Workflow

ENCODE + GEO Integration Pattern

1. Find ENCODE experiments of interest:
   encode_search_experiments(assay_title="total RNA-seq", organ="pancreas")

2. For each experiment, check for GEO accession:
   encode_get_experiment(accession="ENCSR...")
   → Look in dbxrefs for "GEO:GSExxxxx"

3. If GEO accession found, link it:
   encode_link_reference(
       experiment_accession="ENCSR...",
       reference_type="geo_accession",
       reference_id="GSE12345"
   )

4. Search GEO for complementary non-ENCODE datasets:
   E-utils search for same tissue + different assay or condition

5. Download GEO metadata for comparison:
   acc.cgi or E-utils esummary

6. Log the cross-reference:
   encode_log_derived_file(
       file_path="/path/to/comparison.tsv",
       source_accessions=["ENCSR...", "GSE12345"],
       description="ENCODE-GEO cross-tissue comparison"
   )

Finding SRA Accessions from GEO

For sequencing data, raw reads are in SRA, not GEO:

# Link GEO to SRA
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=gds&db=sra&id=GDS_UID&tool=encode_mcp&email=YOUR_EMAIL"

Python alternative using pysradb:

from pysradb.search import SraSearch
# Convert GSE to SRP
pysradb gse-to-srp GSE12345
# Get all SRR run accessions
pysradb gsm-to-srr GSM12345

Pitfalls and Caveats

  1. E-utils return UIDs, not accessions: GEO search returns numeric UIDs. You must call ESummary to get the actual GSE/GDS accession numbers.
  2. Not all ENCODE experiments have GEO accessions: The dbxrefs field may be empty. ENCODE Portal is always the canonical source.
  3. GEO search max is 10,000 per call: Use usehistory=y and paginate with retstart for large result sets.
  4. Series matrix may be split: Large studies can produce multiple matrix files (*_series_matrix-1.txt.gz, *_series_matrix-2.txt.gz).
  5. SOFT format discontinued for new submissions (early 2024): Existing records are still downloadable, but new submissions use different formats.
  6. Rate limits are strict: Without API key, max 3 requests/second. Include tool= and email= parameters on every request.
  7. GEO metadata quality varies: User-submitted metadata may be inconsistent. Always verify organism, platform, and sample characteristics.

Walkthrough: Finding Complementary GEO Datasets for ENCODE Experiments

Goal: Identify Gene Expression Omnibus (GEO) datasets that complement ENCODE epigenomic experiments, enabling integrative analysis of gene expression with regulatory elements. Context: ENCODE provides epigenomic maps (ChIP-seq, ATAC-seq), while GEO hosts vast RNA-seq expression datasets. Combining them links regulatory elements to transcriptional output.

Step 1: Identify the ENCODE experiment to complement

encode_get_experiment(accession="ENCSR123HEP")

Expected output:

{
  "accession": "ENCSR123HEP",
  "assay_title": "Histone ChIP-seq",
  "target": "H3K27ac",
  "biosample_summary": "HepG2",
  "organism": "Homo sapiens",
  "status": "released"
}

Interpretation: This is H3K27ac ChIP-seq in HepG2 (liver cancer cell line). We need matching RNA-seq data from the same cell line.

Step 2: Search GEO for complementary RNA-seq

Using NCBI E-utilities (via skill guidance):

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=HepG2[cell+line]+AND+RNA-seq[strategy]+AND+Homo+sapiens[organism]&retmax=10

Expected response:

{
  "esearchresult": {
    "count": "142",
    "idlist": ["200156789", "200145678", "200134567"]
  }
}

Step 3: Link ENCODE experiment to GEO dataset

encode_link_reference(experiment_accession="ENCSR123HEP", reference_type="geo_accession", reference_id="GSE156789", description="HepG2 RNA-seq for enhancer-expression integration")

Expected output:

{
  "action": "linked",
  "experiment_accession": "ENCSR123HEP",
  "reference_type": "geo_accession",
  "reference_id": "GSE156789"
}

Step 4: Check for ENCODE RNA-seq in same biosample

encode_search_experiments(assay_title="total RNA-seq", biosample_term_name="HepG2", organism="Homo sapiens")

Expected output:

{
  "results": [
    {"accession": "ENCSR456RNA", "assay_title": "total RNA-seq", "biosample_summary": "HepG2", "biosample_type": "cell line", "status": "released"}
  ],
  "total": 15,
  "limit": 25,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}

Interpretation: ENCODE already has 15 HepG2 RNA-seq experiments! Always check ENCODE first before going to GEO. GEO becomes essential when ENCODE lacks expression data for your specific biosample or experimental condition (e.g., drug treatment, knockdown).

Integration with downstream skills

  • GEO expression data feeds into → peak-annotation for enhancer target gene validation
  • GEO dataset accessions integrate with → cite-encode for proper data attribution
  • GEO RNA-seq complements → gtex-expression for cell-line-specific expression
  • GEO metadata links to → data-provenance for full analysis audit trail

Code Examples

1. Link an ENCODE experiment to GEO

encode_link_reference(
  experiment_accession="ENCSR000AKA",
  reference_type="geo_accession",
  reference_id="GSE76079",
  description="Complementary RNA-seq from same lab"
)

Expected output:

{
  "action": "linked",
  "experiment_accession": "ENCSR000AKA",
  "reference_type": "geo_accession",
  "reference_id": "GSE76079"
}

2. View all references for a tracked experiment

encode_get_references(experiment_accession="ENCSR000AKA")

Expected output (each row also carries linked_at, a float epoch timestamp; rows are ordered newest first):

{
  "references": [
    {
      "id": 2,
      "experiment_accession": "ENCSR000AKA",
      "reference_type": "geo_accession",
      "reference_id": "GSE76079",
      "description": "Complementary RNA-seq from same lab"
    },
    {
      "id": 1,
      "experiment_accession": "ENCSR000AKA",
      "reference_type": "pmid",
      "reference_id": "27429435",
      "description": "Primary publication"
    }
  ],
  "count": 2
}

Integration

This skill produces... Feed into... Using tool/skill
GEO accession (GSE/GSM) Cross-reference link encode_link_reference(experiment_accession="ENCSR...", reference_type="geo_accession", reference_id="GSE...")
Supplementary expression data Differential expression integrative-analysis skill
Complementary replicates from GEO Expanded sample size download-encode + batch-analysis
SRA run accessions Raw data download bioinformatics-installer (sra-tools)
GEO metadata Publication cross-reference cite-encode skill

Related Skills

Skill When to Use Instead/Additionally
cross-reference General external reference linking (PubMed, DOI, GEO, NCT)
data-provenance Logging derived files from ENCODE+GEO combined analyses
search-encode Finding ENCODE experiments (primary source)
download-encode Downloading ENCODE files (preferred over GEO for ENCODE data)
track-experiments Local experiment tracking with GEO cross-references
cite-encode Getting citations for ENCODE experiments found via GEO
ucsc-browser Querying aggregated ENCODE tracks at UCSC
publication-trust Verify literature claims backing analytical decisions

Presenting Results

  • Present GEO links as: ENCODE_accession | GEO_accession | title | organism | samples. Suggest: "Would you like to link these GEO accessions to the tracked experiments?"

For the request: "$ARGUMENTS"

Files (encode-toolkit)
  • references
    • literature.md 11.6 KB
      Loading…
  • SKILL.md 14.5 KB
    ---
    name: geo-connector
    description: Search, query, and cross-reference NCBI GEO (Gene Expression Omnibus) datasets with ENCODE experiments. Use when the user wants to find GEO accessions for ENCODE experiments, search GEO for complementary datasets, download GEO metadata or series matrices, cross-reference ENCODE and GEO data, find supplementary files from GEO, or link GEO series to ENCODE experiments for provenance tracking. Also use when the user mentions GEO, GSE, GSM, GPL, GDS, series matrix, SOFT format, or needs to find expression data in GEO that complements their ENCODE analysis.
    ---
    
    # Search and Cross-Reference NCBI GEO with ENCODE
    
    ## When to Use
    
    - User wants to find complementary datasets in NCBI GEO to supplement ENCODE data
    - User asks about "GEO", "Gene Expression Omnibus", "supplementary data", or "find related datasets"
    - User needs to cross-reference ENCODE experiments with GEO series for additional replicates or conditions
    - User wants to link ENCODE accessions to GEO/SRA identifiers for data sharing or citation
    - Example queries: "find GEO datasets for pancreatic islet RNA-seq", "link this ENCODE experiment to GEO", "search GEO for complementary ATAC-seq data"
    
    Query the Gene Expression Omnibus programmatically to find complementary datasets, cross-reference ENCODE experiments, and download metadata.
    
    ## Scientific Rationale
    
    **The question**: "What additional expression or epigenomic datasets exist in GEO that complement my ENCODE analysis?"
    
    GEO hosts >200,000 series across all organisms and assay types. Many ENCODE experiments are deposited in GEO as secondary archives (ENCODE Portal is primary). GEO also contains vast amounts of non-ENCODE data — disease cohorts, perturbation experiments, time courses — that complement ENCODE's reference epigenomes.
    
    ### GEO ↔ ENCODE Relationship
    
    - ENCODE processed data is deposited at GEO as standard GSE submissions
    - Raw sequencing data goes to SRA (linked from both GEO and ENCODE)
    - The ENCODE Portal is canonical; GEO is secondary archive
    - GEO accessions are stored in ENCODE's `dbxrefs` field as `GEO:GSExxxxx`
    - NCBI maintains a dedicated ENCODE listing: https://www.ncbi.nlm.nih.gov/geo/encode/
    
    ## GEO Entity Hierarchy
    
    ```
    Series (GSE) — An experiment/study
      ├── Sample (GSM) — Individual measurements
      │     ├── references → Platform (GPL)
      │     ├── has → Supplementary files (raw data)
      │     └── has → Data table (normalized values)
      │
      └── curated into → DataSet (GDS) [not all GSE get curated]
            └── generates → Profiles (gene-level summaries)
    ```
    
    ## Step 1: Find GEO Accessions for ENCODE Experiments
    
    ### From ENCODE → GEO
    
    ENCODE experiments may have GEO cross-references in their metadata. After tracking an experiment:
    
    ```
    encode_track_experiment(accession="ENCSR...")
    ```
    
    Check the experiment's `dbxrefs` field for `GEO:GSExxxxx` entries. If found, link it:
    
    ```
    encode_link_reference(
        experiment_accession="ENCSR...",
        reference_type="geo_accession",
        reference_id="GSE12345"
    )
    ```
    
    ### From GEO → ENCODE
    
    Search GEO for ENCODE-deposited data:
    
    ```bash
    # Via NCBI E-utilities
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=ENCODE[KEYWORD]+AND+gse[ETYP]&retmax=100&usehistory=y&tool=encode_mcp&email=YOUR_EMAIL"
    ```
    
    ## Step 2: Search GEO for Complementary Datasets
    
    ### E-utilities Search Syntax
    
    **Base URL**: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`
    
    **Required parameters**: `db=gds`, `term=QUERY`, `tool=encode_mcp`, `email=YOUR_EMAIL`
    
    **Rate limit**: 3 req/sec without API key, 10 req/sec with key. Get a key at https://www.ncbi.nlm.nih.gov/account/
    
    ### Search Field Qualifiers
    
    | Qualifier | Purpose | Example |
    |-----------|---------|---------|
    | `[ETYP]` | Entry type | `gse[ETYP]`, `gds[ETYP]` |
    | `[ORGN]` | Organism | `"Homo sapiens"[ORGN]` |
    | `[PDAT]` | Publication date | `2024[PDAT]` |
    | `[ACCN]` | Accession | `GPL96[ACCN]` |
    | `[suppFile]` | Supplementary file type | `bed[suppFile]`, `bw[suppFile]` |
    
    ### Example Searches
    
    ```bash
    # Human pancreas ATAC-seq datasets with BED files
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=pancreas+AND+ATAC-seq+AND+%22Homo+sapiens%22[ORGN]+AND+gse[ETYP]+AND+bed[suppFile]&retmax=50&tool=encode_mcp&email=YOUR_EMAIL"
    
    # ChIP-seq datasets from a specific year
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=ChIP-seq+AND+H3K27ac+AND+gse[ETYP]+AND+2024[PDAT]&retmax=50&tool=encode_mcp&email=YOUR_EMAIL"
    
    # Datasets associated with a PubMed ID
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&db=gds&id=PMID&tool=encode_mcp&email=YOUR_EMAIL"
    ```
    
    ## Step 3: Retrieve GEO Metadata
    
    ### Get Summary for GEO Records
    
    ```bash
    # Step 1: Search (returns UIDs, NOT accessions)
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=GSE12345[ACCN]&tool=encode_mcp&email=YOUR_EMAIL"
    
    # Step 2: Get summary (use UID from step 1)
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gds&id=UID&version=2.0&tool=encode_mcp&email=YOUR_EMAIL"
    ```
    
    ### Direct Record Access (acc.cgi)
    
    ```bash
    # Get full SOFT-format record
    curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=self&view=full&form=text"
    
    # Get XML (MINiML) format
    curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=self&view=full&form=xml"
    
    # Get all sample metadata for a series
    curl "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE12345&targ=gsm&view=brief&form=text"
    ```
    
    ## Step 4: Download GEO Data Files
    
    ### FTP Directory Convention
    
    GEO uses a "nnn" directory pattern: replace last 3 digits with "nnn".
    
    | Accession | FTP Path |
    |-----------|----------|
    | GSE12345 | `ftp://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/` |
    | GSM575 | `ftp://ftp.ncbi.nlm.nih.gov/geo/samples/GSMnnn/GSM575/` |
    
    ### Key Download Paths
    
    | Content | Path Under Series Directory |
    |---------|----------------------------|
    | Series matrix (expression table) | `matrix/GSE12345_series_matrix.txt.gz` |
    | SOFT metadata | `soft/GSE12345_family.soft.gz` |
    | MINiML (XML) | `miniml/GSE12345_family.xml.tgz` |
    | All supplementary files | `suppl/GSE12345_RAW.tar` |
    | Individual supplementary | `suppl/FILENAME.gz` |
    
    ### Download Commands
    
    ```bash
    # Download series matrix (fastest for expression data)
    wget "https://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/matrix/GSE12345_series_matrix.txt.gz"
    
    # Download all supplementary files
    wget "https://ftp.ncbi.nlm.nih.gov/geo/series/GSE12nnn/GSE12345/suppl/GSE12345_RAW.tar"
    ```
    
    ### Format Selection Guide
    
    | Use Case | Format | Speed |
    |----------|--------|-------|
    | Expression matrix analysis | Series matrix | Fastest (10-100x vs SOFT) |
    | Full metadata extraction | SOFT | Complete but slow |
    | XML processing | MINiML | Good for programmatic parsing |
    | Peak/BED files | Supplementary | Direct download |
    | Raw sequencing reads | SRA (not GEO) | Use SRA Toolkit |
    
    ## Step 5: Cross-Reference Workflow
    
    ### ENCODE + GEO Integration Pattern
    
    ```
    1. Find ENCODE experiments of interest:
       encode_search_experiments(assay_title="total RNA-seq", organ="pancreas")
    
    2. For each experiment, check for GEO accession:
       encode_get_experiment(accession="ENCSR...")
       → Look in dbxrefs for "GEO:GSExxxxx"
    
    3. If GEO accession found, link it:
       encode_link_reference(
           experiment_accession="ENCSR...",
           reference_type="geo_accession",
           reference_id="GSE12345"
       )
    
    4. Search GEO for complementary non-ENCODE datasets:
       E-utils search for same tissue + different assay or condition
    
    5. Download GEO metadata for comparison:
       acc.cgi or E-utils esummary
    
    6. Log the cross-reference:
       encode_log_derived_file(
           file_path="/path/to/comparison.tsv",
           source_accessions=["ENCSR...", "GSE12345"],
           description="ENCODE-GEO cross-tissue comparison"
       )
    ```
    
    ### Finding SRA Accessions from GEO
    
    For sequencing data, raw reads are in SRA, not GEO:
    
    ```bash
    # Link GEO to SRA
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=gds&db=sra&id=GDS_UID&tool=encode_mcp&email=YOUR_EMAIL"
    ```
    
    Python alternative using pysradb:
    ```python
    from pysradb.search import SraSearch
    # Convert GSE to SRP
    pysradb gse-to-srp GSE12345
    # Get all SRR run accessions
    pysradb gsm-to-srr GSM12345
    ```
    
    ## Pitfalls and Caveats
    
    1. **E-utils return UIDs, not accessions**: GEO search returns numeric UIDs. You must call ESummary to get the actual GSE/GDS accession numbers.
    2. **Not all ENCODE experiments have GEO accessions**: The `dbxrefs` field may be empty. ENCODE Portal is always the canonical source.
    3. **GEO search max is 10,000 per call**: Use `usehistory=y` and paginate with `retstart` for large result sets.
    4. **Series matrix may be split**: Large studies can produce multiple matrix files (`*_series_matrix-1.txt.gz`, `*_series_matrix-2.txt.gz`).
    5. **SOFT format discontinued for new submissions** (early 2024): Existing records are still downloadable, but new submissions use different formats.
    6. **Rate limits are strict**: Without API key, max 3 requests/second. Include `tool=` and `email=` parameters on every request.
    7. **GEO metadata quality varies**: User-submitted metadata may be inconsistent. Always verify organism, platform, and sample characteristics.
    
    ## Walkthrough: Finding Complementary GEO Datasets for ENCODE Experiments
    
    **Goal**: Identify Gene Expression Omnibus (GEO) datasets that complement ENCODE epigenomic experiments, enabling integrative analysis of gene expression with regulatory elements.
    **Context**: ENCODE provides epigenomic maps (ChIP-seq, ATAC-seq), while GEO hosts vast RNA-seq expression datasets. Combining them links regulatory elements to transcriptional output.
    
    ### Step 1: Identify the ENCODE experiment to complement
    
    ```
    encode_get_experiment(accession="ENCSR123HEP")
    ```
    
    Expected output:
    ```json
    {
      "accession": "ENCSR123HEP",
      "assay_title": "Histone ChIP-seq",
      "target": "H3K27ac",
      "biosample_summary": "HepG2",
      "organism": "Homo sapiens",
      "status": "released"
    }
    ```
    
    **Interpretation**: This is H3K27ac ChIP-seq in HepG2 (liver cancer cell line). We need matching RNA-seq data from the same cell line.
    
    ### Step 2: Search GEO for complementary RNA-seq
    
    Using NCBI E-utilities (via skill guidance):
    ```
    GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gds&term=HepG2[cell+line]+AND+RNA-seq[strategy]+AND+Homo+sapiens[organism]&retmax=10
    ```
    
    Expected response:
    ```json
    {
      "esearchresult": {
        "count": "142",
        "idlist": ["200156789", "200145678", "200134567"]
      }
    }
    ```
    
    ### Step 3: Link ENCODE experiment to GEO dataset
    
    ```
    encode_link_reference(experiment_accession="ENCSR123HEP", reference_type="geo_accession", reference_id="GSE156789", description="HepG2 RNA-seq for enhancer-expression integration")
    ```
    
    Expected output:
    ```json
    {
      "action": "linked",
      "experiment_accession": "ENCSR123HEP",
      "reference_type": "geo_accession",
      "reference_id": "GSE156789"
    }
    ```
    
    ### Step 4: Check for ENCODE RNA-seq in same biosample
    
    ```
    encode_search_experiments(assay_title="total RNA-seq", biosample_term_name="HepG2", organism="Homo sapiens")
    ```
    
    Expected output:
    ```json
    {
      "results": [
        {"accession": "ENCSR456RNA", "assay_title": "total RNA-seq", "biosample_summary": "HepG2", "biosample_type": "cell line", "status": "released"}
      ],
      "total": 15,
      "limit": 25,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    }
    ```
    
    **Interpretation**: ENCODE already has 15 HepG2 RNA-seq experiments! Always check ENCODE first before going to GEO. GEO becomes essential when ENCODE lacks expression data for your specific biosample or experimental condition (e.g., drug treatment, knockdown).
    
    ### Integration with downstream skills
    - GEO expression data feeds into → **peak-annotation** for enhancer target gene validation
    - GEO dataset accessions integrate with → **cite-encode** for proper data attribution
    - GEO RNA-seq complements → **gtex-expression** for cell-line-specific expression
    - GEO metadata links to → **data-provenance** for full analysis audit trail
    
    ## Code Examples
    
    ### 1. Link an ENCODE experiment to GEO
    
    ```
    encode_link_reference(
      experiment_accession="ENCSR000AKA",
      reference_type="geo_accession",
      reference_id="GSE76079",
      description="Complementary RNA-seq from same lab"
    )
    ```
    
    Expected output:
    ```json
    {
      "action": "linked",
      "experiment_accession": "ENCSR000AKA",
      "reference_type": "geo_accession",
      "reference_id": "GSE76079"
    }
    ```
    
    ### 2. View all references for a tracked experiment
    
    ```
    encode_get_references(experiment_accession="ENCSR000AKA")
    ```
    
    Expected output (each row also carries `linked_at`, a float epoch timestamp; rows are ordered newest first):
    ```json
    {
      "references": [
        {
          "id": 2,
          "experiment_accession": "ENCSR000AKA",
          "reference_type": "geo_accession",
          "reference_id": "GSE76079",
          "description": "Complementary RNA-seq from same lab"
        },
        {
          "id": 1,
          "experiment_accession": "ENCSR000AKA",
          "reference_type": "pmid",
          "reference_id": "27429435",
          "description": "Primary publication"
        }
      ],
      "count": 2
    }
    ```
    
    ## Integration
    
    | This skill produces... | Feed into... | Using tool/skill |
    |---|---|---|
    | GEO accession (GSE/GSM) | Cross-reference link | encode_link_reference(experiment_accession="ENCSR...", reference_type="geo_accession", reference_id="GSE...") |
    | Supplementary expression data | Differential expression | integrative-analysis skill |
    | Complementary replicates from GEO | Expanded sample size | download-encode + batch-analysis |
    | SRA run accessions | Raw data download | bioinformatics-installer (sra-tools) |
    | GEO metadata | Publication cross-reference | cite-encode skill |
    
    ## Related Skills
    
    | Skill | When to Use Instead/Additionally |
    |-------|--------------------------------|
    | `cross-reference` | General external reference linking (PubMed, DOI, GEO, NCT) |
    | `data-provenance` | Logging derived files from ENCODE+GEO combined analyses |
    | `search-encode` | Finding ENCODE experiments (primary source) |
    | `download-encode` | Downloading ENCODE files (preferred over GEO for ENCODE data) |
    | `track-experiments` | Local experiment tracking with GEO cross-references |
    | `cite-encode` | Getting citations for ENCODE experiments found via GEO |
    | `ucsc-browser` | Querying aggregated ENCODE tracks at UCSC |
    | `publication-trust` | Verify literature claims backing analytical decisions |
    
    ## Presenting Results
    
    - Present GEO links as: ENCODE_accession | GEO_accession | title | organism | samples. Suggest: "Would you like to link these GEO accessions to the tracked experiments?"
    
    ## For the request: "$ARGUMENTS"
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.