/track-experiments

name: track-experiments
description: Track ENCODE experiments locally with publications, citations, and provenance. Use when the user wants to build a collection of experiments, manage citations, compare experiments, or track data provenance.

Track ENCODE Experiments

When to Use

• User wants to save/bookmark ENCODE experiments for later reference
• User needs to build a collection of experiments for a project
• User asks to "track", "save", or "bookmark" an experiment
• User wants to manage citations and publications for ENCODE data
• User needs to compare experiments for compatibility
• User wants to export their experiment collection as CSV/TSV/JSON
• User asks about data provenance (linking derived files to ENCODE sources)

Help the user manage their local collection of ENCODE experiments. This skill covers the full lifecycle of experiment management: discovery, tracking, annotation, citation, comparison, provenance, and export.

Tracking Capabilities

1. **Track an experiment**: Use `encode_track_experiment` to save experiment metadata, publications, and pipeline info locally.

• Automatically extracts GEO accessions and PMIDs from experiment metadata
• Fetches associated publications with authors, journal, DOI
• Stores 18 metadata fields per experiment (see schema below)
• Idempotent: re-tracking the same accession updates metadata without creating duplicates

2. **View tracked collection**: Use `encode_list_tracked` to see all tracked experiments. Filter by assay, organism, or organ.

3. **Get citations**: Use `encode_get_citations` to export publication data.

• `"json"`: Structured data
• `"bibtex"`: For LaTeX/reference managers
• `"ris"`: For Endnote, Zotero, Mendeley

4. **Compare experiments**: Use `encode_compare_experiments` to check if two experiments are compatible for combined analysis (same organism, assembly, assay, biosample, etc.).

5. **Collection overview**: Use `encode_summarize_collection` for grouped statistics across your tracked experiments.

6. **Export data**: Use `encode_export_data` to export tracked experiments as CSV, TSV, or JSON for use in R, pandas, Excel.

Stored Metadata

When you track an experiment, the following fields are captured from the ENCODE Portal API and stored locally:

| Field | Description | Example | |-------|-------------|---------| | `accession` | ENCODE accession (primary key) | ENCSR123ABC | | `assay_title` | Assay type | Histone ChIP-seq | | `target` | Antibody target (ChIP/eCLIP) | H3K27ac-human | | `biosample_summary` | Full biosample description | pancreas tissue male adult (54 years) | | `organism` | Species | Homo sapiens | | `organ` | Organ or tissue of origin | pancreas | | `biosample_type` | Biosample classification | tissue, primary cell, cell line | | `status` | ENCODE release status | released | | `date_released` | Portal release date | 2020-07-15 | | `description` | Experiment description (from PI) | H3K27ac ChIP-seq on human pancreatic islets | | `lab` | Submitting laboratory | /labs/bradley-bernstein/ | | `award` | Funding award | /awards/U01HG007610/ | | `assembly` | Genome assembly | GRCh38 | | `replication_type` | Replicate strategy | isogenic, anisogenic | | `life_stage` | Developmental stage | adult, embryonic, child | | `url` | ENCODE Portal URL | https://www.encodeproject.org/experiments/ENCSR123ABC/ | | `notes` | User-provided notes | H3K27ac reference for islet enhancer study | | `raw_metadata` | Full JSON from API (up to 512KB) | (stored for future queries) |

Additionally, the tracker stores timestamps (`tracked_at`, `updated_at`) for audit trail purposes.

SQLite Schema Overview

The tracker uses a local SQLite database with WAL journal mode and foreign keys enabled. The schema consists of six tables:

**`tracked_experiments`** -- One row per ENCODE experiment. The `accession` column is the primary key. Indexes on `assay_title`, `organism`, and `organ` for fast filtered queries.

**`publications`** -- Publications linked to experiments. Stores PMID, DOI, title, authors (first 10), journal, year, abstract. Unique constraint on `(experiment_accession, pmid)` prevents duplicates.

**`pipeline_info`** -- ENCODE uniform processing pipeline details. Stores pipeline title, version, software list (as JSON array), and analysis status.

**`quality_metrics`** -- Per-file quality metrics from ENCODE audits. Stores file accession, metric type, and metric data (as JSON).

**`derived_files`** -- User-created files derived from ENCODE data. Stores file path, source accessions (as JSON array), tool used, parameters, and description. This is the backbone of provenance tracking.

**`external_references`** -- Cross-database links. Stores reference type (pmid, doi, geo_accession, nct_id, biorxiv_doi, dbgap), reference ID, and description. Unique constraint on `(experiment_accession, reference_type, reference_id)`.

The database location is `~/.encode_connector/tracker.db` (macOS/Linux) or `%USERPROFILE%\.encode_connector\tracker.db` (Windows). The directory is created automatically on first use.

Data Provenance

7. **Log derived files**: Use `encode_log_derived_file` when the user creates files from ENCODE data (filtered peaks, merged signals, etc.).

8. **View provenance**: Use `encode_get_provenance` to trace derived files back to source ENCODE data.

Cross-References

9. **Link external references**: Use `encode_link_reference` to attach PubMed IDs, DOIs, ClinicalTrials NCT IDs, bioRxiv DOIs, or GEO accessions to tracked experiments.

10. **Get references**: Use `encode_get_references` to retrieve linked external identifiers. These IDs can be passed to PubMed, bioRxiv, or ClinicalTrials MCP servers for further analysis.

---

Walkthrough 1: Building a Pancreatic Islet Epigenome Reference Collection

**Goal**: Curate a comprehensive set of histone modification ChIP-seq, ATAC-seq, and RNA-seq from human pancreatic islets for enhancer analysis. This is the foundational wor