Ucsc Browser

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
• Nassar et al. 2023 (Nucleic Acids Research): The UCSC Genome Browser database: 2023 update. DOI
• 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)

Key Non-ENCODE Regulatory Tracks

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)

cCRE Classification Key

Step 3: Query TF Binding at a Locus

Which transcription factors bind at your region across all ENCODE biosamples?

# Get TF rPeak clusters in a region
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=TFrPeakClusters;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

Response Fields (TFrPeakClusters)

Cross-reference with ENCODE Portal: The exp field contains ENCODE experiment accessions. Use encode_get_experiment to get full metadata:

encode_get_experiment(accession="ENCSR...")

Step 4: Retrieve DNA Sequence

Get the underlying DNA sequence for regulatory elements:

# Get sequence for a region
curl "https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chr1;start=1000000;end=1000500"

# Get reverse complement
curl "https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chr1;start=1000000;end=1000500;revComp=1"

Response includes a dna field with the nucleotide sequence.

Use cases for sequence retrieval:

• Extract sequence under ENCODE peaks for motif analysis (HOMER, MEME)
• Get sequence for CRISPR guide design at regulatory elements
• Check for known TF binding motifs at variants of interest
• Verify sequence context around GWAS variants

Step 5: Query DNase Accessibility Across Cell Types

# DNase clusters (95 cell types)
curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=wgEncodeRegDnaseClustered;chrom=chr1;start=1000000;end=1100000;jsonOutputArrays=1"

The sourceCount field tells you how many of the 95 cell types show accessibility at each site — a measure of how constitutive vs tissue-specific the element is.

Step 6: Bulk Data Access with Command-Line Tools

For genome-wide queries, use UCSC command-line utilities instead of the REST API (which caps at 1M items):

# Download UCSC tools (macOS example)
# Available at: https://hgdownload.gi.ucsc.edu/admin/exe/

# Extract ENCODE cCREs for a region from hosted bigBed
bigBedToBed https://hgdownload.gi.ucsc.edu/gbdb/hg38/encode3/encodeCcreCombined.bb \
  -chrom=chr1 -start=1000000 -end=2000000 stdout

# Extract TF rPeak clusters
bigBedToBed https://hgdownload.gi.ucsc.edu/gbdb/hg38/bbi/ENCODE4/TFrPeakClusters.bb \
  -chrom=chr1 -start=1000000 -end=2000000 stdout

# Summarize bigWig signal over regions
bigWigSummary http://path/to/signal.bw chr1 1000000 1100000 10

MySQL Direct Access (for legacy tables)

mysql --user=genome --host=genome-mysql.gi.ucsc.edu -A -P 3306 -D hg38 \
  -e "SELECT * FROM wgEncodeRegDnaseClustered WHERE chrom='chr1' AND chromStart >= 1000000 AND chromEnd <= 1100000;"

Practical Workflow: ENCODE Portal + UCSC Integration

A typical regulatory analysis workflow combining both:

1. Search ENCODE for tissue-specific experiments:
   encode_search_experiments(assay_title="Histone ChIP-seq", target="H3K27ac", organ="pancreas")

2. Get experiment details and download peaks:
   encode_list_files(experiment_accession="ENCSR...", output_type="IDR thresholded peaks", assembly="GRCh38")

3. For each peak region, query UCSC for regulatory context:
   curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=encodeCcreCombined;chrom=CHR;start=START;end=END;jsonOutputArrays=1"

4. Check which TFs bind at each peak:
   curl "https://api.genome.ucsc.edu/getData/track?genome=hg38;track=TFrPeakClusters;chrom=CHR;start=START;end=END;jsonOutputArrays=1"

5. Get DNA sequence for motif analysis:
   curl "https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=CHR;start=START;end=END"

6. Track and log provenance:
   encode_track_experiment(accession="ENCSR...", notes="Pancreas H3K27ac - UCSC cCRE overlap analysis")

Pitfalls and Caveats

1. 1M item cap: REST API returns maximum 1,000,000 items per query. For genome-wide analyses, iterate by chromosome or use command-line tools.
2. No keyword filtering: The API returns raw track data. Filtering (e.g., only PLS elements, only zScore > 5) must be done client-side after retrieval.
3. Coordinate system mismatch: UCSC uses 0-based half-open (BED format). VCF and GFF use 1-based. Always verify coordinate systems when cross-referencing.
4. Legacy vs current tracks: Tracks with wgEncode prefix are from ENCODE 2/3 and stored in MySQL tables. ENCODE 4 data uses bigBed files accessed via the REST API. Access methods differ.
5. cCRE version: The encodeCcreCombined track contains V3 cCREs (926,535). The expanded V4 registry (2.35M cCREs, Moore et al. 2024) may not yet be reflected on UCSC — check the SCREEN portal for the latest.
6. Mirror availability: Use api.genome.ucsc.edu (US), genome-euro.ucsc.edu (EU), or genome-asia.ucsc.edu (Asia) based on your location.

