feat: redesign around phenotype-driven triage, not variant filtering

A table with filters made the user do the work. Rare disease triage is a different task:
which few variants could explain *this* patient's phenotype, and why. The app now answers
that, and lets a reviewer act on the answer.

Domain
- a case is a proband: a VCF plus the HPO terms observed in the patient (samples -> cases)
- HPO's gene-to-phenotype annotations are loaded as reference data (scripts/load-hpo.py)
- each candidate can be shortlisted or dismissed with a reason and a note

Ranking (app/services/triage.py, 21 tests)
- weighted sum of phenotype match, rarity, consequence severity and the model's score,
  with every component shown next to the candidate
- rarity and consequence filter; phenotype only ranks, because a real diagnosis can sit in
  a gene nobody has annotated yet and filtering on it would hide exactly that case
- ClinVar is deliberately not an input: it appears beside the result as independent
  confirmation, so nothing ranks highly merely because ClinVar already said pathogenic

UI
- the funnel is the headline: variants called -> rare -> coding candidates -> phenotype-matched
- ranked candidates with evidence chips, not a grid of everything; filters are demoted
- a variant panel showing the score breakdown, the matched HPO terms, the raw VEP record and
  links out to Ensembl/gnomAD/ClinVar, with the decision controls
- a printable case report: phenotype, funnel, shortlisted variants with reasons, provenance

API: /cases with phenotypes, /cases/{id}/candidates (funnel + ranked + weights),
/variants/{id}, /variants/{id}/decision, /cases/{id}/report, /phenotypes for the picker.
Scoring moved under the case and now answers 503 with the reason when no model registry is
reachable, instead of a 500.

Verified end to end on a simulated proband (scripts/make-demo-case.sh: real GIAB HG002
background + one real ClinVar 2-star pathogenic NF2 variant). 13 variants called -> 1 coding
candidate, and the planted variant ranks first at 0.80 on phenotype 1.00, rarity 1.00 and
consequence 1.00, with ClinVar agreeing afterwards.

Tests: api 75, ml 18, loader 16, web 27; ruff, mypy, svelte-check, terraform validate, both
kustomize overlays and the Nextflow stub run all clean.
This commit is contained in:
Kemal Yaylali
2026-09-12 08:30:44 +01:00
parent abde5ec6e4
commit 07a01715fd
47 changed files with 2159 additions and 539 deletions
+40 -13
View File
@@ -2,20 +2,47 @@ import uuid
from typing import Any
from app.db import SessionLocal
from app.models import Job, JobStatus, Sample, Variant
from app.models import Case, CasePhenotype, GenePhenotype, Job, JobStatus, Prediction, Variant
VARIANT_DEFAULTS: dict[str, Any] = {
"chrom": "22", "pos": 1, "ref": "A", "alt": "G", "gene": "NF2",
"impact": "HIGH", "consequence": "frameshift_variant", "gnomad_af": None, "annotations": {},
}
async def seed_job(
variants: list[dict[str, Any]], status: JobStatus = JobStatus.succeeded
) -> uuid.UUID:
"""Insert a sample, a job and its variants; each variant dict overrides the defaults."""
async def seed_case(
*,
phenotypes: list[tuple[str, str]] | None = None,
variants: list[dict[str, Any]] | None = None,
gene_terms: dict[str, list[tuple[str, str]]] | None = None,
status: JobStatus = JobStatus.succeeded,
name: str | None = None,
) -> tuple[uuid.UUID, uuid.UUID]:
"""Insert a case, its phenotypes, a job and its variants. Returns (case_id, job_id).
`variants` entries override VARIANT_DEFAULTS; a "score" key becomes a Prediction.
"""
async with SessionLocal() as s:
sample = Sample(name=f"s-{uuid.uuid4()}", vcf_uri="gs://b/x.vcf.gz", assembly="GRCh38")
job = Job(sample=sample, status=status)
rows = [
Variant(job=job, **{"chrom": "22", "pos": 1, "ref": "A", "alt": "G", "annotations": {}} | v)
for v in variants
]
s.add_all([sample, job, *rows])
case = Case(
name=name or f"case-{uuid.uuid4()}",
vcf_uri="gs://bucket/proband.vcf.gz",
assembly="GRCh38",
phenotypes=[CasePhenotype(hpo_id=hpo, label=label) for hpo, label in (phenotypes or [])],
)
job = Job(case=case, status=status, vep_version="113.0")
s.add_all([case, job])
for gene, terms in (gene_terms or {}).items():
s.add_all(
GenePhenotype(gene_symbol=gene, hpo_id=hpo, hpo_name=label) for hpo, label in terms
)
for spec in variants or []:
fields = VARIANT_DEFAULTS | spec
score = fields.pop("score", None)
variant = Variant(job=job, **fields)
s.add(variant)
if score is not None:
await s.flush()
s.add(Prediction(variant_id=variant.id, model_name="rarelens-pathogenicity",
model_version="demo", score=float(score)))
await s.commit()
return job.id
return case.id, job.id