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¶
- Install the binding:
pip install altar-conservation. - 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 + 1topos + len(ref) - 1, leaving out the padding base; - the two bases an insertion falls between,
posandpos + 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 needspip install "altar[hf]"(Where it comes from).datasetnames your own copy, as a path or a URI: onealtar pullmade, or one you built.indelsisskip, the default, which scores SNVs only, ormax, which scores every variant (Outputs).maxchanges the identity (Release and identity).namerenames the source.genome_build, when given, must behg38.storage_optionsis not allowed withconnection.connection = "<name>", set in[sources.phylop100way]itself, names the[connections.<name>]section to read through.prioritize_predicateis 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_buildif 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:
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.parquetin 128,000-row groups, with the track, release and genome build in every file's metadata; - writes only into an empty or absent
--output.--overwritereplaces 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
gcsor 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
tableis 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-conservationis 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.