encode-toolkit

Search ENCODE experiments with comprehensive filters.

Examples:

• Find all Histone ChIP-seq on human pancreas tissue: assay_title="Histone ChIP-seq", organ="pancreas", biosample_type="tissue"

• Find ATAC-seq on human brain: assay_title="ATAC-seq", organ="brain"

• Find RNA-seq on GM12878 cell line: assay_title="RNA-seq", biosample_term_name="GM12878"

• Find ChIP-seq targeting H3K27me3: assay_title="Histone ChIP-seq", target="H3K27me3"

• Find all mouse liver experiments: organism="Mus musculus", organ="liver"

• Free text search: search_term="CRISPR screen pancreatic"

Common assay_title values: "Histone ChIP-seq", "TF ChIP-seq", "ATAC-seq", "DNase-seq", "RNA-seq", "total RNA-seq", "WGBS", "Hi-C", "CUT&RUN", "CUT&Tag", "STARR-seq", "MPRA", "eCLIP", "CRISPR screen"

Common organ values: "pancreas", "liver", "brain", "heart", "kidney", "lung", "intestine", "skin of body", "blood", "spleen", "thymus"

biosample_type values: "tissue", "cell line", "primary cell", "in vitro differentiated cells", "organoid"

WHEN TO USE: Use as the primary entry point when users want to find experiments. Start with encode_get_facets if unsure what filters to use. RELATED TOOLS: encode_get_facets, encode_get_metadata, encode_search_files

Args: assay_title: Assay type (e.g., "Histone ChIP-seq", "ATAC-seq", "RNA-seq") organism: Species (default: "Homo sapiens"). Also: "Mus musculus" organ: Organ/tissue system (e.g., "pancreas", "brain", "liver") biosample_type: Sample classification ("tissue", "cell line", "primary cell", "organoid") biosample_term_name: Specific cell/tissue name (e.g., "GM12878", "HepG2", "pancreas") target: ChIP/CUT&RUN target (e.g., "H3K27me3", "CTCF", "p300") status: Data status (default: "released"). Also: "archived", "revoked" lab: Submitting lab name award: Funding project assembly: Genome assembly (e.g., "GRCh38", "mm10") replication_type: "isogenic", "anisogenic", or "unreplicated" life_stage: "embryonic", "postnatal", "child", "adult" sex: "male", "female", "mixed" treatment: Treatment name if perturbation experiment genetic_modification: Modification type ("CRISPR", "RNAi") perturbed: True for perturbation experiments only search_term: Free text search across all fields date_released_from: Start date (YYYY-MM-DD) for date range filter date_released_to: End date (YYYY-MM-DD) for date range filter limit: Max results to return (default 25, use larger for comprehensive searches) offset: Skip first N results (for pagination)

Returns: JSON with experiment results, total count, and pagination info.

Get full details for a specific ENCODE experiment by accession ID.

Returns complete experiment metadata including all associated files, quality metrics, controls, replicate information, and audit status.

WHEN TO USE: Use when you have a specific accession and need full details including files, quality metrics, and audit status. RELATED TOOLS: encode_list_files, encode_track_experiment, encode_compare_experiments

Args: accession: ENCODE experiment accession (e.g., "ENCSR133RZO", "ENCSR000AKS")

Returns: JSON with full experiment details and file listing.

List all files for a specific ENCODE experiment, with optional filters.

Examples:

• All BED files: experiment_accession="ENCSR133RZO", file_format="bed"

• FASTQs only: experiment_accession="ENCSR133RZO", file_format="fastq"

• Signal tracks: experiment_accession="ENCSR133RZO", output_category="signal"

• Default/recommended files: preferred_default=True

• Peaks from GRCh38: file_format="bed", output_type="IDR thresholded peaks", assembly="GRCh38"

Common file_format values: "fastq", "bam", "bed", "bigWig", "bigBed", "tsv", "hic"

