polygenic - the polygenic scores toolkit

Basic info

![Maintainer]

Downloads

• pip
• docker with data
• docker without data

Index

• Summary
• Diplotyping Algorithm
• Installation
  • With pip
  • With conda
  • With docker
• Quick start guide
• Manual
  • Tools
    • pgs-compute
    • pgs-build
    • pgs-validate
    • vcf-index
    • vcf-validate
    • vcf-stat
    • model-biobankuk
    • model-pgscat
    • model-gbe
    • model-pharmvar
  • Docker images
  • Building models
  • Example models
  • Usecases
    • pgx
• License
• Updates

Summary

Polygenic is a toolkit for a wide range of polygenic scores analysis tasks. The most important use cases include computing scores for samples in vcf files, building scores for GWAS results or fetching scores from repositories.

Diplotyping Algorithm

We begin by reading individual genetic variants (genotypes) from the patient's VCF file, where each genotype carries two alleles — one per chromosome. The system supports phasing using a custom reference panel to resolve which alleles sit on the same chromosome; when phased data is available, the algorithm preserves this linkage information, while for unphased data both chromosomes are treated symmetrically. We define haplotypes as specific combinations of co-inherited variants that form recognized gene versions, such as pharmacogenomic star alleles, where each haplotype definition distinguishes core defining variants (weighted at 1.0) from supportive sub-lineage variants (weighted at 0.05). The algorithm scores every candidate haplotype against the patient's alleles, then selects the best-matching haplotype for the first chromosome — keeping all candidates within a 2% margin of the top score. The matched alleles are then "claimed" by that haplotype, and the remaining unmatched alleles (leftovers) are passed into a second round, where up to 100 candidate haplotypes are re-scored against only those residual alleles to identify the second haplotype. Each first/second haplotype pair is ranked by combined match percentage and filtered by total missing data, producing the final diplotype call — e.g., CYP2D6 *1/*4. Every variant in the result carries a source label — direct genotyping, LD proxy, imputation flag from VCF, allele-frequency-based imputation, reference, or missing — enabling granular quality control and full traceability of the diplotype call.

Missing variant handling (reference fill + --no-ref-fallback / --no-indeterminate)

By default, variants called ./. in the input VCF are filled with homozygous reference (source: "reference") so a best-effort call and scores always compute. Pass --no-ref-fallback for strict behavior: ./. is then treated as missing (source: "missing") and subtracted from both the numerator and the denominator of the haplotype match score (the PharmCAT Named Allele Matcher approach of dropping missing positions), which can leave a sparse panel with no confident call. (There is no --ref-fallback flag — filling is the default as of 2.5.19.)

Filling alone could assert a wild-type call you can't justify, so two safeguards ride alongside it:

• Indeterminate verdict (on by default; disable with --no-indeterminate). The reference fill is recorded as source: "reference" and treated as uncovered by the verdict — i.e. it is computed on the pre-fill state. The headline call is "Indeterminate" only when ALL defining (function-level / core) variants are uncovered (missing, low-quality, or reference-filled). Otherwise the best-effort call is emitted, and which star alleles cannot be ruled in/out is reported per-allele in undeterminable (an allele is listed when any of its defining variants is uncovered and it is not contradicted by a covered slot). The best-effort call for a triggered (all-uncovered) case is kept as call_filled.

• reference_defining_variants (per-model annotation). Positions where the GRCh38 reference base itself defines an allele are never reference-filled, and when unassayed they surface in undeterminable. The canonical case is CYP2C19: rs3758581 (chr10:94842866) has reference A, but G is the global major allele and PharmVar v5 defines every "real" star allele (*1, *2, *17 …) as requiring G there, reserving CYP2C19*38 (= the empty *1.001) for the minority carrying reference A (see PharmVar GeneFocus: CYP2C19). Without the annotation, filling an unassayed rs3758581 with A would collapse every sample toward *38; the annotation keeps the real alleles callable from their own variants and flags the rs3758581-dependent alleles instead. (To author such a model, list the position under reference_defining_variants — see the guidance in CLAUDE.md.)

Match-confidence gate (--top-n)

After scoring all candidate haplotype pairs, the algorithm returns a haplotype_id when either of these holds:

• the best pair's per-chromosome max_percent_match is ≥ 50% (high-confidence call), or
• the total scored-candidate pool size is ≤ top_n (default 15) — a small, non-ambiguous candidate space is itself a confidence signal.

Otherwise haplotype_id is None (the caller refuses to guess). This is more conservative than PharmCAT, which always returns the top-scoring diplotype with deterministic tie-breaking, and roughly comparable to Aldy 4, which reports "no more than three diplotypes" when it cannot fully disambiguate. Tune --top-n higher (laxer) or lower (stricter) depending on how much ambiguity is acceptable downstream. Set --top-n 0 to rely solely on the 50% threshold.

CYP2C19*38 worked example

On a clinical panel that does not assay rs3758581, cyp2c19-pharmvar-5.1.8.yml lists it under reference_defining_variants, so it is never reference-filled. A sample's actual informative variants drive the call, and the rs3758581-dependent alleles (*38 vs *1) are reported in undeterminable rather than miscalled:

The point of the annotation: were rs3758581 blindly filled with reference A/A, it would fail the G required by *1/*2/*17 … and collapse every sample to the empty *1.001 (= *38). Because it is not filled, the real variants still call *2/*17, and the inability to tell *1 from *38 surfaces as an undeterminable entry — never a spurious confident *38.

Installation

Runtime system dependency: tabix

Beyond the pip dependencies, pgs-compute needs the tabix binary (from htslib) available on PATH at runtime. rsID-keyed models — including the diplotype models (APOE, MTHFR, COMT, F2, F5, IFNL4, OPRM1) — resolve genotypes through rsidx, which shells out to tabix; without it those lookups fail with FileNotFoundError: 'tabix'. (Positional chrom-pos-ref-alt keyed models use the bundled pytabix library and do not need the binary, but installing tabix is required for full functionality.) The input VCF must also be bgzipped and tabix-indexed (.tbi).

Install it with your package manager, e.g.:

apt-get install -y tabix          # Debian/Ubuntu (htslib)
# or: conda install -c bioconda htslib   |   brew install htslib

With pip

Install for user account

python3 -m pip install --upgrade polygenic

Install globally

sudo -H python3 -m pip install polygenic

With conda

Run conda image

docker run -it conda/miniconda3 /bin/bash

Create python3.8 environment and install polygenic

yes | conda create --name py38 python=3.8
eval "$(conda shell.bash hook)"
conda activate py38
### should be 3.8
python --version

### gcc is missing to build pytabix
apt -qq update
apt -y install build-essential tabix

pip install polygenic

With docker

Large image with all data included

docker run intelliseq:polygenictk:2.1.0 *command*

Thin image with just polygenic package installed

docker run intelliseq:polygenic:2.1.0 *command*

Quick start guide

mkdir polygenic && cd polygenic # create working directory
wget https://downloads.intelliseq.com/public/polygenic/gbe-INI78-bone-density.yml # download model
wget https://downloads.intelliseq.com/public/polygenic/illu_merged-imputed.vcf.gz # download genotypes
wget https://downloads.intelliseq.com/public/polygenic/illu_merged-imputed.vcf.gz.tbi # download position index
wget https://downloads.intelliseq.com/public/polygenic/illu_merged-imputed.vcf.gz.idx.db # download rsid index
docker run -v $(pwd):/data intelliseq/polygenic:latest --vcf /data/illu_merged-imputed.vcf.gz --model /data/gbe-INI78-bone-density.yml --output-directory /data # compute model

Manual

Tools

pgs-compute

usage: pgstk [-h] -i VCF [-m MODEL [MODEL ...]] [-p PARAMETERS] [-s SAMPLE_NAME] [-o OUTPUT_DIRECTORY] [-n OUTPUT_NAME_APPENDIX] [-l LOG_FILE] [--af AF] [--af-field AF_FIELD]
             [-v] [--print]

pgs-compute computes polygenic scores for genotyped sample in vcf format

optional arguments:
  -h, --help            show this help message and exit
  -i, --vcf VCF         vcf.gz file with genotypes
  -m, --model MODEL [MODEL ...]
                        path to .yml model (can be specified multiple times with space as separator)
  -p, --parameters PARAMETERS
                        parameters json (to be used in formula models)
  -s, --sample-name SAMPLE_NAME
                        sample name in vcf.gz to calculate
  -o, --output-directory OUTPUT_DIRECTORY
                        output directory
  -n, --output-name-appendix OUTPUT_NAME_APPENDIX
                        appendix for output file names
  -l, --log-file LOG_FILE
                        path to log file
  --af AF               vcf file containing allele freq data
  --af-field AF_FIELD   name of the INFO field to be used as allele frequency
  -v, --version         show program's version number and exit
  --print               Print output to stdout

Arguments

Required

• --vcf vcf.gz file with genotypes (tabix index should be available)
• --model path to model file

Optional

• --log_file log file
• --out_dir directory for result jsons
• --population population code
• --models_path path to a directory containing models
• --af an indexed vcf.gz file containing allele freq data
• --version prints version of package

Building models in yml

Index: Model structure Model types Parameters

Model structure

Core structure

Models have two properties which is model and description. model is a specification of computation to be performed and description is additional information to be included in the result.

model:
description:

Object keys

Each object that is not collection has a set of predefined keys (required or optional) that can be used for computation. For example: diplotype_model object has a required diplotypes key.

diplotype_model:
  diplotypes:

The computation is first delegated to key specified objects and later aggregated by the top level object itself.

Collections

There is special category of objects that don't have predefined keys but are collections. Each key within collection becomes element of collection. Collections are easy to recognize, because they are specified in plural form like diplotypes or variants. Each element of collection will be defined as singular object of collection type. For example key in variants collection will becomes objects of variant type.

      variants:
        rs7041: {diplotype: C/C}
        rs4588: {diplotype: T/T}

Variants

Variants can be identified by rsid. Variant value will be computed basing on information provided: diplotype or effect_allele. Accepted sets of fields are:

• diplotypes
  • diplotype
  • symbol
• score
  • effect_allele
  • effect_size
  • symbol

Model types

There are currently implemented four types of models:

• score_model
• diplotype_model
• haplotype_model
• formula_model The type of model can be specified at the top of yml structure or within the model field.

Specification of model type at the top of yml structure

diplotype_model:
description:

Specification of model type within the model field

model:
  diplotype_model:
description:

Parameters

External parameters can be used in formula_model through @parameters keyword.
Example parameters file in .json format:

{"sex": "F"}

Path to file can be provided as argument to polygenic tool:

--parameters /path/to/parameters.json

Example of use of parameters in the formula_model:

formula_model:
  formula:
    value: "@female.score_model.value if @parameters.sex == 'F' else @male.score_model.value"
  male:
    score_model:
      variants:
        ...
  female:
    score_model:
      variants:

Example models

Example diplotype model

This example diplotype model is based on Randolph 2014.

diplotype_model:
  diplotypes:
    1/1:
      variants:
        rs7041: {diplotype: C/C}
        rs4588: {diplotype: T/T}
    1/1s:
      variants:
        rs7041: {diplotype: C/C}
        rs4588: {diplotype: T/G}
    1/1f:
      variants:
        rs7041: {diplotype: C/A}
        rs4588: {diplotype: T/G}
    1/2:
      variants:
        rs7041: {diplotype: C/A}
        rs4588: {diplotype: T/T}
    1s/1s:
      variants:
        rs7041: {diplotype: C/C}
        rs4588: {diplotype: G/G}
    1s/1f:
      variants: 
        rs7041: {diplotype: C/A}
        rs4588: {diplotype: G/G}
    1s/2:
      variants: 
        rs7041: {diplotype: C/A}
        rs4588: {diplotype: G/T}
    1f/1f: 
      variants: 
        rs7041: {diplotype: A/A}
        rs4588: {diplotype: G/G}
    1f/2: 
      variants: 
        rs7041: {diplotype: A/A}
        rs4588: {diplotype: G/T}
    2/2: 
      variants: 
        rs7041: {diplotype: A/A}
        rs4588: {diplotype: T/T}
description:
  pmid: 24447085
  genes: [GC]
  result_diplotype_choice:
    1/1: Moderate
    1/1s: High
    1/1f: High
    1/2: Low
    1s/1s: Very high
    1s/1f: Very high
    1s/2: Moderate
    1f/1f: Very high
    1f/2: Moderate
    2/2: Very low

Example haplotype model

Haplotype model can be used for HLA and PGx.
To define haplotype models a list of alleles is required (called variants in this case, to be consistent with othe rypes of models). Each allele has associated list of defining mutations (alternative SNV alles) defined by Gnomad ID along with ref, alt and effect_allele properties. One star allele should be empty (containing only reference SNV alleles). The algorithm will utilised any phasing information in the vcf.

haplotype_model:
  variants:
    CYP2D6*1.001:
    CYP2D6*1.002:
      22-42126963-C-T: {ref: "C", alt: "T", effect_allele: "T"}
    CYP2D6*1.003:
      22-42128813-G-A: {ref: "G", alt: "A", effect_allele: "A"}
    CYP2D6*1.004:
      22-42128216-G-T: {ref: "G", alt: "T", effect_allele: "T"}
    CYP2D6*1.005:
      22-42128922-A-G: {ref: "A", alt: "G", effect_allele: "G"}
    CYP2D6*1.006:
      22-42129726-A-C: {ref: "A", alt: "C", effect_allele: "C"}
      22-42129950-A-C: {ref: "A", alt: "C", effect_allele: "C"}
      22-42130482-C-A: {ref: "C", alt: "A", effect_allele: "A"}

For copy-number star alleles (CYP2D6 *5/*1xN, CYP2C19 *36/*37) the model gains a copy_number: block and structural: haplotypes — see docs/pgx-cnv.md for the VCF contract and YAML schema.

Example score model with categories rescaling

score_model:
  variants:
    rs10012: {effect_allele: G, effect_size: 0.369215857410143}
    rs1014971: {effect_allele: T, effect_size: 0.075546961392531}
    rs10936599: {effect_allele: C, effect_size: 0.086359830674748}
    rs11892031: {effect_allele: C, effect_size: -0.552841968657781}
    rs1495741: {effect_allele: A, effect_size: 0.05307844348342}
    rs17674580: {effect_allele: C, effect_size: 0.187520720836463}
    rs2294008: {effect_allele: T, effect_size: 0.08278537031645}
    rs798766: {effect_allele: T, effect_size: 0.093421685162235}
    rs9642880: {effect_allele: G, effect_size: 0.093421685162235}
  categories:
    High risk: {from: 1.371624087, to: 2.581880425, scale_from: 2, scale_to: 3}
    Potential risk: {from: 1.169616034, to: 1.371624087, scale_from: 1, scale_to: 2}
    Average risk: {from: -0.346748358, to: 1.169616034, scale_from: 0, scale_to: 1}
    Low risk: {from: -1.657132197, to: -0.346748358, scale_from: -1, scale_to: 0}
description:
  about: 
  genes: []
  result_statement_choice:
    Average risk: Avg
    Potential risk: Pot
    High risk: Hig
    Low risk: Low
  science_behind_the_test:
  test_type: Polygenic Risk Score
  trait: Breast cancer
  trait_authors:
    - taken from the PGS catalog
  trait_copyright: Intelliseq all rights reserved
  trait_explained: None
  trait_heritability: None
  trait_pgs_id: PGS000001
  trait_pmids:
    - 25855707
  trait_snp_heritability: None
  trait_title: Breast_Cancer
  trait_version: 1.0
  what_you_can_do_choice:
    Average risk:
    High risk:
    Low risk:
  what_your_result_means_choice:
    Average risk:
    High risk:
    Low risk:

Example Formula Model

formula_model:
  formula:
    brownexp: "math.exp(@brown.score_model.value - 2.0769)"
    redexp: "math.exp(@red.score_model.value - 6.3953)"
    blackexp: "math.exp(@black.score_model.value - 2.4029)"
    sumexp: "@brownexp + @redexp + @blackexp"
    brown_prob: "@brownexp / (1 + @sumexp)"
    red_prob: "@redexp / (1 + @sumexp)"
    black_prob: "@blackexp / (1 + @sumexp)"
    blonde_prob: "1 - (@brown_prob + @red_prob + @black_prob)"
  brown:
    score_model:
      variants:
        rs796296176: {effect_allele: CA, effect_size: 1.2522}
        rs11547464: {effect_allele: A, effect_size: -0.61155}
        rs885479: {effect_allele: T, effect_size: 0.2937}
        rs1805008: {effect_allele: T, effect_size: -0.50143}
        rs1805005: {effect_allele: T, effect_size: 0.21172}
        rs1805006: {effect_allele: A, effect_size: 1.9293}
        rs1805007: {effect_allele: T, effect_size: -0.32318}
        rs1805009: {effect_allele: C, effect_size: 0.60861}
        rs1805009: {effect_allele: A, effect_size: 0.25624}
        rs2228479: {effect_allele: A, effect_size: -0.054143}
        rs1110400: {effect_allele: C, effect_size: -0.56315}
        rs28777: {effect_allele: C, effect_size: 0.52168}
        rs16891982: {effect_allele: C, effect_size: 0.75284}
        rs12821256: {effect_allele: G, effect_size: -0.34957}
        rs4959270: {effect_allele: A, effect_size: -0.19171}
        rs12203592: {effect_allele: T, effect_size: 1.6475}
        rs1042602: {effect_allele: T, effect_size: 0.16092}
        rs1800407: {effect_allele: A, effect_size: -0.19111}
        rs2402130: {effect_allele: G, effect_size: 0.35821}
        rs12913832: {effect_allele: T, effect_size: 1.214}
        rs2378249: {effect_allele: C, effect_size: 0.12669}
        rs683: {effect_allele: C, effect_size: 0.21172}
  red:
    score_model:
      variants:
        rs796296176: {effect_allele: CA, effect_size: 25.508}
        rs11547464: {effect_allele: A, effect_size: 2.5381}
        rs885479: {effect_allele: T, effect_size: -0.20889}
        rs1805008: {effect_allele: T, effect_size: 2.801}
        rs1805005: {effect_allele: T, effect_size: 0.93493}
        rs1805006: {effect_allele: A, effect_size: 3.65}
        rs1805007: {effect_allele: T, effect_size: 3.4408}
        rs1805009: {effect_allele: C, effect_size: 4.5868}
        rs1805009: {effect_allele: A, effect_size: 22.107}
        rs2228479: {effect_allele: A, effect_size: 0.62307}
        rs1110400: {effect_allele: C, effect_size: 1.4453}
        rs28777: {effect_allele: C, effect_size: 0.70401}
        rs16891982: {effect_allele: C, effect_size: -0.41869}
        rs12821256: {effect_allele: G, effect_size: -0.57964}
        rs4959270: {effect_allele: A, effect_size: 0.24861}
        rs12203592: {effect_allele: T, effect_size: 0.90233}
        rs1042602: {effect_allele: T, effect_size: 0.45003}
        rs1800407: {effect_allele: A, effect_size: -0.27606}
        rs2402130: {effect_allele: G, effect_size: 0.28313}
        rs12913832: {effect_allele: T, effect_size: -0.093776}
        rs2378249: {effect_allele: C, effect_size: 0.76634}
        rs683: {effect_allele: C, effect_size: -0.053427}
  black:
    score_model:
      variants:
        rs796296176: {effect_allele: CA, effect_size: 2.732}
        rs11547464: {effect_allele: A, effect_size: -16.969}
        rs885479: {effect_allele: T, effect_size: 0.39983}
        rs1805008: {effect_allele: T, effect_size: -0.86062}
        rs1805005: {effect_allele: T, effect_size: -0.0029013}
        rs1805006: {effect_allele: A, effect_size: -16.088}
        rs1805007: {effect_allele: T, effect_size: -1.3757}
        rs1805009: {effect_allele: C, effect_size: 0.060631}
        rs1805009: {effect_allele: A, effect_size: 3.9824}
        rs2228479: {effect_allele: A, effect_size: 0.17012}
        rs1110400: {effect_allele: C, effect_size: 0.29143}
        rs28777: {effect_allele: C, effect_size: 0.82228}
        rs16891982: {effect_allele: C, effect_size: 1.1617}
        rs12821256: {effect_allele: G, effect_size: -0.89824}
        rs4959270: {effect_allele: A, effect_size: -0.36359}
        rs12203592: {effect_allele: T, effect_size: 1.997}
        rs1042602: {effect_allele: T, effect_size: 0.065432}
        rs1800407: {effect_allele: A, effect_size: -0.49601}
        rs2402130: {effect_allele: G, effect_size: 0.26536}
        rs12913832: {effect_allele: T, effect_size: 1.9391}
        rs2378249: {effect_allele: C, effect_size: -0.089509}
        rs683: {effect_allele: C, effect_size: 0.15796}
description:
  name: HirisPlex

Description

Model keys glossary

• model - generic model that can aggregate results of other model types
• diplotype_model Required keys:
  • diplotypes
• description - all properties to be included in the final results

Usecases

PGX

python3 -m pip install polygenic
pgstk pgs-compute --vcf [PATH_TO_VCF_GZ] --model cyp2d6-pharmvar.yml --print | jq .haplotype_model.haplotypes.match

License

Proprietary (contact@intelliseq.pl)

Updates

2.5.36

The packaged models now cover the whole PGx report (33 -> 40 models). Seven genes existed only in the deployed model streams, so anything switching a pipeline to package-provided models would have silently dropped them from every report.

• Added NAT2 (nat2-pharmvar-6.2.25.yml, 129 sub-alleles / 59 core). The version was established by checksum: the deployed models-pharmvar/06.2026 export IS PharmVar 6.2.25 - its CYP2A6 differs from ours only in indel left-alignment.
• Added ABCG2, CACNA1S, CFTR, G6PD, RYR1, UGT1A1 (*-pharmgkb-1.0.0.yml), vendored from the deployed PharmGKB-derived set; each header records the source path and the sha256 of the unchanged body. These are not star-allele models: G6PD names alleles as variant combinations and is X-linked, CFTR by ivacaftor responsiveness class, RYR1 has 340 single-variant alleles, and UGT1A1 carries the (TA)n promoter repeat (*28/*36/*37).
• All their indels (CFTR 1, G6PD 10, RYR1 4, UGT1A1 3) were checked against GRCh38 with bcftools norm and were already left-aligned, so nothing was rewritten.
• Every added model was validated against real output: NAT2 matches the Paragon review sheet on 4/5 samples (the fifth is PharmVar vs legacy naming, *5/*16 vs *5/*5), and the six others reproduce the production s11-star_alleles.json exactly.
• Manifest fix: a model added by copying an existing file is now dated at the copy. git reported NAT2 as a copy (C096) of a file vendored elsewhere a day earlier, and the manifest dated the model before it existed in the package. A copy is not a move - the source still exists.

2.5.35

Every result now states its gene (BT-2323). description.gene carries the canonical symbol, so consumers never have to derive it from the model file name.

• The file stem equalled the gene only because models were deployed renamed to GENE.yml. Packaged models keep {gene}-{source}-{version}.yml, so anything parsing the name broke - the pgx pipeline's gene key became CYP2D6-PHARMVAR-5.1.8 instead of CYP2D6.
• Precedence: a model's own description.gene (curatorial) wins, then the shipped manifest, then the file name - and only when the name really looks like a model (CYP2D6.yml or the {gene}-{source}-{version} grammar). An arbitrary name yields no gene field rather than an invented one, so the field can be trusted when present.
• MT-RNR1 now declares its symbol in the model: the file-name convention cannot carry the hyphen (mtrnr1-cpic-1.0.0.yml would give MTRNR1). pgstk model-list and the manifest honour a declared gene too.

2.5.34

pip install polygenic-pgx no longer needs a C compiler. pytabix publishes no wheels, so pip compiled it from source and the install failed with command 'gcc' failed on any machine without a toolchain - including python:3.8-slim. That mattered more since 2.5.33, which tells people to pip install and expect working models.

• VcfAccessor now queries the tabix index through pysam (already a declared dependency, ships manylinux wheels) instead of pytabix; pytabix is dropped from install_requires.
• No behavioural change: the same records come back for point and region queries, the chr-prefix retry still works, and an absent contig still yields no records rather than an error. The two call sites now share one query_lines() helper instead of duplicating the retry.
• Verified by installing the wheel in python:3.8-slim with gcc absent, and by the full test suite (162 tests) against the real fixtures.

2.5.33

The PGx models now ship inside the package. pip install polygenic-pgx installs the 33 PGx star-allele models alongside the engine, so there is a single source of truth instead of the engine and its models arriving by separate routes (which is how a stale-model image produced wrong calls in a customer validation). Full guide: docs/models.md.

• -m accepts a built-in name or a path: pgs-compute -m cyp2d6 as well as -m /path/to/cyp2d6.yml. An explicit path always wins; names never prefix-match; a gene with two models from different sources raises rather than guessing. Results record both model_name (what ran) and model_requested (what was asked for).
• New pgstk model-list: every model with its version, creation/update dates, checksum and origin. -m X --path-only for scripting, --json, --gene/--source filters, --verify (checksums vs the manifest), --models-dir.
• New pgstk model-manifest regenerates the committed manifest.json from git history. Creation dates survive both traps: a rebuild that renames a file is dated at the rebuild, while relocating the models wholesale does not reset them. Dates are never inferred from filesystem timestamps, and a model whose bytes drift from the manifest reports unknown rather than a stale date.
• POLYGENIC_MODELS_DIR is now honoured by the engine (previously shell-only) and searched before the built-ins, so a pipeline can override part or all of the set.
• Packaging: models moved to polygenic/models/pgx/; the shipped directory is data-pure and the release gate asserts that notes/scripts are absent from the wheel. build.sh now uses the same PEP 517 build as the gate, with an upload glob that matches the actual artifact names.

Older releases: see CHANGELOG.md in the repository (it ships in the sdist).