encode-ccres-database

---
name: encode-ccres-database
description: >
    Query the ENCODE Registry of cis-Regulatory Elements (cCREs) via the SCREEN
    GraphQL API, or make custom queries to the ENCODE Portal REST API for
    experiments and files (ChIP-seq peaks, etc.). Use when you want to query
    regulatory annotations or raw experimental data across human cell types.
---

# ENCODE Database Skill

This skill allows you to query the ENCODE Registry of cCREs (candidate
cis-Regulatory Elements) via the SCREEN GraphQL API. It helps identify
functional non-coding DNA elements (like Promoters, Enhancers, and insulators)
by analyzing biochemical signatures (DNase, H3K4me3, H3K27ac, CTCF).

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If .licenses/encode_ccres_database_LICENSE.txt does
    not already exist in the workspace root directory then (1) prominently
    notify the user to check the terms at
    https://www.encodeproject.org/help/rest-api/, then (2) create the file
    recording the notification text and timestamp.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the
    database rather than accessing the database directly. The scripts
    automatically enforce the required rate limit gracefully.
-   **Parsing Output**: Do NOT use `cat` to read the entire JSON output file
    into context, as it can be extremely large. You MUST use `jq` to efficiently
    parse and extract relevant fields.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

### Quick Start

```bash
# Search cCREs by coordinates
uv run scripts/screen_api.py search --chromosome chr11 \
  --start 5205263 --end 5207263 \
  --output /tmp/search.json

# Get details for a specific cCRE
uv run scripts/screen_api.py details EH38E2941922 \
  --output /tmp/details.json
```

All subcommands write JSON to disk. Always save output in a temporary location
like `/tmp/`.

### Identifying High-Confidence ("Type A") Biosamples

Biosamples in ENCODE are often categorized by their data completeness. **"Type
A"** (or high-confidence) biosamples are those that have experimental data for
all four core epigenetic markers: **DNase, H3K4me3, H3K27ac, and CTCF**.

The `biosamples` and `details` commands automatically enrich their output with
an `is_type_a` boolean flag for each biosample.

**Example: Finding high-confidence cell types**

```bash
uv run scripts/screen_api.py biosamples --output /tmp/biosamples.json
# Use jq to filter for Type A biosamples
jq '.data.ccREBiosampleQuery.biosamples[] | select(.is_type_a == true) | .displayname' /tmp/biosamples.json
```

### Parsing Output (CRITICAL)

**Do NOT use `cat` to read the entire JSON output file into context, as it**
**can be extremely large.** Instead, you MUST use `jq` to efficiently parse and
extract the relevant fields from the JSON file saved by the script. If `jq` is
not available on the system, write your own Python filtering code (e.g.,
`python3 -c "import json..."`) to extract the necessary data.

For a complete reference of the JSON structure returned by eachmcommand (so you
know which fields to query with `jq`), read
`references/json_output_structure.md`.

### Available Commands

-   `search`: Search cCREs by coordinates, accessions, or epigenetic signals.

    ```bash
    uv run scripts/screen_api.py search \
        --chromosome chr11 --start 5205263 --end 5207263 \
        --output /tmp/search.json
    ```

-   `nearby-genes`: Find nearby genes for given cCRE accessions.

    ```bash
    uv run scripts/screen_api.py nearby-genes \
        EH38E1516972 --output /tmp/nearby.json
    ```

-   `details`: Get detailed information and biosample-specific max Z-scores for
    a specific cCRE.

    ```bash
    uv run scripts/screen_api.py details EH38E2941922 \
        --output /tmp/details.json
    ```

-   `biosamples`: Get biosample metadata for an assembly.

    ```bash
    uv run scripts/screen_api.py biosamples \
        --output /tmp/biosamples.json
    ```

-   `orthologs`: Get orthologous cCREs in another assembly.

    ```bash
    uv run scripts/screen_api.py orthologs EH38E2941922 \
        --output /tmp/orthologs.json
    ```

-   `linked-genes`: Find linked genes via methods like HiC or eQTLs.

    ```bash
    uv run scripts/screen_api.py linked-genes \
        EH38E1516972 --output /tmp/linked.json
    ```

-   `gene-expression`: Get gene expression (TPM) across all biosamples for a
    named gene. Internally resolves the gene symbol to an Ensembl gene ID, then
    queries per-biosample RNA-seq quantifications.

    ```bash
    uv run scripts/screen_api.py gene-expression GAPDH \
        --output /tmp/gene_expr.json
    ```

-   `entex`: Get ENTEx data for a cCRE or genomic region.

    ```bash
    uv run scripts/screen_api.py entex \
        --accession EH38E1310345 \
        --output /tmp/entex.json
    ```

    ```bash
    uv run scripts/screen_api.py entex \
        --region chr1:1000068:1000409 \
        --output /tmp/entex.json
    ```

-   `gwas`: Query genome-wide association studies, SNPs, or enrichment data.

    ```bash
    uv run scripts/screen_api.py gwas studies \
        --output /tmp/gwas.json
    ```

    ```bash
    uv run scripts/screen_api.py gwas snps --study \
        Ahola-Olli_AV-27989323-Eotaxin_levels \
        --output /tmp/gwas_snps.json
    ```

You can supply the `--assembly mm10` or `--assembly grch38` flag to explicitly
request a specific assembly for most commands. By default, the script targets
`grch38` but will automatically fall back to `mm10` if no results are found or
if the query fails.

## ENCODE Portal REST API (Direct Access)

For accessing raw experiments, ChIP-seq peaks, or other datasets that are not
represented as cCREs in SCREEN, use the `scripts/encode_portal_api.py` script.
It allows custom queries to the ENCODE Portal REST API.

### Usage

```bash
uv run scripts/encode_portal_api.py search "type=Experiment&target.label=ZNF549" --output /tmp/znf549_experiments.json
```

### Data Analysis Tips

When analyzing `.bed` or `.bigBed` files downloaded from ENCODE, standard
bioinformatics tools are highly recommended for finding overlaps (e.g., between
gene promoters and peaks):

-   **`bedtools`**: For fast mathematical operations on genomic intervals.
-   **`bigBedToBed`**: For converting binary BigBed files to readable BED
    format.
-   **`pybedtools`**: A Python wrapper for `bedtools`.

Write custom logic if these tools are not pre-installed.

## Custom Queries (SCREEN GraphQL)

If you need to make a complex GraphQL query that the script does not support,
read `references/graphql_schema.md` for a reference of available queries,
arguments, and return fields in the SCREEN GraphQL API.