Common output_type values: "reads", "alignments", "signal of unique reads", "signal of all reads", "fold change over control", "IDR thresholded peaks", "pseudoreplicated peaks", "replicated peaks", "gene quantifications", "transcript quantifications", "contact matrix"

WHEN TO USE: Use to browse files within a known experiment. Use encode_search_files instead to find files across experiments. RELATED TOOLS: encode_search_files, encode_get_file_info, encode_download_files

Args: experiment_accession: ENCODE experiment accession (e.g., "ENCSR133RZO") file_format: Filter by format ("fastq", "bam", "bed", "bigWig", "bigBed", etc.) file_type: Filter by specific type ("bed narrowPeak", "bed broadPeak", etc.) output_type: Filter by output type ("reads", "peaks", "signal", etc.) output_category: Filter by category ("raw data", "alignment", "signal", "annotation") assembly: Filter by genome assembly ("GRCh38", "hg19", "mm10") status: Filter by status ("released", "archived", "in progress") preferred_default: If True, return only default/recommended files limit: Max files to return (default 200)

Returns: JSON list of files with accession, format, size, download URL, and metadata.

Search files across ALL experiments with combined experiment + file filters.

This is powerful for finding specific file types across many experiments.

Examples:

• All BED files from human pancreas ChIP-seq: file_format="bed", assay_title="Histone ChIP-seq", organ="pancreas"

• FASTQs from mouse liver RNA-seq: file_format="fastq", assay_title="RNA-seq", organ="liver", organism="Mus musculus"

• All IDR peak files for H3K27me3: output_type="IDR thresholded peaks", target="H3K27me3"

• BigWig signal tracks from ATAC-seq on brain tissue: file_format="bigWig", assay_title="ATAC-seq", organ="brain", biosample_type="tissue"

WHEN TO USE: Use to find specific file types across ALL experiments. More powerful than encode_list_files for cross-experiment file discovery. RELATED TOOLS: encode_list_files, encode_batch_download, encode_get_file_info

Args: file_format: File format ("fastq", "bam", "bed", "bigWig", etc.) file_type: Specific file type ("bed narrowPeak", "bed broadPeak", etc.) output_type: Output type ("reads", "peaks", "signal", etc.) output_category: Output category ("raw data", "alignment", "signal", "annotation") assembly: Genome assembly ("GRCh38", "hg19", "mm10") assay_title: Filter by assay type of parent experiment organism: Filter by organism of parent experiment organ: Filter by organ of parent experiment biosample_type: Filter by biosample type ("tissue", "cell line", etc.) target: Filter by ChIP/CUT&RUN target status: File status (default: "released") preferred_default: If True, only default/recommended files search_term: Free text search limit: Max results (default 25) offset: Skip first N results (pagination)

Returns: JSON with file results, total count, and pagination info.

Download specific ENCODE files by accession to a local directory.

Downloads files from ENCODE to your local machine. Supports MD5 verification, concurrent downloads, and skip-if-already-downloaded.

WHEN TO USE: Use for downloading specific files by accession. For bulk downloads, prefer encode_batch_download. RELATED TOOLS: encode_batch_download, encode_search_files, encode_log_derived_file

Args: file_accessions: List of file accessions to download (e.g., ["ENCFF635JIA", "ENCFF388RZD"]) download_dir: Local directory path to save files (e.g., "/Users/you/data/encode") organize_by: How to organize downloaded files: - "flat": All files in download_dir (default) - "experiment": download_dir/ENCSR.../filename - "format": download_dir/bed/filename - "experiment_format": download_dir/ENCSR.../bed/filename verify_md5: Verify file integrity with MD5 checksum (default True)

Returns: JSON with download results for each file (path, size, success/error, MD5 status).

Get available filter values for ENCODE searches.

Use this to discover valid values for search parameters.

WHEN TO USE: Use to discover valid filter values before searching. Helps prevent typos in assay_title, organ, biosample_type etc. RELATED TOOLS: encode_get_facets, encode_search_experiments

