Skip to content

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

[sources.gpnstar]
type = "gpnstar"
  1. 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.
  2. Download one score set and build a copy with altar-gpnstar-build (Build another release).
  3. Name the copy as dataset, which is required:

    [sources.gpnstar]
    type = "gpnstar"
    
    [sources.gpnstar.options]
    dataset = "gpn-star-m447"
    

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
  • dataset is required. It names the directory altar-gpnstar-build wrote, or its gpnstar-asset.json, as a path or a URI such as gs://my-bucket/gpn-star-m447.
  • checksum_policy is on_first_use by default: each shard's bytes are checked against the copy's manifest before its chromosome's first lookup. eager checks every shard when the source opens. trust_manifest checks only that each shard exists.
  • genome_build, when given, must name the copy's build.
  • allow_synthetic_fixture is for tests only, and the default is false.
  • storage_options is not allowed with connection.
  • 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 N alleles 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 the chr prefix 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-256 4c118ecd2deeeaa43b5a1cc6f90c510183a2feda9ba47862201437ec28f4033e.

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_build option that names another build than the copy's;
  • the synthetic test asset, unless allow_synthetic_fixture is 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:

  • --chromosome builds one chromosome; repeat it for several.
  • --threads sets the DuckDB worker count. The default, 1, makes builds reproducible.
  • --overwrite replaces a previous build in --output once the new one is complete. Without it, an existing --output is 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_policy sets when the shards are hashed: eager hashes every shard when the source opens, on_first_use hashes a chromosome's shard before its first lookup, and trust_manifest hashes none.
  • The whole upstream dataset is about 722 GB. A copy holds one score set.
  • On BigQuery, staged_annotation_source stages 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-gpnstar is 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.