Walkthrough: Visualizing ENCODE Data in the UCSC Genome Browser

Goal: Use UCSC Genome Browser REST API to retrieve candidate cis-regulatory elements (cCREs) and custom track data that complement ENCODE experiments, enabling genome-wide regulatory visualization. Context: UCSC Genome Browser hosts ENCODE-derived cCRE tracks and provides REST API access to sequence, annotations, and track data.

Step 1: Find ENCODE experiments to visualize

encode_search_experiments(assay_title="ATAC-seq", organ="heart", organism="Homo sapiens", limit=5)

Expected output:

{
  "total": 18,
  "results": [
    {"accession": "ENCSR100HRT", "assay_title": "ATAC-seq", "biosample_summary": "heart left ventricle", "status": "released"}
  ]
}

Step 2: Get ENCODE file URLs for UCSC track hub

encode_get_file_info(accession="ENCFF200BW")

Expected output:

{
  "accession": "ENCFF200BW",
  "file_format": "bigWig",
  "output_type": "fold change over control",
  "href": "https://www.encodeproject.org/files/ENCFF200BW/@@download/ENCFF200BW.bigWig",
  "assembly": "GRCh38",
  "file_size_mb": 45.2
}

Interpretation: Use the bigWig download URL directly in a UCSC custom track or track hub for visualization.

Step 3: Query UCSC cCRE track for the region of interest

Using UCSC REST API (via skill guidance):

GET https://api.genome.ucsc.edu/getData/track?genome=hg38&track=encodeCcreCombined&chrom=chr1&start=1000000&end=1100000

Expected response (key fields):

{
  "encodeCcreCombined": [
    {"chrom": "chr1", "chromStart": 1020500, "chromEnd": 1021200, "name": "EH38E1234567", "ucscLabel": "pELS"},
    {"chrom": "chr1", "chromStart": 1050800, "chromEnd": 1051500, "name": "EH38E1234568", "ucscLabel": "dELS"}
  ]
}

Interpretation: pELS = proximal enhancer-like signature, dELS = distal enhancer-like signature. These cCRE classifications are derived from ENCODE data and provide standardized regulatory element annotations.

Step 4: Retrieve sequence for motif analysis

GET https://api.genome.ucsc.edu/getData/sequence?genome=hg38&chrom=chr1&start=1020500&end=1021200

Use the retrieved sequence for downstream motif scanning with → jaspar-motifs.

Step 5: Cross-reference with liftOver for assembly conversion

If you have hg19 coordinates that need conversion:

# Use liftover-coordinates skill for assembly conversion
# Then query UCSC API with GRCh38 coordinates

Integration with downstream skills

• UCSC cCRE annotations complement → regulatory-elements ENCODE-based classification
• Sequence retrieval feeds into → jaspar-motifs for TF motif scanning
• UCSC track hub URLs support → visualization-workflow genome browser sessions
• cCRE coordinates integrate with → peak-annotation for regulatory element assignment
• Assembly conversion via → liftover-coordinates ensures correct UCSC API queries

Code Examples

1. Search ENCODE for data to visualize on UCSC

encode_search_experiments(
  assay_title="ATAC-seq",
  organ="brain"
)

Expected output:

{
  "total": 24,
  "experiments": [
    {
      "accession": "ENCSR789XYZ",
      "assay_title": "ATAC-seq",
      "biosample_summary": "brain tissue female adult (53 years)"
    }
  ]
}

2. Get file details for UCSC track hub setup

encode_list_files(
  accession="ENCSR789XYZ",
  file_format="bigWig",
  assembly="GRCh38"
)

Expected output:

{
  "total": 4,
  "files": [
    {
      "accession": "ENCFF456DEF",
      "file_format": "bigWig",
      "output_type": "fold change over control",
      "assembly": "GRCh38",
      "file_size_mb": 125.3,
      "href": "/files/ENCFF456DEF/@@download/ENCFF456DEF.bigWig"
    }
  ]
}

Integration

Related Skills

Presenting Results

• Present UCSC links as clickable URLs with region, tracks, and assembly specified. Include direct session links when possible. Suggest: "Would you like to create a UCSC track hub for these experiments?"

For the request: "$ARGUMENTS"