Args: metadata_type: Type of metadata to retrieve. Options: - "assays": Available assay types (Histone ChIP-seq, ATAC-seq, RNA-seq, etc.) - "organisms": Available organisms (Homo sapiens, Mus musculus, etc.) - "organs": Available organ/tissue systems (pancreas, brain, liver, etc.) - "biosample_types": Biosample classifications (tissue, cell line, primary cell, etc.) - "file_formats": File format types (fastq, bam, bed, bigWig, etc.) - "output_types": Output data types (reads, peaks, signal, etc.) - "output_categories": Output categories (raw data, alignment, signal, etc.) - "assemblies": Genome assemblies (GRCh38, hg19, mm10, etc.) - "life_stages": Life stages (embryonic, adult, child, etc.) - "replication_types": Replication types (isogenic, anisogenic, unreplicated) - "statuses": Experiment statuses (released, archived, etc.) - "file_statuses": File statuses (released, archived, in progress, etc.)

Returns: JSON list of valid values for the specified metadata type.

Search for files and download them all in batch.

First searches for files matching the criteria, then downloads them. By default runs in dry_run mode to preview what would be downloaded. Set dry_run=False to actually download.

WHEN TO USE: Use for searching and downloading files in one step. Always use dry_run=True first to preview. For specific file accessions, use encode_download_files. RELATED TOOLS: encode_download_files, encode_search_files

Examples:

• Download all BED files from human pancreas ChIP-seq: file_format="bed", assay_title="Histone ChIP-seq", organ="pancreas", download_dir="/data/encode", dry_run=False

• Preview FASTQ downloads for mouse brain RNA-seq: file_format="fastq", assay_title="RNA-seq", organ="brain", organism="Mus musculus", download_dir="/data/encode"

• Download IDR peaks for H3K27me3 in GRCh38: output_type="IDR thresholded peaks", target="H3K27me3", assembly="GRCh38", download_dir="/data/encode", dry_run=False

Args: download_dir: Local directory to save files file_format: File format filter ("fastq", "bam", "bed", "bigWig", etc.) output_type: Output type filter ("reads", "peaks", "signal", etc.) output_category: Output category ("raw data", "alignment", "annotation", etc.) assembly: Genome assembly ("GRCh38", "mm10", etc.) assay_title: Assay type ("Histone ChIP-seq", "ATAC-seq", "RNA-seq", etc.) organism: Organism (default: "Homo sapiens") organ: Organ/tissue ("pancreas", "brain", "liver", etc.) biosample_type: Biosample type ("tissue", "cell line", "primary cell", etc.) target: ChIP/CUT&RUN target ("H3K27me3", "CTCF", etc.) preferred_default: If True, only download default/recommended files organize_by: File organization ("flat", "experiment", "format", "experiment_format") verify_md5: Verify downloads with MD5 checksums (default True) limit: Max files to download (default 100, safety limit) dry_run: If True (default), only preview what would be downloaded. Set False to download.

Returns: JSON with download preview (dry_run=True) or download results (dry_run=False).

Manage ENCODE API credentials for accessing restricted/unreleased data.

Most ENCODE data is public and requires no authentication. Credentials are only needed for unreleased or restricted datasets.

Credentials are stored securely in your OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Locker) and never in plaintext.

WHEN TO USE: Use only for accessing unreleased/restricted ENCODE data. Public data requires no authentication. RELATED TOOLS: encode_search_experiments

Args: action: What to do: - "store": Save new credentials (requires access_key and secret_key) - "check": Check if credentials are configured - "clear": Remove stored credentials access_key: Your ENCODE access key (only for action="store") secret_key: Your ENCODE secret key (only for action="store")

Returns: JSON with action result.

Get live filter counts from ENCODE to discover what data is available.

Returns faceted counts showing how many experiments/files exist for each filter value. Useful for exploring what's available before searching.

WHEN TO USE: Use to explore what data exists before searching. Shows counts per filter value. Best first step for unknown datasets. RELATED TOOLS: encode_get_metadata, encode_search_experiments

Examples:

• What assays are available for pancreas? organ="pancreas"

