/search-encode

name: search-encode
description: Search and explore ENCODE Project genomics data. Use when the user wants to find experiments, files, or explore what data is available for specific assays, organs, cell lines, or targets.

Search ENCODE Data

When to Use

• User wants to find ENCODE experiments matching specific criteria (assay, organ, cell type, target)
• User asks "what ENCODE data exists for [tissue/target/assay]?"
• User wants to explore available data before downloading
• User needs to find specific file types (BED, BAM, bigWig) across experiments
• User wants to know how many experiments exist for a condition
• User asks about available assays, organisms, or biosamples in ENCODE

Help the user find ENCODE experiments and files. Use the appropriate tools based on what they need.

Search Strategy

1. **Finding experiments**: Use `encode_search_experiments` with filters:

• `assay_title`: "Histone ChIP-seq", "ATAC-seq", "RNA-seq", "TF ChIP-seq", "Hi-C", "CUT&RUN", "WGBS", etc.
• `organ`: "pancreas", "brain", "liver", "heart", "kidney", "lung", etc.
• `biosample_type`: "tissue", "cell line", "primary cell", "organoid"
• `biosample_term_name`: specific name like "GM12878", "HepG2", "K562"
• `target`: ChIP/CUT&RUN target like "H3K27me3", "H3K4me3", "CTCF", "p300"
• `organism`: "Homo sapiens" (default) or "Mus musculus"

2. **Finding files across experiments**: Use `encode_search_files` when the user wants specific file types from multiple experiments.

3. **Exploring available data**: Use `encode_get_facets` to see counts of what exists before searching. Use `encode_get_metadata` to list valid filter values.

4. **Getting experiment details**: Use `encode_get_experiment` for full metadata on a single experiment. Use `encode_list_files` to see all files for one experiment.

Search Strategy Guide

Effective ENCODE searching follows a three-phase pattern: explore, search, refine. Jumping straight to a filtered search often produces empty results or misses relevant data.

Phase 1: Explore with Facets

Always start with `encode_get_facets` to understand what data exists. Facets return counts per filter value, so you can see immediately whether your target organ, assay, or biosample has data.

encode_get_facets(organ="pancreas")
  -> Shows: Histone ChIP-seq (42), ATAC-seq (8), RNA-seq (15), TF ChIP-seq (6), ...
  -> Also shows: biosample types, life stages, labs, replication types

This avoids the frustrating pattern of searching for data that does not exist. Facets may also reveal data you did not expect -- for example, CUT&RUN data where you only anticipated ChIP-seq, or organoid samples alongside tissue.

Phase 2: Validate Filter Values

Before searching, confirm that your filter values match ENCODE's controlled vocabulary. A mistyped assay name returns zero results with no error.

encode_get_metadata(metadata_type="assays")
  -> Returns all valid assay_title values: "Histone ChIP-seq", "TF ChIP-seq", "ATAC-seq", ...

Available metadata types: `assays`, `organisms`, `organs`, `biosample_types`, `file_formats`, `output_types`, `output_categories`, `assemblies`, `life_stages`, `replication_types`, `statuses`, `file_statuses`.

Phase 3: Search and Refine

Start with broad filters and add constraints one at a time. If a search returns too many results (>100), add a filter. If it returns zero, remove the most restrictive filter first.

# Too broad: 2,400 results
encode_search_experiments(assay_title="Histone ChIP-seq")

# Add organ: 42 results
encode_search_experiments(assay_title="Histone ChIP-seq", organ="pancreas")

# Add target: 6 results
encode_search_experiments(assay_title="Histone ChIP-seq", organ="pancreas", target="H3K27ac")

Pitfalls & Edge Cases

1. **Wrong assay_title values**: Assay names must match ENCODE's controlled vocabulary exactly. Run `encode_get_metadata(metadata_type="assays")` first to discover valid values. For example, use "Histone ChIP-seq" not "ChIP-seq" or "H3K27ac ChIP". 2. **Confusing biosample_term_name vs organ**: `organ` is a broad anatomical system (e.g., "pancreas", "brain"). `biosample_term_name` is a specific cell or tissue name (e.g., "GM12878", "islet of Langerhans"). Use `organ` for tissue-level exploration, `biosample_term_name` when you know the exact biosample. 3. **Not exploring first**: Always call `encode_get_facets` before searching to see what data exists. This avoids empty results and reveals unexpected data availability. For example, facets may show CUT&RUN data exists for your organ when you only expected ChIP-seq. 4. **Mixing organisms**: Human and mouse experiments use different assemblies (GRCh38 vs mm10) and cannot be directly compared. Always filter by `organism` to avoid mixing species in results. 5. **Expecting file-level results from experiment search**: `encode_search_experiments` returns experiments, not individual files. If the user wants specific BED or bigWig files, use `encode_search_files` instead with `file_format` and `output_type` filters. 6. **Searching for deprecated data**: The default `status="released"` is correct for most use cases. Archived or revoked experiments may have known quality issues. Only change status if the user explicitly needs historical data.

Gotchas

organ vs biosample_term_name vs biosample_type

These three filters address different levels of the biosample hierarchy. Using the wrong one produces unexpected results.

| Filter | What it means | Example values | When to use | |--------|---------------|----------------|-------------| | `organ` | Broad anatomical system | "pancreas", "brain", "heart", "liver" | Exploring all data for an organ system | | `biosample_term_name` | Exact biosample name | "GM12878", "K562", "islet of Langerhans", "HepG2" | You know the exact cell type or tissue name | | `biosample_type` | Category of biosample | "tissue", "cell line", "primary cell", "organoid", "in vitro differentiated cells" | Fi