Ucsc Conservation And Tfbs

Google DeepMindOfficialPublished by Google DeepMind

Skill
Tool integration
Science and research
Apache-2.0
Low risk
Has scripts

From the author

Fetch Evolutionary Conservation scores (phyloP, phastCons) and Transcription Factor Binding Sites (TFBS) from the UCSC Genome Browser. Use when analyzing whether genomic variants or regions are evolutionarily conserved, functionally important, or bounded by TF regulators across major projects (ENCODE, JASPAR, ReMap).

— the description by Google DeepMind

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a programmatic interface to retrieve genomic data from the UCSC Genome Browser, specifically focusing on evolutionary constraint scores and regulatory element binding sites. It enables researchers to analyze genomic variants by fetching phyloP and phastCons scores to assess functional importance, or by querying TFBS tracks from major databases like ENCODE, JASPAR, and ReMap to investigate regulatory disruption. The skill includes helper scripts to manage data retrieval, handle large outputs, and support various genome assemblies and evolutionary collections.

What it does

Retrieves phyloP scores for individual base-level evolutionary constraint analysis.
Fetches phastCons scores and conserved elements for regional functional analysis.
Queries transcription factor binding sites (TFBS) from ENCODE, JASPAR, and ReMap tracks.
Supports multiple evolutionary depths including vertebrate, mammal, and primate alignments.
Provides statistical analysis of conservation scores to identify potentially accelerated regions.
Allows discovery of available genomic tracks through search and group filtering.

When to use it

When evaluating the functional impact or pathogenicity of non-coding genomic variants.
When determining if a specific genomic region is evolutionarily conserved across species.
When investigating whether a variant disrupts known transcription factor binding sites.
When comparing regulatory elements against established ChIP-seq or predicted binding data.

Advantages

Automates complex queries to the UCSC Genome Browser database.
Provides standardized metrics for evolutionary constraint and regulatory binding.
Supports flexible evolutionary depth settings for comparative genomics.
Includes built-in rate limiting and large-output management for stable performance.

Usage examples

“Get the phyloP conservation scores for the variant at chr1:215867804.”: The agent executes the conservation script to return the evolutionary constraint score for the specified base.
“Find all TP53 binding sites in the region chr6:36670000-36690000 using the JASPAR 2024 track.”: The agent filters the JASPAR 2024 track for TP53 and returns the identified binding sites within the requested coordinates.
“Analyze the evolutionary acceleration of the region chr5:1045330-1046172.”: The agent computes mean, min, and max phyloP scores and provides a boolean indicator of evolutionary acceleration.
“List all available tracks related to regulation for the hg38 assembly.”: The agent returns a list of regulatory tracks available in the UCSC Genome Browser for hg38.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/google-deepmind/ucsc-conservation-and-tfbs/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip ucsc-conservation-and-tfbs.zip -d .agents/skills

Documentation by Google DeepMind

Conservation Scores & TFBS Lookup (UCSC)

This skill provides access to evolutionary constraint scores and conserved elements from the UCSC Genome Browser. It retrieves scores from the PHAST package — specifically phastCons (identifying functional blocks) and phyloP (measuring individual site constraint) — calculated from multiple alignments.

Use this skill to determine if a non-coding variant hits a site that hasn't changed since a common ancestor (which is a strong signal for pathogenicity) or to find conservation peaks across a regulatory element.

Prerequisites

uv: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.
User Notification: If .licenses/ucsc_conservation_and_tfbs_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://genome.ucsc.edu/conditions.html and https://genome.ucsc.edu/goldenPath/help/api.html, 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.
Large Output Handling: Always pass --output to redirect output to a file. Parse it separately (using jq or your own code).
Notification: If this skill is used, ensure this is mentioned in the output.

Utility Scripts

This skill includes scripts to query different types of genomic data from UCSC:

scripts/get_conservation.py: For Evolutionary Conservation scores (phyloP, phastCons).
scripts/get_tfbs.py: For Transcription Factor Binding Sites (TFBS).
scripts/list_tracks.py: For listing available tracks based on search or group constraints.

Always use the hg38 genome assembly by default, unless the user has specified otherwise.

Fetching Conservation for Specific Variants

To get the evolutionary constraint at a single base, or a list of specific bases. This is optimal for single nucleotide variants (SNVs). phyloP is the best metric for individual bases.

uv run scripts/get_conservation.py --coordinates "chr1:215867804" "chr1:215867823" --output /tmp/cons_output.json

Fetching Regions and Conserved Elements

To identify "conservation peaks" across a non-coding regulatory element (like an enhancer) to see if an ISM-predicted importance peak aligns with evolutionary history. phastCons is best for functional windows due to HMM smoothing. The --conserved-elements flag will also retrieve predefined blocks under extreme constraint.

