Methodology
How PRSGuard works
Orchestration gathers evidence and calls tools. Deterministic code alone decides what claims are allowed. Orchestration is performed by an LLM agent when one drives PRSGuard, and otherwise by the deterministic scripted PRSGuard CLI orchestrator (as in every demo result here); both are bound by the same rules. PRSGuard starts from the trait, not from the genome: candidate scores are selected and frozen before any personal genotype is scored, and each one must then pass an evidence gate before anything is interpreted.
Architecture
Three lanes, read top to bottom. Every result page shows the same steps in its orchestration trace.
ORCHESTRATIONDETERMINISTIC DECISIONCONTEXT ONLY — never used by the applicability gate
Orchestration (LLM agent or scripted CLI)gathers evidence, calls tools, explains; never decides applicability
Deterministic sciencefixed code decides what may be claimed
CONTEXT ONLYnever used by the applicability gate
Orchestration (LLM agent or scripted CLI)step 1Receive the request, read the file locallyTrait, sex, optional declared build. The genotype never leaves the machine.
Deterministic sciencestep 2Resolve the genome buildrsID anchor positions + declaration; never assumed.genotypes.resolve_build
Orchestration (LLM agent or scripted CLI)step 3Resolve the traitFree text → ontology term and an explicit scope; narrower sub-phenotypes excluded.PGS Catalog /trait/search
Orchestration (LLM agent or scripted CLI)step 4Search the PGS CatalogCollect score, publication and evaluation metadata (snapshot or live).PGS Catalog /score/search
Deterministic sciencestep 5Router: eligibility, pre-rank, FREEZERules E1–E8 and R1–R5 pick the top k; the candidate set gets a digest.prsguard.router
CANDIDATES FROZEN — no personal genotype has been scored yet
Deterministic sciencestep 6Reference placement (once per person)PCA projection vs 1000 Genomes with bootstrap stability → RESOLVED / INTERMEDIATE / UNSTABLE / UNRESOLVED.reference.projection
Deterministic sciencestep 7Harmonise and compute raw scoresAllele, strand and build checks; scoreability r against the published score.prsguard.harmonize
Deterministic sciencestep 8Evidence audit + reference distributionCatalog consistency checks; the score distribution in the placed reference group.catalog + reference.distribution
Deterministic sciencestep 9prs-applicability-gateRules G1–G12 per candidate → SUPPORTED / RAW_ONLY / ABSTAIN and the allowed claims.skills/prs-applicability-gate
Deterministic sciencestep 10 · toolCross-PGS check, primary scoreSUPPORTED scores only; primary = highest pre-ranked SUPPORTED (fixed rule).prsguard.cross_pgs
Context onlycontextequity-scorerFST between the person's reference group and the score's cohorts; representation index.ClawBio equity-scorer
Context onlycontextequity-lit-auditorHow the papers behind each score report and sample populations (live Europe PMC + PGS Catalog).equity-lit-auditor
CONTEXT ONLY — attached to the report, never an input to the applicability gate
Orchestration (LLM agent or scripted CLI)step 10 · reportExplain the resultReport what the gate released, why, and what would change it — in plain language, without adding claims.
What orchestration (LLM agent or scripted CLI) may and may not do
Orchestration may
- Resolve the trait text to an ontology term and state the scope it used
- Search the PGS Catalog and collect score, publication and evaluation metadata
- Plan the run and call the deterministic tools in order
- Attach clearly labelled context (equity-scorer, equity-lit-auditor) to the report
- Explain in plain language what was released, the reason codes, and what would change the result
Orchestration may not
- Add, drop or reorder candidates after the freeze, or pick a different primary score
- Override, relax or re-interpret any gate rule or threshold
- Compute or show a percentile, standardized score or risk that the gate withheld
- Convert a polygenic score into absolute risk or a diagnosis
- Use literature equity or FST context as an input to any gate decision
- Describe genetic reference placement as ethnicity, race or identity
- Send genotype data anywhere other than the machine it was read on
Three outcomes per score
No percentile is released unless the evidence gate supports it. Absolute risk is never provided.
| Gate status | Raw score | Standardized score | Percentile | Absolute risk | Typical cause |
|---|---|---|---|---|---|
| SUPPORTED | released | released | released, with intervals | never | Scoreable, stably placed, and with evidence of association (95% CI above the null) in an evaluation of the person's reference group. A research reportability state: not evidence of clinically useful discrimination or calibration, and not a clinical recommendation. |
| RAW ONLY | released | withheld | withheld | never | No stable placement, or no relevant evaluation for the person's reference group. |
| ABSTAIN | withheld | withheld | withheld | never | The computable score does not represent the published one, or inputs are invalid. |
The applicability gate
prs-applicability-gate v2.2.1, calibration 2026.09.26-3. Every rule is evaluated for each candidate: ABSTAIN if any ABSTAIN rule failed, else RAW_ONLY if any RAW_ONLY rule failed, else SUPPORTED.
| Rule | Name | Question |
|---|---|---|
| G1 | INPUT_VALID | Is the gate input well-formed and unmodified? |
| G2 | SCORE_FORMAT | Is the scoring file a plain additive score on a log scale? |
| G3 | BUILD | Is the genotype file's genome build established (never assumed)? |
| G4 | ALLELES | Are located variants' alleles consistent with the scoring file? |
| G5 | SCOREABILITY | Does the computable score represent the published score (r >= r_min)? |
| G6 | SEX_SCORE | Is a sex-specific score applied to a person of that sex? |
| G7 | METADATA | Is the PGS Catalog record resolved and internally consistent? |
| G8 | PLACEMENT | Is the person placed stably inside one reference group? |
| G9 | EVALUATION | Is there evidence of association (95% CI above the null) in an evaluation of the person's group? (Association only: not clinically useful discrimination or calibration.) |
| G10 | SEX_EVALUATION | Do the informative evaluations include the person's sex? |
| G11 | REFERENCE_DISTRIBUTION | Is there a reference distribution on the matched variants? |
| G12 | REFERENCE_SENSITIVITY | Is the percentile robust to the reference population chosen? |
The router: eligibility and pre-ranking
Applied to PGS Catalog metadata only. The person's genotype is never an input.
Eligibility
- E1 trait: mapped (PGS Catalog trait_efo) to the resolved term or an in-scope child term.
- E2 phenotype: trait_reported names the whole outcome (the term's label, a Catalog synonym of an in-scope term, or the query); parenthetical qualifiers are allowed only when they are a sex qualifier, a synonym or abbreviation of the term, or a phenotype code (PheCode/ICD); subtype, age-of-onset or carrier-status scores answer a different question.
- E3 sex: sex-specific scores are excluded when the person's sex is given and differs.
- E4 score model: additive with log-scale weights and no interaction terms (what the scorer computes).
- E5 file: a PGS Catalog harmonised scoring file exists for the requested genome build (any build if unknown).
- E6 evaluated: at least one evaluation (publication, sample set) unit in the Catalog.
- E7 metadata: the Catalog record resolves and passes the consistency audit.
- E8 engineering: variants_number <= max_variants when set (the prsguard CLI sets 10,000 by default, the size the shipped 1000 Genomes reference panel supports; --max-variants 0 disables it). A runtime constraint, not a scientific criterion.
Pre-ranking
- R1 more distinct ancestry groups (single-ancestry evaluation units; NR/MAE/MAO/OTH not counted) with at least one reported performance metric - breadth of validation first;
- R2 more evaluation units with a reported performance metric;
- R3 larger total evaluation sample size (sum over units);
- R4 earlier Catalog release (longer track record); R5 PGS id. The person's genotype is never an input.
Privacy model
- This website is a static export. It loads only its own files (demo results, map geometry).
- Uploads are analysed only by a PRSGuard server running on your own machine (
prsguard serve, bound to 127.0.0.1). This website never receives genomic data. - The local server deletes the uploaded file after responding; it sends only trait text and PGS IDs to the PGS Catalog.
- No analytics, cookies or third-party scripts.