• What organs have Histone ChIP-seq data? assay_title="Histone ChIP-seq"

• What targets are available for mouse brain ChIP-seq? assay_title="Histone ChIP-seq", organism="Mus musculus", organ="brain"

Args: search_type: Object type ("Experiment" or "File") assay_title: Pre-filter by assay type organism: Pre-filter by organism organ: Pre-filter by organ biosample_type: Pre-filter by biosample type

Returns: JSON with facet names and their term counts.

Get detailed information about a specific ENCODE file.

WHEN TO USE: Use when you need detailed metadata for a specific file (size, md5, assembly, biological replicate info). RELATED TOOLS: encode_download_files, encode_list_files

Args: accession: File accession ID (e.g., "ENCFF635JIA")

Returns: JSON with file metadata including format, size, download URL, MD5, assembly, etc.

Track an ENCODE experiment locally with its publications, methods, and pipeline info.

Fetches full experiment metadata from ENCODE and stores it in a local SQLite database along with any associated publications (PMIDs, DOIs, authors, journal) and pipeline/analysis information (software versions, methods).

This is like adding an experiment to your "library" - similar to Endnote for papers.

WHEN TO USE: Use to save an experiment to your local library with publications and pipeline info. Required before compare or citations. RELATED TOOLS: encode_compare_experiments, encode_get_citations, encode_export_data

Args: accession: ENCODE experiment accession (e.g., "ENCSR133RZO") fetch_publications: Also fetch and store publications/citations (default True) fetch_pipelines: Also fetch and store pipeline/analysis info (default True) notes: Optional notes to attach to this experiment

Returns: JSON with tracking result including publications and pipeline info found.

List all experiments you've tracked locally, with optional filters.

Shows your local library of tracked ENCODE experiments, their metadata, publication counts, and derived file counts.

WHEN TO USE: Use to see all experiments in your local library. Filter by assay, organism, or organ. RELATED TOOLS: encode_summarize_collection, encode_export_data

Args: assay_title: Filter by assay type (partial match) organism: Filter by organism (partial match) organ: Filter by organ (partial match)

Returns: JSON with tracked experiments metadata table and tracker stats.

Get publications and citations for tracked experiments.

Returns publication data with authors, journal, DOI, PMID. Can export as BibTeX or RIS (Endnote/Zotero/Mendeley compatible).

WHEN TO USE: Use to get publication data for tracked experiments. Supports BibTeX and RIS export for reference managers. RELATED TOOLS: encode_track_experiment, encode_link_reference

Args: accession: Specific experiment accession. If None, returns all publications. export_format: Output format: - "json": Structured data (default) - "bibtex": BibTeX format for LaTeX - "ris": RIS format (Endnote, Zotero, Mendeley)

Returns: Publications in the requested format.

Analyze whether two ENCODE experiments are compatible for combined analysis.

Compares organism, genome assembly, assay type, biosample, organ, target, replication strategy, and lab to identify potential issues.

Both experiments must be tracked first (use encode_track_experiment).

WHEN TO USE: Use to check if two experiments are compatible for combined analysis. Both must be tracked first. RELATED TOOLS: encode_track_experiment, encode_list_tracked

Args: accession1: First experiment accession (e.g., "ENCSR133RZO") accession2: Second experiment accession (e.g., "ENCSR000AKS")

Returns: JSON compatibility report with verdict, issues, warnings, and recommendations.

Log a file you've derived from ENCODE data for provenance tracking.

Use this when you create new files from ENCODE data (e.g., running a pipeline, filtering peaks, merging samples). This creates a provenance record linking your derived file back to the original ENCODE source data.

WHEN TO USE: Use after creating files from ENCODE data (filtered peaks, merged signals). Creates provenance chain back to source. RELATED TOOLS: encode_get_provenance, encode_download_files

Args: file_path: Path to the derived file you created source_accessions: List of ENCODE accessions this file was derived from (experiment or file accessions, e.g., ["ENCSR133RZO", "ENCFF635JIA"]) description: What this derived file contains file_type: Type of file (e.g., "filtered_peaks", "merged_signal", "differential") tool_used: Tool/software used to create it (e.g., "bedtools intersect", "DESeq2") parameters: Parameters or command used