uv run scripts/get_conservation.py --coordinates "chr8:11748914-11749085" --conserved-elements --output /tmp/region_cons.json

Lineage-Specific Constraints

You can control the evolutionary depth using the --collection flag. The default (vertebrate) uses the 100-vertebrate Multiz alignment for both hg38 and hg19, matching the UCSC Genome Browser's default comparative genomics tracks.

hg38 Collections

vertebrate (default): UCSC 100-vertebrate Multiz alignment. phyloP: phyloP100way, phastCons: phastCons100way.
mammal: Hiller Lab 470-way mammalian alignment. phyloP: phyloP470wayBW, phastCons: phastCons470way.
primate: UCSC 30-primate Multiz alignment. phyloP: phyloP30way, phastCons: phastCons30way.

hg19 Collections

vertebrate (default): UCSC 100-vertebrate Multiz alignment. phyloP: phyloP100way, phastCons: phastCons100way.
vertebrate46: UCSC 46-vertebrate Multiz alignment (legacy). phyloP: phyloP46wayAll, phastCons: phastCons46way.
mammal: 46-way placental mammal subset. phyloP: phyloP46wayPlacental, phastCons: phastCons46wayPlacental.
primate: 46-way primate subset. phyloP: phyloP46wayPrimates, phastCons: phastCons46wayPrimates.

# hg38 mammal (Hiller 470-way)
uv run scripts/get_conservation.py --coordinates "chr5:1045330-1046172" --collection mammal --output /tmp/mammal_cons.json

# hg19 with legacy 46-vertebrate alignment
uv run scripts/get_conservation.py --coordinates "chr5:1045330-1046172" --genome hg19 --collection vertebrate46 --output /tmp/vert46_cons.json

Analyzing Evolutionary Acceleration

To analyze whether a specific locus is undergoing evolutionary acceleration (i.e. evolving more rapidly than the neutral drift baseline), use --analyze. This will compute scalar statistics (mean, min, max) for phyloP scores and provide a heuristic boolean is_accelerated to simplify your evaluation.

uv run scripts/get_conservation.py --coordinates "chr5:1045330-1046172" --analyze --output /tmp/accelerated_cons.json

Fetching Transcription Factor Binding Sites (TFBS)

To identify transcription factor binding sites for a given genomic interval. This is useful for interpreting non-coding variants that might disrupt TF binding.

Run scripts/get_tfbs.py with --coordinates and --tracks. You can query multiple tracks at once.

uv run scripts/get_tfbs.py --coordinates "chr11:1001000-1010000" --tracks encRegTfbsClustered --output /tmp/tfbs_encode.json

JASPAR tracks may return very large result sets. Use --tf-filter to keep only items whose TFName field contains the given substring (case-insensitive):

uv run scripts/get_tfbs.py --coordinates "chr6:36670000-36690000" --tracks jaspar2024 --tf-filter TP53 --output /tmp/tp53_sites.json

Common Verified Tracks (hg38)

ENCODE: encRegTfbsClustered (TF Clusters)
JASPAR: jaspar2026, jaspar2024 (Predicted TFBS)
ReMap: ReMapTFs (ChIP-seq Atlas)

[!CAUTION] Tracks like jaspar or ReMap without years are often "container" tracks and will fail with a 400 error. Always use the specific subtrack name (e.g., jaspar2026).

Listing Available Tracks

To list available tracks (such as different versions of JASPAR, or purely to discover what tracks exist for a particular genome assembly):

uv run scripts/list_tracks.py --search "jaspar" --output /tmp/jaspar_tracks.json

You can also filter by functional group:

uv run scripts/list_tracks.py --group "regulation" --output /tmp/regulation_tracks.json

Anti-Patterns

DON'T query mammalian (--collection mammal) constraint if you are explicitly looking for deep evolutionary roots across all vertebrates. Use the default vertebrate collection.
DON'T use this skill for determining the ancestral state reconstruction of a nucleotide (this skill provides measures of how much sites have changed, not what the ancestral nucleotide was).
DON'T assume low conservation strictly means neutral/useless sequence; it could also reflect a high local mutation rate which conservation scores alone cannot distinguish.
DON'T print output on standard out, or run cat on output to files. The output is too large. Use jq or write your own code to parse the output files.
DON'T use hg19 unless the user has explicitly asked for it. The default should be to always use hg38.

Files

ATTRIBUTION.mdAdded by AutoGineer934 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md7.5 KiB
references/citation.bib810 B
scripts/get_conservation.pyScript7.5 KiB
scripts/get_tfbs.pyScript4.9 KiB
scripts/list_tracks.pyScript4.2 KiB

