Compute PRS
compute_prsCalculate a polygenic risk score for one genome against a PGS model from a raw VCF, with options to infer genetic ancestry or embed published performance metrics on the result.
Instructions
Compute a polygenic risk score for one genome against one PGS model.
Pass the raw VCF directly; a separate normalize_vcf call is not needed.
If this VCF has a fresh normalized cache, it is reused automatically;
genotypes_path is the explicit Parquet fast path. For a trait panel —
one genome or several — use
compute_prs_by_trait(samples=[...]), then
compare_genomes / build_prs_prompt / plot_trait_panel.
Reference restoration (F15/F22). reference_restoration fills a scoring
variant's missing reference allele from the precomputed reference-allele
universe (pulled from HuggingFace on first use) so a locus the sample is
confidently hom-ref at scores as dose-0 instead of being dropped as
unscorable-absent — recovering the ~50% coverage gap on genome-wide WGS
scores. Default "auto" detects the input: whole-universe restoration for
WGS, the matching chip scope for a genotyping array, off otherwise. Pass
"off", "wgs", or a chip id (e.g. "gsa_v3") to force a scope. The
result's variants_ref_resolved_panel / variants_ref_resolved_fasta
counters show how many loci were recovered.
Set infer_ancestry=True to also infer and attach the sample's genetic
ancestry (sample_ancestry). genotype_input_mode ("auto" /
"variant_only" / "all_sites") controls how absent loci are read.
Set attach_performance=True to embed the score's best published
performance (effect sizes, AUROC/C-index, evaluation ancestry) on the
result in the same call. The result also carries detected_genome_build /
build_mismatch from the VCF (F4).
Recommended follow-up: percentile then absolute_risk (disease
traits), or build_prs_prompt(kind='score') for a reusable LLM write-up.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pgs_id | Yes | ||
| vcf_path | Yes | ||
| genome_build | No | ||
| genotypes_path | No | ||
| infer_ancestry | No | ||
| attach_performance | No | ||
| genotype_input_mode | No | auto | |
| reference_restoration | No | auto |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| score | Yes | Computed polygenic risk score | |
| pgs_id | Yes | PGS Catalog Score ID | |
| z_score | No | Standardized score (score - reference_mean) / reference_std, set when a percentile was computed | |
| ancestry | No | Ancestry superpopulation used for percentile (AFR, AMR, EAS, EUR, SAS) | |
| match_rate | Yes | Fraction of scoring variants matched (0-1) | |
| percentile | No | Estimated population percentile (0-100) from theoretical distribution | |
| performance | No | Best available performance metric from PGS Catalog | |
| absolute_risk | No | Absolute disease risk estimate based on PRS z-score and prevalence data | |
| reference_std | No | Reference/theoretical distribution std used for the percentile and z-score | |
| build_mismatch | No | True when the detected VCF build differs from the genome_build used for scoring | |
| reference_mean | No | Reference/theoretical distribution mean used for the percentile and z-score | |
| trait_reported | No | Reported trait for the score | |
| variants_total | Yes | Total number of variants in scoring file | |
| sample_ancestry | No | Inferred genetic ancestry of the sample (super-pop + confidence, fine population, informational mixture); populated when ancestry inference is requested | |
| theoretical_std | No | Theoretical population SD of PRS: sqrt(sum(w_i^2 * 2 * p_i * (1-p_i))) | |
| theoretical_mean | No | Theoretical population mean PRS computed from allele frequencies: sum(w_i * 2 * p_i) | |
| variants_matched | Yes | Number of scoring variants matched in VCF | |
| variants_no_call | No | Scoring loci present in the genotype input but carrying a missing/no-call GT | |
| percentile_method | No | Method used to compute percentile: 'reference_panel', 'theoretical', or 'auroc_approx' | |
| variants_observed | No | Scoring loci present in the genotype input with a genotype row | |
| weight_mass_total | No | Sum of |effect_weight| over all scoring variants (per-dosage formats use max|dosage_k_weight|) | |
| genotype_input_mode | No | How absent genotype loci were interpreted during scoring | plink_present_only |
| variants_maf_filled | No | Absent loci filled with population MAF dosage (2 * allelefrequency_effect) instead of being unscorable | |
| weight_mass_matched | No | Sum of |effect_weight| over matched scoring variants (per-dosage formats use max|dosage_k_weight|) | |
| weight_mass_coverage | No | C_wt: weight_mass_matched / weight_mass_total — fraction of total effect-weight mass carried by matched variants | |
| detected_genome_build | No | Genome build inferred from the VCF header/contigs (None if undetectable or genotypes were pre-normalized) | |
| has_allele_frequencies | No | Whether the scoring file contained allelefrequency_effect data | |
| variants_assumed_hom_ref | No | Absent loci treated as homozygous-reference under variant-only VCF semantics | |
| variants_unscorable_absent | No | Absent loci that could not be scored because the reference allele was unknown | |
| variants_ref_resolved_fasta | No | Absent loci whose missing reference allele was resolved from the reference FASTA faidx (subset of variants_assumed_hom_ref) | |
| variants_ref_resolved_panel | No | Absent loci whose missing reference allele was resolved from the reference panel .pvar (subset of variants_assumed_hom_ref) |