Returns: JSON with the provenance record ID.

Get provenance information for derived files.

Shows the chain from your derived files back to original ENCODE data, including what tools and parameters were used.

WHEN TO USE: Use to trace a derived file back to original ENCODE data. Shows tools and parameters used. RELATED TOOLS: encode_log_derived_file

Args: file_path: Get provenance for a specific derived file source_accession: List all files derived from a specific ENCODE accession

Returns: JSON provenance chain or list of derived files.

Export tracked experiments as a table (CSV, TSV, or JSON).

Creates a tabular export of all tracked experiments with metadata, publication counts, PMIDs, and derived file counts. Useful for loading into Excel, R, pandas, or sharing with collaborators.

PMIDs in the output can be directly used with PubMed MCP tools for further literature analysis.

WHEN TO USE: Use to create shareable tables of tracked experiments (CSV, TSV, JSON). Good for manuscripts and reports. RELATED TOOLS: encode_list_tracked, encode_summarize_collection

Args: format: Output format: - "csv": Comma-separated values (default, for Excel/spreadsheets) - "tsv": Tab-separated values (for R, pandas) - "json": JSON array (for programmatic use) assay_title: Filter by assay type (partial match) organism: Filter by organism (partial match) organ: Filter by organ (partial match)

Returns: Formatted table data in the requested format.

Summarize your tracked experiment collection with grouped statistics.

Provides an overview of tracked experiments grouped by assay type, target, organism, organ, biosample type, and lab. Shows total counts for publications, derived files, and external references.

Useful when tracking 10+ experiments and needing a bird's-eye view of your research data collection.

WHEN TO USE: Use for a bird's-eye view of tracked experiments grouped by assay, target, organ. Best for 10+ tracked experiments. RELATED TOOLS: encode_list_tracked, encode_export_data

Args: assay_title: Filter by assay type (partial match) organism: Filter by organism (partial match) organ: Filter by organ (partial match)

Returns: JSON summary with experiment counts grouped by multiple dimensions.

Link an external reference to a tracked ENCODE experiment.

This is the cross-server bridge. Attach PubMed IDs, bioRxiv DOIs, ClinicalTrials.gov NCT IDs, GEO accessions, or any external identifier to your tracked experiments for provenance and cross-referencing.

After finding a relevant paper with PubMed MCP or a preprint on bioRxiv, link it to the ENCODE experiment for future reference.

WHEN TO USE: Use to attach external IDs (PMID, DOI, GEO, NCT) to tracked experiments for cross-referencing. RELATED TOOLS: encode_get_references, encode_get_citations

Args: experiment_accession: ENCODE experiment accession (e.g., "ENCSR133RZO") reference_type: Type of external reference: - "pmid": PubMed ID (e.g., "32728249") - "doi": DOI (e.g., "10.1038/s41586-020-2493-4") - "nct_id": ClinicalTrials.gov ID (e.g., "NCT04567890") - "preprint_doi": bioRxiv/medRxiv DOI - "geo_accession": GEO accession (e.g., "GSE123456") - "other": Any other identifier reference_id: The actual identifier value description: Optional description of why this reference is linked

Returns: JSON with linking result.

Get external references linked to tracked experiments.

Returns PMIDs, DOIs, NCT IDs, GEO accessions and other identifiers linked to experiments. These identifiers can be directly passed to PubMed, bioRxiv, ClinicalTrials.gov, or other MCP tools.

WHEN TO USE: Use to retrieve external references linked to experiments. PMIDs can be passed to PubMed MCP tools. RELATED TOOLS: encode_link_reference, encode_get_citations

Args: experiment_accession: Filter by specific experiment (optional) reference_type: Filter by reference type (optional): "pmid", "doi", "nct_id", "preprint_doi", "geo_accession", "other"

Returns: JSON with linked external references.