scripts/get_tfbs.py

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Fetches Transcription Factor Binding Sites (TFBS) from UCSC Database."""

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "polite-http",
# ]
# ///

import argparse
import json
import re
import sys
from typing import Any
from polite_http import http_client

UCSC_API_URL = "https://api.genome.ucsc.edu/getData/track"

api_client = http_client.HttpClient("https://api.genome.ucsc.edu/", qps=0.05)


def parse_coordinate(coord_str: str) -> tuple[str, int, int]:
  """Parses a coordinate string like 'chr1:100-200' or 'chr1:100'."""
  match = re.match(r"^(chr[0-9XYM]+|\w+):(\d+)(?:-(\d+))?$", coord_str)
  if not match:
    print(
        f"Error: Invalid coordinate format '{coord_str}'. Expected"
        " 'chr:start-end' or 'chr:pos'."
    )
    sys.exit(1)

  chrom = match.group(1)
  start = int(match.group(2))
  if match.group(3):
    end = int(match.group(3))
  else:
    # If no end provided, assume a 1bp region (start and start+1)
    end = start + 1
  return chrom, start, end


def get_tfbs_data(
    chrom: str, start: int, end: int, track: str, genome: str = "hg38"
) -> dict[str, Any]:
  """Fetches track data for a given region."""
  url = f"{UCSC_API_URL}?genome={genome}&track={track}&chrom={chrom}&start={start}&end={end}"
  print(f"Requesting URL: {url}")
  return api_client.fetch_json(url)


def main():
  parser = argparse.ArgumentParser(
      description=(
          "Fetch Transcription Factor Binding Sites (TFBS) from UCSC Database."
      )
  )
  parser.add_argument(
      "--coordinates",
      required=True,
      nargs="+",
      help=(
          "One or more genomic coordinates (e.g., 'chr1:100-200' or"
          " 'chr1:100')."
      ),
  )
  parser.add_argument(
      "--tracks",
      required=True,
      nargs="+",
      help=(
          "One or more track names or aliases (e.g., 'encRegTfbsClustered',"
          " 'jaspar2026', 'ReMapTFs')."
      ),
  )
  parser.add_argument(
      "--tf-filter",
      default=None,
      help=(
          "Optional case-insensitive filter on the TFName field. Only items"
          " whose TFName contains this substring are kept (e.g., 'TP53')."
      ),
  )
  parser.add_argument(
      "--output",
      required=True,
      help="Filename where all successful output is written in JSON format.",
  )
  parser.add_argument(
      "--genome", default="hg38", help="Genome assembly. Defaults to hg38."
  )

  args = parser.parse_args()

  results = {}
  for coord in args.coordinates:
    chrom, start, end = parse_coordinate(coord)
    region_result = {"coordinate": f"{chrom}:{start}-{end}", "tracks": {}}

    for track in args.tracks:
      print(f"Fetching {track} for region {chrom}:{start}-{end}...")
      data = get_tfbs_data(chrom, start, end, track, genome=args.genome)

      # Extract actual track data items from the JSON.
      if "error" in data:
        print(f"API Error for track '{track}': {data['error']}")
        region_result["tracks"][track] = {"error": data["error"]}
        continue

      # Try both track name and chromosome as key
      track_items = data.get(track, [])
      if not track_items and chrom in data:
        track_items = data.get(chrom, [])

      # Fallback to look for ANY list that looks like data
      if not track_items:
        for k, v in data.items():
          if isinstance(v, list) and k not in [
              "downloadTime",
              "downloadTimeStamp",
              "dataTime",
              "dataTimeStamp",
              "genome",
              "track",
              "chrom",
              "start",
              "end",
          ]:
            track_items = v
            break

      # Apply TF name filter if specified.
      if args.tf_filter and track_items:
        tf_filter_lower = args.tf_filter.lower()
        filtered = [
            item
            for item in track_items
            if tf_filter_lower in item.get("TFName", "").lower()
        ]
        print(
            f"  Filtered {len(track_items)} items to {len(filtered)} matching"
            f" TFName containing '{args.tf_filter}'."
        )
        track_items = filtered

      region_result["tracks"][track] = track_items

    results[coord] = region_result

  # Dump final output to specified file
  with open(args.output, "w") as f:
    json.dump(results, f, indent=2)
  print(f"Output written to {args.output}")


if __name__ == "__main__":
  main()

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Google DeepMind

Publisher

Google DeepMind (Official)

Source

google-deepmind/science-skills · skills/ucsc_conservation_and_tfbs · commit 4de6786

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Google DeepMind or Google DeepMind.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download ucsc-conservation-and-tfbs.zip