/ucsc-browser

name: ucsc-browser
description: Query the UCSC Genome Browser REST API to retrieve regulatory tracks, DNA sequences, cCRE annotations, TF binding clusters, and track schemas for any genomic region. Use when the user wants to look up what regulatory elements exist at a genomic locus, retrieve DNA sequence under peaks, query ENCODE cCREs or TF rPeak clusters from UCSC, check what tracks are available for a genome assembly, get chromatin accessibility across cell types, or cross-reference ENCODE data with UCSC-hosted annotations. Also use when the user mentions UCSC, genome browser, cCRE lookup, SCREEN, TF binding clusters, DNA sequence retrieval, or track data extraction.

Query the UCSC Genome Browser REST API

When to Use

• User wants to query the UCSC Genome Browser REST API for tracks, sequences, or cCRE annotations
• User asks about "UCSC", "genome browser", "cCREs", "track hub", or "sequence retrieval"
• User needs to retrieve DNA sequences for peak regions or regulatory elements
• User wants to intersect ENCODE peaks with UCSC-hosted annotations (cCREs, conservation, repeat masker)
• Example queries: "get cCRE annotations for my region", "fetch DNA sequence under my peaks", "query UCSC for conservation scores at my enhancers"

Retrieve regulatory annotations, DNA sequences, TF binding data, and ENCODE-hosted tracks from the UCSC Genome Browser programmatic interface.

Scientific Rationale

**The question**: "What regulatory annotations exist at this genomic locus, and what is the underlying sequence?"

The UCSC Genome Browser hosts the most comprehensive collection of genome annotations, including ENCODE cCREs (926,535 human), TF rPeak clusters (21.8M from 912 factors across 1,152 biosamples), DNase clusters, conservation scores, and gene models. The REST API at `api.genome.ucsc.edu` enables programmatic access without authentication.

Why UCSC Complements the ENCODE Portal

The ENCODE Portal (`encodeproject.org`) provides experiment-level data — individual ChIP-seq peaks, BAM files, quality metrics. UCSC provides **aggregated, cross-experiment annotations**: which cCREs overlap your region, which TFs bind there across all ENCODE biosamples, and what the underlying DNA sequence is. Together they answer: "What did ENCODE find at this locus?" (UCSC) and "What are the specific experiments behind it?" (ENCODE Portal).

Literature Support

• **ENCODE Project Consortium 2020** (Nature, ~1,656 citations): Registry of 926,535 human cCREs hosted on UCSC as `encodeCcreCombined` track. [DOI](https://doi.org/10.1038/s41586-020-2493-4)
• **Nassar et al. 2023** (Nucleic Acids Research): The UCSC Genome Browser database: 2023 update. [DOI](https://doi.org/10.1093/nar/gkac1072)
• **ENCODE4 TF Atlas**: 21.8M TF rPeak clusters from 912 factors in 1,152 biosamples, hosted as `TFrPeakClusters` track on UCSC.

API Reference

**Base URL**: `https://api.genome.ucsc.edu`

**No authentication required.** Rate limit: ~1 request/second recommended. Use semicolons (`;`) to separate parameters.

**Coordinate system**: Half-open, 0-based start (matches BED format). `start=1000000;end=1000100` returns 100 bases starting at position 1,000,000.

Step 1: Discover Available Tracks

Before querying data, check what tracks exist for your assembly:

# List all tracks for hg38
curl "https://api.genome.ucsc.edu/list/tracks?genome=hg38"

# Search for ENCODE-specific tracks
curl "https://api.genome.ucsc.edu/search?search=encode+regulation&genome=hg38&categories=trackDb"

# Get schema (field definitions) for a track
curl "https://api.genome.ucsc.edu/list/schema?genome=hg38;track=encodeCcreCombined"

Key ENCODE Tracks on UCSC (hg38)

| Track ID | Description | Data Type | Source | |----------|-------------|-----------|--------| | `encodeCcreCombined` | 926,535 candidate cis-regulatory elements (V3) | bigBed 9+ | ENCODE Phase 3 | | `TFrPeakClusters` | 21.8M TF rPeak clusters, 912 factors, 1,152 biosamples | bigBed 12+ | ENCODE 4 | | `wgEncodeRegDnaseClustered` | 2.1M+ DNase clusters across 95 cell types | MySQL table | ENCODE 2/3 | | `wgEncodeRegTfbsClustered` | TF binding site clusters (legacy) | MySQL table | ENCODE 2/3 |

Key Non-ENCODE Regulatory Tracks

| Track ID | Description | Use Case | |----------|-------------|----------| | `cpgIslandExt` | CpG islands | Promoter identification | | `rmsk` | RepeatMasker | Filter repetitive elements | | `snp155` | dbSNP 155 with ClinVar | Variant annotation | | `phastCons100way` | Conservation scores (100 vertebrates) | Evolutionary constraint | | `phyloP100way` | Per-base conservation (100 vertebrates) | Variant impact |

Step 2: Query ENCODE cCREs at a Locus

The most common use case — what regulatory elements does ENCODE predict at this region?

# Get all cCREs in a 100kb window
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=encodeCcreCombined;chrom=chr1;start=1000000;end=1100000"

# Use jsonOutputArrays for named fields (recommended)
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=encodeCcreCombined;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

Response Fields (encodeCcreCombined)

| Field | Description | Example | |-------|-------------|---------| | `chrom` | Chromosome | chr1 | | `chromStart` | Start (0-based) | 999856 | | `chromEnd` | End | 1000009 | | `name` | ENCODE accession | EH38E1310344 | | `score` | Signal strength (0-1000) | 312 | | `encodeLabel` | cCRE class | PLS, pELS, dELS, CTCF-only | | `zScore` | Max DNase Z-score | 3.1283 | | `ccre` | Full classification | PLS,CTCF-bound |

cCRE Classification Key

| Class | Full Name | Biochemical Signature | |-------|-----------|----------------------| | PLS | Promoter-like signature | DNase+ H3K4me3+ near TSS | | pELS | Proximal enhancer-like | DNase+ H3K27ac+ within 2kb of TSS | | dELS | Distal enhancer-like | DNase+ H3K27ac+ >2kb from TSS | | CTCF-only | CTCF-only | DNase+ CTCF+ (no H3K4me3/H3K27ac) | |