GPN-Star¶
The gpnstar source adds the published GPN-Star evolutionary-constraint scores to each single-nucleotide variant.
GPN-Star is a genomic language model trained on whole-genome alignments, and its scores measure constraint at one
evolutionary timescale, such as 447 mammals or 100 vertebrates. The source looks the scores up in a checked copy of
one score set that you build once. It runs no model.
| Kind | Annotation source; type = "gpnstar" |
| Install | altar-gpnstar, from a source checkout: pip install -e bindings/gpnstar in a clone of the repository (how) |
| Genome builds | ce11, dm6, gg6, hg38, mm39, tair10, one per copy, by score set |
| Variant classes | SNVs between A, C, G and T |
| Data | Build your own with altar-gpnstar-build |
| Validation | Not spot-checked (Validation) |
| Licence | Apache 2.0 scores; cite GPN-Star |
| Upstream | Data, Paper, Code |
When to use it¶
- Use GPN-Star to ask how strongly evolution constrains the base a variant changes, for SNVs anywhere in the genome, coding or not.
- Pick the score set for the timescale your question is about. The human score sets cover 447 mammals, 243 primates or 100 vertebrates; mouse, chicken, fly, worm and Arabidopsis have one set each (Release and identity).
- Choose phyloP 100-way for UCSC's base-wise conservation score from the 100-vertebrate alignment. It needs no build step, and its published copy is read in place. phyloP scores a position; GPN-Star scores the change to a specific alternate base.
- Choose a model, such as Cherimoya, to ask how a variant changes a measured assay in one cell type. GPN-Star's scores are neither tissue-specific nor assay-specific.
- Choose AlphaMissense for a missense pathogenicity score. Neither GPN-Star column is a probability or a clinically calibrated score.
Add it to a run¶
- Install the binding from a clone of the repository:
pip install -e bindings/gpnstar. It is not on PyPI; see Install from a source checkout. - Download one score set and build a copy with
altar-gpnstar-build(Build another release). -
Name the copy as
dataset, which is required:
altar sources gpnstar lists the columns and options. The run spec reference
describes the [sources.<name>] section, and Annotate variants with evidence walks
through a run.
Outputs¶
| Column | Type | Meaning |
|---|---|---|
gpnstar_llr_calibrated |
float | The log-likelihood ratio of the alternate against the reference allele, calibrated for mutation rate. More negative means stronger constraint or a larger predicted effect. |
gpnstar_abs_llr_calibrated |
float | A separately calibrated absolute-LLR score. Positive means a larger effect than a neutral substitution, negative a smaller one. It is not abs(gpnstar_llr_calibrated); don't recompute it from that column. |
gpnstar_score_set |
str | The score set, such as gpn-star-hg38-m447-200m. |
gpnstar_genome_build |
str | The copy's genome build. |
gpnstar_model_id |
str | The model checkpoint. |
gpnstar_model_revision |
str | The checkpoint's Hugging Face commit. |
gpnstar_alignment_id |
str | The whole-genome alignment. |
gpnstar_alignment_revision |
str | The alignment's Hugging Face commit. |
gpnstar_species_set |
str | The species in the alignment, such as 447 mammals. |
gpnstar_source_release |
str | The commit of the score release. |
gpnstar_source_asset_sha256 |
str | The SHA-256 of the published chromosome shard the score came from. |
Every column starts with gpnstar_.
The paper defines the raw LLR as log(p(alt) / p(ref)), averaged over both strands. Calibration subtracts the
mean score of neutral sites with the same central pentanucleotide and substitution. Neither column is a
probability or a clinically calibrated pathogenicity score.
A score of exactly 0.0 is a real observation. A variant with no exact (chromosome, position, ref, alt) row
has no row, so every column is empty in the export. Empty can mean an uncovered or unscorable position, a
chromosome the copy lacks, an allele or reference mismatch, or a variant class outside the source. It never means
a score of 0; see Variants a lookup may miss.
The other columns record where each score came from: the score set, its model and alignment with their commits, the release commit and the SHA-256 of the shard.
Configuration¶
| Option | Set in | Type | Default | Meaning |
|---|---|---|---|---|
dataset |
[sources.gpnstar.options] |
path | required | the copy altar-gpnstar-build wrote: its directory or its gpnstar-asset.json, as a path or URI |
genome_build |
[sources.gpnstar.options] |
text | not set | the genome build of the data, checked against it when given |
checksum_policy |
[sources.gpnstar.options] |
one of "eager", "on_first_use", "trust_manifest" |
"on_first_use" |
when to check each shard's bytes against the copy's manifest: eager checks every shard when the source opens, on_first_use a chromosome's shard before its first lookup, and trust_manifest only that each shard exists |
allow_synthetic_fixture |
[sources.gpnstar.options] |
true or false | false |
accept the binding's synthetic test copy; for tests only |
storage_options |
[sources.gpnstar.options] |
table | not set | fsspec settings for reading the files, such as credentials |
connection |
[sources.gpnstar] |
not set | connection = "<name>": the [connections.<name>] section to read the data through |
datasetis required. It names the directoryaltar-gpnstar-buildwrote, or itsgpnstar-asset.json, as a path or a URI such asgs://my-bucket/gpn-star-m447.checksum_policyison_first_useby default: each shard's bytes are checked against the copy's manifest before its chromosome's first lookup.eagerchecks every shard when the source opens.trust_manifestchecks only that each shard exists.genome_build, when given, must name the copy's build.allow_synthetic_fixtureis for tests only, and the default isfalse.storage_optionsis not allowed withconnection.connection = "<name>", set in[sources.gpnstar]itself, names the[connections.<name>]section to read through; see Pass credentials through connections.
An unknown option stops the run with an error that lists the valid ones.
Inputs¶
- Genome builds: one per copy, the build of its score set. A run on another build stops before it reads the cohort, and the error names the source.
- Variant classes: only substitutions between two different bases of A, C, G and T are scored. Indels,
multi-nucleotide variants and
Nalleles in a batch get no row, while the batch's SNVs are still looked up. - Variant IDs must be canonical Altar IDs such as
chr1:100:A:G. The source strips thechrprefix for the lookup, because the Parquet shards spell chromosomes without it. - Coverage: a position outside a shard's recorded range, or on a chromosome the copy lacks, gets no row. The source checks each variant against the manifest's chromosomes and position ranges before it queries the copy.
Where it comes from¶
The scores are the songlab/gpn-star-scores dataset
on Hugging Face. Each score set has one LLR Parquet shard per chromosome under data/<score set>/llr/. The whole
dataset is about 722 GB, so download only the score set you need. The browser BigWig tracks are rounded display
products, and the builder does not read them.
Hugging Face rate-limits downloads; see Hugging Face rate limits.
Altar publishes no copy of GPN-Star. Keep your copy on disk, or upload the built directory to your own bucket and
give its URI as dataset; see Read your own copy.
Release and identity¶
The source's identity is the org.kundajelab.altar.annotation.gpnstar contract, version 1.0.0, with the release
label <score set>@<release commit>, such as
gpn-star-hg38-m447-200m@cdaa131f2a105fae804ffdba9c67a7f128e69f70, and the copy's genome build. A run records it
in its provenance. Another score set or another release is a different identity. Where the copy is read from is
not part of it.
The binding pins one release of the songlab/gpn-star-scores dataset on Hugging Face:
- release commit
cdaa131f2a105fae804ffdba9c67a7f128e69f70; - Parquet revision
5c799b2ec6aa089f0caa8294ae72adb4510f81ae; - release manifest
manifest/release.json, SHA-2564c118ecd2deeeaa43b5a1cc6f90c510183a2feda9ba47862201437ec28f4033e.
It knows these score sets. Every revision is an immutable Hugging Face commit:
| Score set | Build | Model checkpoint | Alignment | Species |
|---|---|---|---|---|
gpn-star-hg38-v100-200m |
hg38 | songlab/gpn-star-hg38-v100-200m@0c949f13… |
songlab/multiz100way-pigz@6a9d42a3… |
100 vertebrates |
gpn-star-hg38-m447-200m |
hg38 | songlab/gpn-star-hg38-m447-200m@0d8f5164… |
songlab/hg38_cactus447way@f523f046… |
447 mammals |
gpn-star-hg38-p243-200m |
hg38 | songlab/gpn-star-hg38-p243-200m@16773016… |
primate subset of songlab/hg38_cactus447way@f523f046… |
243 primates |
mm39 |
mm39 | songlab/gpn-star-mm39-v35-85m@dac8b6b1… |
songlab/mm39_multiz35way@0e4f0417… |
35 vertebrates |
gg6 |
gg6 | songlab/gpn-star-galGal6-v77-85m@48a680f3… |
songlab/galGal6_multiz77way@68486485… |
77 vertebrates |
dm6 |
dm6 | songlab/gpn-star-dm6-i124-85m@82e9751a… |
songlab/dm6_multiz124way@e192eeeb… |
124 insects |
ce11 |
ce11 | songlab/gpn-star-ce11-n135-25m@078ad60c… |
songlab/ce11_multiz135way@1e4b77d7… |
135 nematodes |
tair10 |
tair10 | songlab/gpn-star-tair10-b18-25m@317841ed… |
songlab/tair10_multiz18way@34b56f69… |
18 Brassicaceae |
altar_gpnstar.metadata.SCORE_SETS holds the full commits. The chicken score set's assembly is gg6, while its
model and alignment use the name galGal6.
The builder writes gpnstar-asset.json next to the shards. It records the score set, the model, alignment and
release revisions, the genome build, and each shard's SHA-256, row count and position range. The source reads the
manifest and refuses:
- a manifest whose model or alignment does not match its score set;
- a
genome_buildoption that names another build than the copy's; - the synthetic test asset, unless
allow_synthetic_fixtureis set; - a shard whose bytes do not match the manifest, when the checksum policy checks it.
Build another release¶
Download the pinned release manifest and the LLR shards of one score set, check the manifest, then build:
pip install -e bindings/gpnstar
hf download songlab/gpn-star-scores \
--repo-type dataset \
--revision cdaa131f2a105fae804ffdba9c67a7f128e69f70 \
--include manifest/release.json \
--include 'data/gpn-star-hg38-m447-200m/llr/*.parquet' \
--local-dir gpn-star-release
echo '4c118ecd2deeeaa43b5a1cc6f90c510183a2feda9ba47862201437ec28f4033e gpn-star-release/manifest/release.json' \
| sha256sum --check
altar-gpnstar-build \
--asset-root gpn-star-release \
--release-manifest gpn-star-release/manifest/release.json \
--score-set gpn-star-hg38-m447-200m \
--output gpn-star-m447
hf is the Hugging Face command-line tool (pip install huggingface_hub). --release-manifest names the
upstream release; the builder accepts only the manifest with the pinned SHA-256 and the Apache-2.0 licence. Another
GPN-Star release needs a binding version that pins its manifest.
Other options:
--chromosomebuilds one chromosome; repeat it for several.--threadssets the DuckDB worker count. The default, 1, makes builds reproducible.--overwritereplaces a previous build in--outputonce the new one is complete. Without it, an existing--outputis refused. A directory that holds anything a build does not write is never deleted.
For each selected shard, the builder checks the size, SHA-256 and row count against the release manifest, the
columns, the chromosome and position range, the SNV alleles, and that no variant appears twice. It then writes one
position-sorted Parquet shard per chromosome, chrom=<chromosome>/scores.parquet, and gpnstar-asset.json. The
output is a local directory.
Compute and scale¶
- A lookup runs no model and needs no GPU.
- A lookup opens only the shards of the chromosomes its variants fall on, and reads only the row groups that hold their positions, from disk or from your bucket.
checksum_policysets when the shards are hashed:eagerhashes every shard when the source opens,on_first_usehashes a chromosome's shard before its first lookup, andtrust_manifesthashes none.- The whole upstream dataset is about 722 GB. A copy holds one score set.
- On BigQuery,
staged_annotation_sourcestages the annotations for a BigQuery store (Python and extension). The BigQuery backend is Preview.
Prioritization¶
None. The calibrated scores have no agreed cutoff, so GPN-Star adds columns but never sets prioritized. Place
GPN-Star next to model scores as separate columns. What prioritized means explains
how rules combine.
Validation¶
Validation label: Not spot-checked. The builder checks each shard's size, SHA-256 and row count against the pinned upstream release manifest, and the source checks the shards' bytes against the copy's manifest. No named variant has been looked up in a copy and in the upstream files and compared.
Not validated:
- a lookup compared with upstream GPN-Star scores for named variants;
- reading a copy through the BigQuery backend on live BigQuery, which is Preview.
Limits¶
- Only SNVs between A, C, G and T are scored. Every indel and multi-nucleotide variant has no GPN-Star columns.
- A copy holds one score set and one genome build.
- The source reads precomputed scores only. Live GPN-Star inference needs a prepared whole-genome alignment and is not part of Altar.
- Another GPN-Star release needs a binding version that pins its manifest.
- Neither score is a probability or a clinically calibrated pathogenicity score.
Cite and licence¶
Cite the GPN-Star paper, and name the score set and release you used, such as "GPN-Star gpn-star-hg38-m447-200m, songlab/gpn-star-scores@cdaa131f":
@article{ye2026gpnstar,
author = {Ye, Chengzhong and Benegas, Gonzalo and Albors, Carlos and Li, Jianan Canal and Prillo, Sebastian and
Fields, Peter D. and Clarke, Brian and Song, Yun S.},
title = {Predicting genome-wide functional constraints with {GPN-Star}},
journal = {Nature},
year = {2026},
doi = {10.1038/s41586-026-11005-5}
}
The code version archived with the paper is GPN release 0.8, on Zenodo:
@software{ye2026gpnstarcode,
author = {Ye, Chengzhong and Benegas, Gonzalo and Albors, Carlos and Li, Jianan Canal and Song, Yun S.},
title = {{GPN-Star} model source code},
publisher = {Zenodo},
year = {2026},
doi = {10.5281/zenodo.21501177}
}
- Scores: the score dataset is released under the Apache License 2.0, as its dataset card and release manifest state. The builder refuses a manifest that names another licence.
- Binding:
altar-gpnstaris MIT-licensed. It ships no GPN-Star scores.
Python and extension¶
GPNStarSource.from_options() builds the same source as a run spec, with the same options as keywords.
GPNStarSource.from_dataset() builds it over a copy:
from altar.sources import fetch_annotations
from altar_gpnstar import GPNStarSource
source = GPNStarSource.from_dataset("gpn-star-m447", checksum_policy="eager")
annotations = await fetch_annotations([source], ["chr1:1014143:C:T"])
source.close()
GPNStarSource(backend, asset=..., genome_build=..., verifier=...) reads the shards through any
AllelicRecordBackend, such as SqliteAllelicRecordBackend, with the key columns GPNSTAR_KEY_COLUMNS (chrom,
pos, ref, alt). GPNStarAssetVerifier checks the shard bytes separately from the lookup. The source checks each
variant against the manifest's chromosomes and position ranges before it queries the store. For a BigQuery store,
staged_annotation_source stages the annotations; see Run at warehouse scale on BigQuery.
The BigQuery backend is Preview: tested on the BigQuery emulator and DuckDB; not run against live BigQuery.