This is an experimental retraining of the alignment-conditioned GPN-Star M447 25M model, using a broader set of conserved training windows. It is not a single-sequence distilled model and does not replace the original published M447 25M checkpoint. Inference requires the original hg38 M447 alignment and species ordering.
The released fp32 weights are the 145,000-step chromosome-21 validation-best checkpoint from a run trained for 150,000 steps. Checkpoint selection did not use variant-effect benchmark labels. The final 150k checkpoint is not included. The model-specific neutral mutation-rate calibration table is included.
Use a fresh Python 3.10 or 3.11 environment. The bundled legacy_gpn/ files are
the unchanged implementation used for this run; do not mix them in one process
with the newer refactored gpn package. The portable loader resolves the bundled
phylogenetic metadata relative to the model directory, not the working directory.
# Run this download command with an installed Hugging Face CLI.
hf download songlab/gpn-star-hg38-m447-25m-top20 --local-dir gpn-star-m447-top20
cd gpn-star-m447-top20
sha256sum -c SHA256SUMS
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Eight saved, tokenized examples; no whole-genome alignment download required.
.venv/bin/python top20.py --self-test
For reproducibility, pin the Hub revision to the release tag v1.0.0 or its
commit SHA rather than downloading an unspecified future revision.
Provide a tab-separated file with chrom, pos, ref, and alt columns.
Coordinates are 1-based hg38/GRCh38; alleles are on the reference-genome
forward strand. Chromosomes may include or omit chr in the input file; the
alignment stores must use the original chromosome keys without that prefix.
.venv/bin/python top20.py \
--input variants.tsv --output scores.tsv \
--msa /path/to/243/all.zarr /path/to/204/all.zarr \
--device cuda --precision fp16 --batch-size 8
These two stores must be in the original 243-then-204 column order, with human as column 0. A combined 447-column store in that same order is also accepted. Arbitrarily substituting another 447-species alignment is not valid. The alignment itself is not bundled. See the GPN resources for the original data. The wrapper checks REF alleles, shapes, and missing alignment chunks, and fails rather than silently substituting missing alignment data. It currently requires a full 256-bp reference window and an A/C/G/T central pentanucleotide.
On CPU, use --device cpu --precision fp32 and a small batch size. Stored
parameters remain fp32 in both modes; fp16 refers only to CUDA autocast.
The original benchmark inference used compiled FP16 forwards. This helper uses
eager inference; small device/precision-dependent numerical differences are
possible. Verification details are recorded in release_manifest.json.
From the downloaded release directory:
from top20 import load_model
model = load_model(device="cuda")
# model is GPNStarForMaskedLM, in eval mode with fp32 parameters.
# Its forward inputs are input_ids, source_ids and target_species, not raw DNA.
# Use tokenize_variants/predict_logits or the CLI for the validated SNV path.
The model is not frozen: load_model preserves gradient-enabled parameters.
This release validates SNV inference, not a fine-tuning recipe or an indel scorer.
Direct AutoModelForMaskedLM.from_pretrained without registering the matching
implementation and resolving phylo_dist_path is not the supported quick start.
No trust_remote_code=True is required by the supplied loader.
For each SNV, the model sees a 256-bp MSA window. The target human nucleotide is masked in both the target sequence and alignment source. Forward and reverse complement predictions are mapped into A/C/G/T order and their logits averaged. Forward/reverse target indices are 128/127. No distillation temperature is applied.
The output columns are:
llr_raw = log P(ALT | context, MSA) - log P(REF | context, MSA).llr_calibrated = llr_raw - neutral_mean(pentanucleotide, ALT).impact_raw and impact_calibrated: the negatives of the corresponding LLRs;
higher values indicate stronger predicted loss of evolutionary compatibility.abs_llr_calibrated: magnitude of the calibrated allele effect, which does not
distinguish increases from decreases in compatibility.Calibration has 3,072 directed central-five-mer/ALT classes and was fitted specifically for these weights using all 6,578,091 original hg38 neutral sites, without benchmark labels. Do not substitute the published top-5% model's table, or apply this table twice. Calibration is postprocessing, not another trained model. It does not improve every task or every score convention.
| Property | Value |
|---|---|
| Architecture | Original GPN-Star small; 25,869,671 parameters |
| Transformer | 8 layers, 8 attention heads, hidden width 512, intermediate width 2,048 |
| Alignment/context | Original M447 ordering; 256-bp windows, candidate stride 128 |
| Region selection | Top 20% of nonmissing window conservation scores + 0.1% random remainder |
| Window conservation score | 75th percentile of phastCons470way within the window |
| Training chromosomes | 1–20, X, Y |
| Validation/test chromosomes | Original top-5% chr21/chr22 sets, unchanged |
| Training pool | 3,732,978 unique windows; 7,465,956 forward/RC examples |
| Optimization | 150,000 steps; global batch 256; AdamW; LR 1e-4; 2,500-step warmup then cosine to zero |
| Seed | 42; fresh random initialization |
| Released checkpoint | Minimum chr21 validation loss, step 145,000; loss 0.07878149067416074 |
The top-20% cutoff is tie-inclusive and changes the sampling pool, not the number of training updates. Original FIRE-1 evolutionary-distance encoding, clade threshold 0.05, masking objective, auxiliary features, conservation-based loss weights, repeat weight 0.1, and neutral-label augmentation 0.1 are retained. The run used four A100s with gradient accumulation to preserve the original global batch. Recovery restored training state, but stochastic dataloader-worker transforms are not guaranteed to replay bitwise after preemption.
These are pooled AUPRC point estimates for this released checkpoint on the five
GPN-Star/Program A SNV datasets. For OMIM, ClinVar and COSMIC the score is signed
REF-minus-ALT; the two UKB rows use absolute LLR, with absolute value taken
after calibration. Counts and AUROC, as well as signed UKB sensitivities,
are included in evaluation_metrics.csv.
| Dataset | Raw AUPRC | Calibrated AUPRC |
|---|---|---|
| OMIM regulatory (TraitGym Mendelian) | 0.746579 | 0.761973 |
| UKB noncoding (TraitGym Complex) | 0.240967 | 0.143668 |
| ClinVar missense | 0.856383 | 0.862038 |
| COSMIC missense | 0.315342 | 0.393311 |
| UKB fine-mapped coding | 0.253135 | 0.222491 |
For clarity, calibrated signed UKB noncoding/coding AUPRC is 0.238804/0.275994; these are separately labeled sensitivities, not silently substituted for the absolute-score rows. This is one fitted training seed; the broader sampling pool is not claimed to improve universally over the original model. These research predictions are not clinically validated.
model.safetensors: original fp32 weights, byte-for-byte unchanged (103,510,204 bytes).config.json and phylo_info/: portable configuration and two small distance arrays.calibration.parquet: this checkpoint's neutral calibration means and counts.top20.py, legacy_gpn/, requirements.txt: matching inference implementation.examples/: eight label-free-selected test variants, tokenized MSA inputs, and expected scores.tests/, release_manifest.json, SHA256SUMS: software tests, provenance and checksums.No optimizer state, whole-genome MSA, training datasets, credentials, or
unrelated experimental models are included. This model was trained with the
GPN source at commit b28eaeda4740087ea747c9354fa2108161abb1ac; the small bundled
source subset is hash-checked against the frozen training/evaluation copy.
Weights and bundled software are released under the MIT license, matching the original model and GPN repository. Please cite Ye et al., "Predicting genome-wide functional constraints with GPN-Star," Nature (2026), doi:10.1038/s41586-026-11005-5, and identify this as the top-20% retraining, validation-best step 145k rather than the original published checkpoint.
model.safetensors 104 MBexamples/tokenized_inputs.npz 124.9 kB