Skip to content

phyloP 100-way conservation

The phylop100way source adds UCSC's hg38 phyloP 100-way score at each variant's base: how much more slowly or quickly that base has evolved than neutral across 100 vertebrates. It is a lookup in a released track and runs no model.

Kind Annotation source; type = "phylop100way"
Install pip install altar-conservation (PyPI)
Genome builds hg38
Variant classes SNVs; every class with indels = "max". Bases on chr1–22, X, Y and M
Data Published: release 2015-05 on hg38, read in place. gcs (default): gs://kundajelab-altar/conservation/phylop100way-hg38; hf: hf://datasets/altar-genomics/phylop100way-hg38. Copy it with altar pull phylop100way --to PATH_OR_URI. Build your own with altar-conservation-build
Validation Matches upstream on spot checks (Validation)
Licence Free for public use; cite UCSC
Upstream Data, Paper, Documentation

When to use it

  • Use phyloP to ask whether a variant falls on a base that evolution has conserved, or accelerated, across 100 vertebrates. The score covers coding and non-coding bases alike.
  • It scores SNVs by default. Set indels = "max" to score every variant by the most conserved base it touches (Outputs).
  • Choose GPN-Star for constraint scores from a genomic language model trained on whole-genome alignments, or for a genome other than hg38.
  • Choose gnomAD to ask how common a variant is among people. phyloP measures constraint across species, not within humans.
  • Choose a model, such as Cherimoya, or a precomputed prediction, such as AlphaMissense or SpliceAI, to predict what a change does. A conserved base says the position matters, not how this allele changes it.

Add it to a run

[sources.phylop100way]
type = "phylop100way"
  1. Install the binding: pip install altar-conservation.
  2. Add the section above to the run spec. It reads the published copy in place, with no download and no credentials.

altar sources phylop100way lists the column, the options and the published copy. The run spec reference describes the [sources.<name>] section, and Annotate variants with evidence walks through a run. Tutorial 0: look up what is known about five variants looks five variants up in phyloP in a notebook.

Outputs

Column Type Meaning
phylop100way float The phyloP score: a signed -log10 p-value, from about -20 to 10. Positive where the base evolves more slowly than neutral (conserved), negative where it evolves faster (accelerated).

By default only SNVs are scored, by the score at their base. With indels = "max", every variant is scored by the greatest score over the bases it touches, as VEP takes them:

  • a deletion's deleted bases, pos + 1 to pos + len(ref) - 1, leaving out the padding base;
  • the two bases an insertion falls between, pos and pos + 1;
  • any other change's REF span.

The spans assume Altar's normalized variant IDs. SNVs score the same in both modes. Unscored bases are ignored. A variant with no scored base gets no column, and so does a variant the default mode skips.

An augmented VCF written from a run's export carries the score as the ALTAR1_PHYLOP100WAY INFO field; see Write an augmented VCF.

Configuration

