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
@@ -0,0 +1,73 @@
"""cases, phenotypes and triage decisions
Samples become cases (a proband: a VCF plus observed phenotype terms), and triage gains the two
things it needs: HPO annotations to rank against, and somewhere to record the reviewer's calls.
Revision ID: 9a1c2d3e4f50
Revises: 5f2c8e1b9d04
Create Date: 2026-09-12 09:00:00.000000
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = '9a1c2d3e4f50'
down_revision: str | None = '5f2c8e1b9d04'
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
op.rename_table('samples', 'cases')
op.alter_column('jobs', 'sample_id', new_column_name='case_id')
op.create_table(
'case_phenotypes',
sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
sa.Column('case_id', sa.UUID(), nullable=False),
sa.Column('hpo_id', sa.String(length=20), nullable=False),
sa.Column('label', sa.String(length=200), nullable=False),
sa.ForeignKeyConstraint(['case_id'], ['cases.id'], ondelete='CASCADE'),
sa.PrimaryKeyConstraint('id'),
sa.UniqueConstraint('case_id', 'hpo_id', name='uq_case_phenotypes_case_term'),
)
op.create_index(op.f('ix_case_phenotypes_case_id'), 'case_phenotypes', ['case_id'])
op.create_table(
'gene_phenotypes',
sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
sa.Column('gene_symbol', sa.String(length=60), nullable=False),
sa.Column('hpo_id', sa.String(length=20), nullable=False),
sa.Column('hpo_name', sa.String(length=200), nullable=False),
sa.PrimaryKeyConstraint('id'),
sa.UniqueConstraint('gene_symbol', 'hpo_id', name='uq_gene_phenotypes_gene_term'),
)
op.create_index(op.f('ix_gene_phenotypes_gene_symbol'), 'gene_phenotypes', ['gene_symbol'])
op.create_index(op.f('ix_gene_phenotypes_hpo_id'), 'gene_phenotypes', ['hpo_id'])
op.create_table(
'variant_decisions',
sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
sa.Column('variant_id', sa.Integer(), nullable=False),
sa.Column('state', sa.Enum('shortlisted', 'dismissed', name='decisionstate'), nullable=False),
sa.Column('reason', sa.String(length=120), nullable=True),
sa.Column('note', sa.Text(), nullable=True),
sa.Column('decided_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
sa.ForeignKeyConstraint(['variant_id'], ['variants.id'], ondelete='CASCADE'),
sa.PrimaryKeyConstraint('id'),
sa.UniqueConstraint('variant_id'),
)
def downgrade() -> None:
op.drop_table('variant_decisions')
sa.Enum(name='decisionstate').drop(op.get_bind(), checkfirst=True)
op.drop_index(op.f('ix_gene_phenotypes_hpo_id'), table_name='gene_phenotypes')
op.drop_index(op.f('ix_gene_phenotypes_gene_symbol'), table_name='gene_phenotypes')
op.drop_table('gene_phenotypes')
op.drop_index(op.f('ix_case_phenotypes_case_id'), table_name='case_phenotypes')
op.drop_table('case_phenotypes')
op.alter_column('jobs', 'case_id', new_column_name='sample_id')
op.rename_table('cases', 'samples')