Option Set in Type Default Meaning
dataset [sources.phylop100way.options] path not set your own copy, as a path or URI, such as one altar pull made (default: the published copy)
location [sources.phylop100way.options] one of "gcs", "hf" "gcs" where to read the published copy from
storage_options [sources.phylop100way.options] table not set fsspec settings for reading the files, such as credentials
connection [sources.phylop100way] not set connection = "<name>": the [connections.<name>] section to read the data through
indels [sources.phylop100way.options] one of "skip", "max" "skip" skip scores SNVs only; max scores every variant by the greatest score over the bases it touches
genome_build [sources.phylop100way.options] text not set the genome build of the data, checked against it when given
name [sources.phylop100way.options] text not set the source's name in a run's provenance and prioritized_source_names (default: the track's name)
prioritize_predicate Only in code not set a rule over the score that sets prioritized, given only in code

Every option is optional. With none, the source reads the published copy from gcs and scores SNVs.

  • location = "hf" reads the Hugging Face mirror, which needs pip install "altar[hf]" (Where it comes from).
  • dataset names your own copy, as a path or a URI: one altar pull made, or one you built.
  • indels is skip, the default, which scores SNVs only, or max, which scores every variant (Outputs). max changes the identity (Release and identity).
  • name renames the source.
  • genome_build, when given, must be hg38.
  • storage_options is not allowed with connection.
  • connection = "<name>", set in [sources.phylop100way] itself, names the [connections.<name>] section to read through.
  • prioritize_predicate is given only in code (Prioritization).

The source reads no BigQuery table. table stops the run with an error that says to pull the dataset and name it with dataset (Compute and scale). An unknown option stops the run with an error that lists the valid ones.

This reads your own copy and scores indels too:

[sources.phylop100way]
type = "phylop100way"
options = { dataset = "/data/phylop100way-hg38", indels = "max" }

Inputs

  • Genome builds: hg38 only. A run on another build, such as an hg19 or mouse cohort, stops before it reads the cohort, and the error names the source. Remove the source, or correct genome_build if the cohort is hg38.
  • Variant classes: SNVs by default; every class with indels = "max".
  • Contigs: chr1–22, X, Y and M. A variant on an alternate, unlocalized or unplaced contig gets no value.
  • Allele matching: the lookup reads positions, not alleles. The indel spans under Outputs assume Altar's normalized variant IDs; see Variant identity and normalization.

Where it comes from

The Kundaje lab builds the track with altar-conservation-build and publishes it in a public-read bucket, with a byte-for-byte mirror on Hugging Face (dataset card). The card above lists both locations. It holds one row per scored base of chr1–22, X, Y and M: 2,837,915,604 rows in 25 files, 5.0 GB, partitioned by contig, with a 1-based pos and a float32 score. altar-conservation depends on altar[gcs], so the default location needs no other install.

location = "hf" reads the mirror, which needs pip install "altar[hf]". Hugging Face limits anonymous requests, so a large cohort read from hf can stall; see Hugging Face rate limits.

To keep your own copy:

altar pull phylop100way --to /data/phylop100way-hg38

It copies the files and checks that every file records the release. Name the copy with dataset. Choose where data is read from covers the published copy, your own copy, altar pull and connections for every source.

Release and identity

UCSC publishes one phyloP 100-way track for hg38, hg38.phyloP100way.bw, dated May 2015, and does not release new versions of it. Its release label is 2015-05.

The source's identity is the contract org.kundajelab.altar.annotation.phylop100way (version 1.0.0), the release and hg38. indels = "max" scores variants the default leaves out, so its release is 2015-05+indels-max. The published copy, a pulled copy and a copy you build declare the same identity. Where the data is read from is not part of it.

Build another release

The builder has no release option: UCSC publishes one version of the track, and the builder checks the file against it. Rebuild the copy from the upstream bigWig:

pip install "altar-conservation[build]"
curl -O https://hgdownload.soe.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw
altar-conservation-build --track phylop100way --input hg38.phyloP100way.bw --output /scratch/phylop100way-hg38

The build extra installs pybigtools, which has wheels for Linux and macOS. The builder:

  • checks the file's MD5 against UCSC's, 43858006bdf98145b6fd239490bd0478;
  • converts each primary contig in its own process (--workers, by default one per contig up to the CPU count), and skips other contigs;
  • turns UCSC's 0-based intervals into one row per base with a 1-based pos, and checks that positions strictly increase;
  • writes chr=<contig>/scores.parquet in 128,000-row groups, with the track, release and genome build in every file's metadata;
  • writes only into an empty or absent --output. --overwrite replaces a previous build there.

--output is a local directory; copy it to a bucket yourself.

Compute and scale

  • A lookup runs no model and needs no GPU.
  • The published copy is 2,837,915,604 rows in 25 files, 5.0 GB. A lookup reads one row group per block of positions it needs, not the whole track.
  • Hugging Face limits anonymous requests, so read a large cohort from gcs or from your own copy.
  • The source reads Parquet only. A BigQuery table of 2.8 billion rows would be scanned once per chunk of variants, so table is refused.
  • On a 64-core server the build took 72 s and about 14 GB of memory across 25 processes.

Prioritization

None from a run spec. Built in code, PhyloP100wayAnnotationSource.from_options(prioritize_predicate=...) gates prioritized on a rule you give, such as Ge(Col("phylop100way"), Lit(2.0)). What prioritized means explains how rules combine.

Validation

Validation label: Matches upstream on spot checks. When the published copy was built, its rows per contig were compared with the scored bases of UCSC's bigWig. Scores looked up in the published copy for a set of SNVs and indels agreed with the bigWig, including the bases each indel spans.

Not validated:

  • the value at every base: the check compared row counts per contig and a set of variants' scores.

Limits

  • hg38 only. A run on another build stops before it reads the cohort, and the error names the source.
  • A variant on an alternate, unlocalized or unplaced contig gets no value. The build keeps chr1–22, X, Y and M.
  • A base UCSC did not score gets no value.
  • By default an indel gets no value. Set indels = "max" to score it.
  • When Python code assembles results across several assemblies, the source is joined to hg38 variants only. On another assembly it is dropped with an AnnotationUnavailableWarning.

Cite and licence

Cite the phyloP and phastCons papers, which UCSC's phyloP 100-way README cites:

@article{pollard2010phylop,
  author = {Pollard, Katherine S. and Hubisz, Melissa J. and Rosenbloom, Kate R. and Siepel, Adam},
  title = {Detection of nonneutral substitution rates on mammalian phylogenies},
  journal = {Genome Research},
  volume = {20},
  number = {1},
  pages = {110--121},
  year = {2010},
  doi = {10.1101/gr.097857.109}
}

@article{siepel2005phastcons,
  author = {Siepel, Adam and Bejerano, Gill and Pedersen, Jakob S. and Hinrichs, Angie S. and Hou, Minmei and
    Rosenbloom, Kate and Clawson, Hiram and Spieth, John and Hillier, Ladeana W. and Richards, Stephen and
    Weinstock, George M. and Wilson, Richard K. and Gibbs, Richard A. and Kent, W. James and Miller, Webb and
    Haussler, David},
  title = {Evolutionarily conserved elements in vertebrate, insect, worm, and yeast genomes},
  journal = {Genome Research},
  volume = {15},
  number = {8},
  pages = {1034--1050},
  year = {2005},
  doi = {10.1101/gr.3715005}
}

UCSC asks you to credit the data and cite the Genome Browser's latest database paper (citing UCSC):

@article{casper2026ucsc,
  author = {Casper, Jonathan and Speir, Matthew L. and Raney, Brian J. and Perez, Gerardo and Nassar, Luis R. and
    Lee, Christopher M. and Hinrichs, Angie S. and Gonzalez, Jairo Navarro and Fischer, Clay and
    Diekhans, Mark and Clawson, Hiram and Benet-Pages, Anna and Barber, Galt P. and Vaske, Charles J. and
    van Baren, Marijke J. and Wang, Karen and Rodriguez, Yesenia Joanna Puga and Jenkins-Kiefer, Jaidan Ashlyn
    and Chalamala, Megna and Haussler, David and Kent, William James and Haeussler, Maximilian},
  title = {The {UCSC} Genome Browser database: 2026 update},
  journal = {Nucleic Acids Research},
  volume = {54},
  number = {D1},
  pages = {D1331--D1335},
  year = {2026},
  doi = {10.1093/nar/gkaf1250}
}
  • Data: UCSC's phyloP files are freely available for public use.
  • Binding: altar-conservation is MIT-licensed. It ships no data.

Python and extension

PhyloP100wayAnnotationSource.from_options() builds the same source as a run spec, with the same options as keywords, and also takes prioritize_predicate. Look up evidence shows a lookup from Python.

The source reads Parquet only, so a BigQuery store cannot read it in its own SQL. Run at warehouse scale on BigQuery covers sources at warehouse scale. Another track, such as phastCons, is added as described in Add a conservation track.