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
+3
-3
@@ -4,7 +4,7 @@ from fastapi import APIRouter, FastAPI
|
||||
from fastapi.middleware.cors import CORSMiddleware
|
||||
|
||||
from app.config import settings
|
||||
from app.routers import jobs, predictions, samples, variants
|
||||
from app.routers import cases, jobs, phenotypes, variants
|
||||
|
||||
|
||||
@asynccontextmanager
|
||||
@@ -23,10 +23,10 @@ app.add_middleware(
|
||||
|
||||
# The ingress forwards /api/* to this service unchanged, and local dev uses the same prefix.
|
||||
api = APIRouter(prefix="/api")
|
||||
api.include_router(samples.router, prefix="/samples", tags=["samples"])
|
||||
api.include_router(cases.router, prefix="/cases", tags=["cases"])
|
||||
api.include_router(jobs.router, prefix="/jobs", tags=["jobs"])
|
||||
api.include_router(variants.router, prefix="/variants", tags=["variants"])
|
||||
api.include_router(predictions.router, prefix="/predictions", tags=["predictions"])
|
||||
api.include_router(phenotypes.router, prefix="/phenotypes", tags=["phenotypes"])
|
||||
app.include_router(api)
|
||||
|
||||
|
||||
|
||||
+63
-7
@@ -1,12 +1,23 @@
|
||||
"""SQLAlchemy 2.0 declarative models.
|
||||
|
||||
One sample -> many jobs; one job -> many variants; one variant -> one prediction (latest).
|
||||
A case is a proband: a VCF plus the phenotype terms observed in that patient. One case -> many
|
||||
jobs (pipeline runs); one job -> many variants; one variant -> one prediction and one decision.
|
||||
"""
|
||||
import enum
|
||||
import uuid
|
||||
from datetime import datetime
|
||||
|
||||
from sqlalchemy import DateTime, Enum, Float, ForeignKey, Integer, String, Text, func
|
||||
from sqlalchemy import (
|
||||
DateTime,
|
||||
Enum,
|
||||
Float,
|
||||
ForeignKey,
|
||||
Integer,
|
||||
String,
|
||||
Text,
|
||||
UniqueConstraint,
|
||||
func,
|
||||
)
|
||||
from sqlalchemy.dialects.postgresql import JSONB, UUID
|
||||
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
|
||||
|
||||
@@ -22,27 +33,58 @@ class JobStatus(str, enum.Enum):
|
||||
failed = "failed"
|
||||
|
||||
|
||||
class Sample(Base):
|
||||
__tablename__ = "samples"
|
||||
class DecisionState(str, enum.Enum):
|
||||
shortlisted = "shortlisted"
|
||||
dismissed = "dismissed"
|
||||
|
||||
|
||||
class Case(Base):
|
||||
__tablename__ = "cases"
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
|
||||
name: Mapped[str] = mapped_column(String(120), unique=True)
|
||||
vcf_uri: Mapped[str] = mapped_column(Text)
|
||||
assembly: Mapped[str] = mapped_column(String(10), default="GRCh38")
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
|
||||
jobs: Mapped[list["Job"]] = relationship(back_populates="sample")
|
||||
jobs: Mapped[list["Job"]] = relationship(back_populates="case")
|
||||
phenotypes: Mapped[list["CasePhenotype"]] = relationship(
|
||||
back_populates="case", cascade="all, delete-orphan", order_by="CasePhenotype.hpo_id"
|
||||
)
|
||||
|
||||
|
||||
class CasePhenotype(Base):
|
||||
"""An HPO term observed in this patient; the ranking matches these against gene annotations."""
|
||||
|
||||
__tablename__ = "case_phenotypes"
|
||||
__table_args__ = (UniqueConstraint("case_id", "hpo_id", name="uq_case_phenotypes_case_term"),)
|
||||
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
||||
case_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("cases.id", ondelete="CASCADE"), index=True)
|
||||
hpo_id: Mapped[str] = mapped_column(String(20))
|
||||
label: Mapped[str] = mapped_column(String(200))
|
||||
case: Mapped[Case] = relationship(back_populates="phenotypes")
|
||||
|
||||
|
||||
class GenePhenotype(Base):
|
||||
"""HPO's gene-to-phenotype annotations (scripts/load-hpo.py); read-only reference data."""
|
||||
|
||||
__tablename__ = "gene_phenotypes"
|
||||
__table_args__ = (UniqueConstraint("gene_symbol", "hpo_id", name="uq_gene_phenotypes_gene_term"),)
|
||||
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
||||
gene_symbol: Mapped[str] = mapped_column(String(60), index=True)
|
||||
hpo_id: Mapped[str] = mapped_column(String(20), index=True)
|
||||
hpo_name: Mapped[str] = mapped_column(String(200))
|
||||
|
||||
|
||||
class Job(Base):
|
||||
__tablename__ = "jobs"
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
|
||||
sample_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("samples.id", ondelete="CASCADE"))
|
||||
case_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("cases.id", ondelete="CASCADE"))
|
||||
status: Mapped[JobStatus] = mapped_column(Enum(JobStatus), default=JobStatus.queued)
|
||||
workflow_ref: Mapped[str | None] = mapped_column(String(200)) # Argo workflow name / nf run id
|
||||
vep_version: Mapped[str | None] = mapped_column(String(40))
|
||||
log: Mapped[str | None] = mapped_column(Text)
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
|
||||
finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
sample: Mapped[Sample] = relationship(back_populates="jobs")
|
||||
case: Mapped[Case] = relationship(back_populates="jobs")
|
||||
variants: Mapped[list["Variant"]] = relationship(back_populates="job")
|
||||
|
||||
|
||||
@@ -64,6 +106,7 @@ class Variant(Base):
|
||||
annotations: Mapped[dict] = mapped_column(JSONB, default=dict) # full VEP CSQ record
|
||||
job: Mapped[Job] = relationship(back_populates="variants")
|
||||
prediction: Mapped["Prediction | None"] = relationship(back_populates="variant", uselist=False)
|
||||
decision: Mapped["VariantDecision | None"] = relationship(back_populates="variant", uselist=False)
|
||||
|
||||
|
||||
class Prediction(Base):
|
||||
@@ -75,3 +118,16 @@ class Prediction(Base):
|
||||
score: Mapped[float] = mapped_column(Float) # P(pathogenic)
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
|
||||
variant: Mapped[Variant] = relationship(back_populates="prediction")
|
||||
|
||||
|
||||
class VariantDecision(Base):
|
||||
"""A reviewer's triage call. No authentication here, so decisions are shared by all visitors."""
|
||||
|
||||
__tablename__ = "variant_decisions"
|
||||
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
||||
variant_id: Mapped[int] = mapped_column(ForeignKey("variants.id", ondelete="CASCADE"), unique=True)
|
||||
state: Mapped[DecisionState] = mapped_column(Enum(DecisionState))
|
||||
reason: Mapped[str | None] = mapped_column(String(120))
|
||||
note: Mapped[str | None] = mapped_column(Text)
|
||||
decided_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
|
||||
variant: Mapped[Variant] = relationship(back_populates="decision")
|
||||
|
||||
@@ -0,0 +1,225 @@
|
||||
import logging
|
||||
import uuid
|
||||
from dataclasses import asdict
|
||||
from datetime import UTC, datetime
|
||||
|
||||
from fastapi import APIRouter, HTTPException, Query, status
|
||||
from sqlalchemy import func, select
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
from sqlalchemy.orm import selectinload
|
||||
|
||||
from app.db import SessionDep
|
||||
from app.models import (
|
||||
Case,
|
||||
CasePhenotype,
|
||||
DecisionState,
|
||||
Job,
|
||||
JobStatus,
|
||||
Variant,
|
||||
VariantDecision,
|
||||
)
|
||||
from app.schemas import (
|
||||
CandidateOut,
|
||||
CandidatePage,
|
||||
CaseCreate,
|
||||
CaseOut,
|
||||
FunnelOut,
|
||||
JobOut,
|
||||
ProvenanceOut,
|
||||
ReportOut,
|
||||
ScoreOut,
|
||||
)
|
||||
from app.services import candidates as case_view
|
||||
from app.services import events, triage
|
||||
from app.services.scoring import score_job
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
async def _case_or_404(session: SessionDep, case_id: uuid.UUID) -> Case:
|
||||
case = await case_view.get_case(session, case_id)
|
||||
if case is None:
|
||||
raise HTTPException(404, "case not found")
|
||||
return case
|
||||
|
||||
|
||||
async def _shortlisted_counts(session: SessionDep, case_ids: list[uuid.UUID]) -> dict[uuid.UUID, int]:
|
||||
if not case_ids:
|
||||
return {}
|
||||
rows = await session.execute(
|
||||
select(Job.case_id, func.count(VariantDecision.id))
|
||||
.join(Variant, Variant.job_id == Job.id)
|
||||
.join(VariantDecision, VariantDecision.variant_id == Variant.id)
|
||||
.where(Job.case_id.in_(case_ids), VariantDecision.state == DecisionState.shortlisted)
|
||||
.group_by(Job.case_id)
|
||||
)
|
||||
return dict(rows.all()) # type: ignore[arg-type]
|
||||
|
||||
|
||||
async def _latest_jobs(session: SessionDep, case_ids: list[uuid.UUID]) -> dict[uuid.UUID, Job]:
|
||||
if not case_ids:
|
||||
return {}
|
||||
jobs = await session.scalars(
|
||||
select(Job).where(Job.case_id.in_(case_ids)).order_by(Job.created_at.desc())
|
||||
)
|
||||
latest: dict[uuid.UUID, Job] = {}
|
||||
for job in jobs: # ordered newest first, so the first one wins
|
||||
latest.setdefault(job.case_id, job)
|
||||
return latest
|
||||
|
||||
|
||||
def _as_case_out(case: Case, job: Job | None, shortlisted: int) -> CaseOut:
|
||||
out = CaseOut.model_validate(case)
|
||||
out.latest_job = JobOut.model_validate(job) if job is not None else None
|
||||
out.shortlisted = shortlisted
|
||||
return out
|
||||
|
||||
|
||||
@router.get("", response_model=list[CaseOut])
|
||||
async def list_cases(session: SessionDep):
|
||||
cases = (
|
||||
await session.scalars(
|
||||
select(Case).order_by(Case.created_at.desc()).options(selectinload(Case.phenotypes))
|
||||
)
|
||||
).all()
|
||||
ids = [c.id for c in cases]
|
||||
jobs, counts = await _latest_jobs(session, ids), await _shortlisted_counts(session, ids)
|
||||
return [_as_case_out(c, jobs.get(c.id), counts.get(c.id, 0)) for c in cases]
|
||||
|
||||
|
||||
@router.post("", response_model=CaseOut, status_code=status.HTTP_201_CREATED)
|
||||
async def create_case(payload: CaseCreate, session: SessionDep):
|
||||
case = Case(
|
||||
name=payload.name,
|
||||
vcf_uri=payload.vcf_uri,
|
||||
assembly=payload.assembly,
|
||||
phenotypes=[CasePhenotype(hpo_id=p.hpo_id, label=p.label) for p in payload.phenotypes],
|
||||
)
|
||||
session.add(case)
|
||||
try:
|
||||
await session.commit()
|
||||
except IntegrityError: # cases.name is unique
|
||||
await session.rollback()
|
||||
raise HTTPException(409, f"a case named {payload.name!r} already exists") from None
|
||||
await session.refresh(case, attribute_names=["phenotypes"])
|
||||
return _as_case_out(case, None, 0)
|
||||
|
||||
|
||||
@router.get("/{case_id}", response_model=CaseOut)
|
||||
async def get_case(case_id: uuid.UUID, session: SessionDep):
|
||||
case = await _case_or_404(session, case_id)
|
||||
counts = await _shortlisted_counts(session, [case_id])
|
||||
return _as_case_out(case, await case_view.latest_job(session, case_id), counts.get(case_id, 0))
|
||||
|
||||
|
||||
@router.get("/{case_id}/jobs", response_model=list[JobOut])
|
||||
async def list_jobs(case_id: uuid.UUID, session: SessionDep):
|
||||
result = await session.scalars(
|
||||
select(Job).where(Job.case_id == case_id).order_by(Job.created_at.desc())
|
||||
)
|
||||
return result.all()
|
||||
|
||||
|
||||
@router.post("/{case_id}/annotate", response_model=JobOut, status_code=status.HTTP_202_ACCEPTED)
|
||||
async def annotate(case_id: uuid.UUID, session: SessionDep):
|
||||
case = await _case_or_404(session, case_id)
|
||||
# Commit `running` before launching: a local run that dies instantly is marked failed by its
|
||||
# watcher, and a later status write here would overwrite that.
|
||||
job = Job(case_id=case.id, status=JobStatus.running)
|
||||
session.add(job)
|
||||
await session.commit()
|
||||
try:
|
||||
job.workflow_ref = await events.launch(job.id, case.vcf_uri, case.assembly)
|
||||
except events.LaunchError as e:
|
||||
job.status = JobStatus.failed
|
||||
job.log = str(e)
|
||||
job.finished_at = datetime.now(UTC)
|
||||
await session.commit()
|
||||
await session.refresh(job)
|
||||
return job
|
||||
|
||||
|
||||
@router.post("/{case_id}/score", response_model=ScoreOut)
|
||||
async def score(case_id: uuid.UUID, session: SessionDep):
|
||||
await _case_or_404(session, case_id)
|
||||
job = await case_view.latest_job(session, case_id, status=JobStatus.succeeded)
|
||||
if job is None:
|
||||
raise HTTPException(409, "no finished annotation to score")
|
||||
try:
|
||||
scored, version = await score_job(job.id, session)
|
||||
except Exception as e:
|
||||
# No registry, no model behind the alias, a model that will not load: all of these are
|
||||
# the environment being unready, not a bug in the request. Say so rather than throwing 500.
|
||||
logger.exception("scoring case %s failed", case_id)
|
||||
raise HTTPException(503, f"could not score with the model: {e}") from e
|
||||
return ScoreOut(case_id=case_id, scored=scored, model_version=version)
|
||||
|
||||
|
||||
@router.get("/{case_id}/candidates", response_model=CandidatePage)
|
||||
async def list_candidates(
|
||||
case_id: uuid.UUID,
|
||||
session: SessionDep,
|
||||
gene: str | None = None,
|
||||
impact: str | None = Query(None, pattern="^(HIGH|MODERATE|LOW|MODIFIER)$"),
|
||||
max_af: float | None = Query(None, ge=0, le=1),
|
||||
state: str | None = Query(None, pattern="^(shortlisted|dismissed|undecided)$"),
|
||||
limit: int = Query(50, ge=1, le=500),
|
||||
offset: int = Query(0, ge=0),
|
||||
) -> CandidatePage:
|
||||
case = await _case_or_404(session, case_id)
|
||||
view = await case_view.build(session, case)
|
||||
|
||||
items = view.candidates
|
||||
if gene:
|
||||
items = [c for c in items if (c.variant.gene or "").upper() == gene.upper()]
|
||||
if impact:
|
||||
items = [c for c in items if c.variant.impact == impact]
|
||||
if max_af is not None:
|
||||
items = [c for c in items if c.variant.gnomad_af is None or c.variant.gnomad_af <= max_af]
|
||||
if state == "undecided":
|
||||
items = [c for c in items if c.variant.decision is None]
|
||||
elif state is not None:
|
||||
items = [c for c in items if c.variant.decision and c.variant.decision.state.value == state]
|
||||
|
||||
labels = view.labels
|
||||
return CandidatePage(
|
||||
# The funnel describes the whole case, not the filtered view.
|
||||
funnel=FunnelOut(**asdict(view.funnel)),
|
||||
weights=triage.WEIGHTS,
|
||||
items=[CandidateOut.from_candidate(c, labels) for c in items[offset : offset + limit]],
|
||||
total=len(items),
|
||||
limit=limit,
|
||||
offset=offset,
|
||||
)
|
||||
|
||||
|
||||
@router.get("/{case_id}/report", response_model=ReportOut)
|
||||
async def report(case_id: uuid.UUID, session: SessionDep) -> ReportOut:
|
||||
case = await _case_or_404(session, case_id)
|
||||
view = await case_view.build(session, case)
|
||||
labels = view.labels
|
||||
|
||||
def decided(state: DecisionState) -> list[CandidateOut]:
|
||||
return [
|
||||
CandidateOut.from_candidate(c, labels)
|
||||
for c in view.candidates
|
||||
if c.variant.decision is not None and c.variant.decision.state == state
|
||||
]
|
||||
|
||||
shortlisted, dismissed = decided(DecisionState.shortlisted), decided(DecisionState.dismissed)
|
||||
prediction = next((c.variant.prediction for c in view.candidates if c.variant.prediction), None)
|
||||
return ReportOut(
|
||||
case=_as_case_out(case, view.job, len(shortlisted)),
|
||||
funnel=FunnelOut(**asdict(view.funnel)),
|
||||
generated_at=datetime.now(UTC),
|
||||
provenance=ProvenanceOut(
|
||||
job_id=view.job.id if view.job else None,
|
||||
vep_version=view.job.vep_version if view.job else None,
|
||||
finished_at=view.job.finished_at if view.job else None,
|
||||
model_name=prediction.model_name if prediction else None,
|
||||
model_version=prediction.model_version if prediction else None,
|
||||
),
|
||||
shortlisted=shortlisted,
|
||||
dismissed=dismissed,
|
||||
)
|
||||
@@ -0,0 +1,25 @@
|
||||
from fastapi import APIRouter, Query
|
||||
from sqlalchemy import select
|
||||
|
||||
from app.db import SessionDep
|
||||
from app.models import GenePhenotype
|
||||
from app.schemas import PhenotypeTerm
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
@router.get("", response_model=list[PhenotypeTerm])
|
||||
async def search(
|
||||
session: SessionDep,
|
||||
q: str = Query(min_length=2, max_length=100),
|
||||
limit: int = Query(20, ge=1, le=100),
|
||||
) -> list[PhenotypeTerm]:
|
||||
"""Type-ahead over the HPO terms that are annotated to at least one gene."""
|
||||
rows = await session.execute(
|
||||
select(GenePhenotype.hpo_id, GenePhenotype.hpo_name)
|
||||
.where(GenePhenotype.hpo_name.ilike(f"%{q}%"))
|
||||
.distinct()
|
||||
.order_by(GenePhenotype.hpo_name)
|
||||
.limit(limit)
|
||||
)
|
||||
return [PhenotypeTerm(hpo_id=hpo_id, label=name) for hpo_id, name in rows]
|
||||
@@ -1,22 +0,0 @@
|
||||
import uuid
|
||||
|
||||
from fastapi import APIRouter, HTTPException
|
||||
|
||||
from app.db import SessionDep
|
||||
from app.models import Job, JobStatus
|
||||
from app.schemas import ScoreOut
|
||||
from app.services.scoring import score_job
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
@router.post("/score/{job_id}", response_model=ScoreOut)
|
||||
async def score(job_id: uuid.UUID, session: SessionDep) -> ScoreOut:
|
||||
"""Score every variant of a finished job with the model behind the registry alias."""
|
||||
job = await session.get(Job, job_id)
|
||||
if job is None:
|
||||
raise HTTPException(404, "job not found")
|
||||
if job.status != JobStatus.succeeded:
|
||||
raise HTTPException(409, f"job is {job.status.value}; only succeeded jobs can be scored")
|
||||
n, version = await score_job(job_id, session)
|
||||
return ScoreOut(job_id=job_id, scored=n, model_version=version)
|
||||
@@ -1,61 +0,0 @@
|
||||
import uuid
|
||||
from datetime import UTC, datetime
|
||||
|
||||
from fastapi import APIRouter, HTTPException, status
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
|
||||
from app.db import SessionDep
|
||||
from app.models import Job, JobStatus, Sample
|
||||
from app.schemas import JobOut, SampleCreate, SampleOut
|
||||
from app.services import events
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
@router.get("", response_model=list[SampleOut])
|
||||
async def list_samples(session: SessionDep):
|
||||
result = await session.scalars(select(Sample).order_by(Sample.created_at.desc()))
|
||||
return result.all()
|
||||
|
||||
|
||||
@router.post("", response_model=SampleOut, status_code=status.HTTP_201_CREATED)
|
||||
async def create_sample(payload: SampleCreate, session: SessionDep):
|
||||
sample = Sample(**payload.model_dump())
|
||||
session.add(sample)
|
||||
try:
|
||||
await session.commit()
|
||||
except IntegrityError: # samples.name is unique
|
||||
await session.rollback()
|
||||
raise HTTPException(409, f"a sample named {payload.name!r} already exists") from None
|
||||
await session.refresh(sample)
|
||||
return sample
|
||||
|
||||
|
||||
@router.get("/{sample_id}/jobs", response_model=list[JobOut])
|
||||
async def list_jobs(sample_id: uuid.UUID, session: SessionDep):
|
||||
result = await session.scalars(
|
||||
select(Job).where(Job.sample_id == sample_id).order_by(Job.created_at.desc())
|
||||
)
|
||||
return result.all()
|
||||
|
||||
|
||||
@router.post("/{sample_id}/annotate", response_model=JobOut, status_code=status.HTTP_202_ACCEPTED)
|
||||
async def annotate(sample_id: uuid.UUID, session: SessionDep):
|
||||
sample = await session.get(Sample, sample_id)
|
||||
if sample is None:
|
||||
raise HTTPException(404, "sample not found")
|
||||
# Commit `running` before launching: a local run that dies instantly is marked failed by its
|
||||
# watcher, and a later status write here would overwrite that.
|
||||
job = Job(sample_id=sample.id, status=JobStatus.running)
|
||||
session.add(job)
|
||||
await session.commit()
|
||||
try:
|
||||
job.workflow_ref = await events.launch(job.id, sample.vcf_uri, sample.assembly)
|
||||
except events.LaunchError as e:
|
||||
job.status = JobStatus.failed
|
||||
job.log = str(e)
|
||||
job.finished_at = datetime.now(UTC)
|
||||
await session.commit()
|
||||
await session.refresh(job)
|
||||
return job
|
||||
+52
-49
@@ -1,60 +1,63 @@
|
||||
import uuid
|
||||
|
||||
from fastapi import APIRouter, Query
|
||||
from sqlalchemy import Integer, case, cast, func, select
|
||||
from fastapi import APIRouter, HTTPException
|
||||
from sqlalchemy import func, select
|
||||
from sqlalchemy.dialects.postgresql import insert
|
||||
from sqlalchemy.orm import selectinload
|
||||
|
||||
from app.db import SessionDep
|
||||
from app.models import Prediction, Variant
|
||||
from app.schemas import VariantOut, VariantPage
|
||||
from app.models import Variant, VariantDecision
|
||||
from app.schemas import CandidateOut, DecisionIn, DecisionOut, VariantDetailOut
|
||||
from app.services import candidates as case_view
|
||||
from app.services import triage
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
# Karyotype order (1..22, X, Y, MT) instead of text order, where "10" sorts before "2".
|
||||
_chrom = func.regexp_replace(Variant.chrom, "^chr", "", "i")
|
||||
CHROM_ORDER = case(
|
||||
(_chrom.regexp_match("^[0-9]+$"), cast(_chrom, Integer)),
|
||||
(_chrom == "X", 23),
|
||||
(_chrom == "Y", 24),
|
||||
(_chrom.in_(["M", "MT"]), 25),
|
||||
else_=26,
|
||||
)
|
||||
|
||||
|
||||
@router.get("", response_model=VariantPage)
|
||||
async def list_variants(
|
||||
job_id: uuid.UUID,
|
||||
session: SessionDep,
|
||||
gene: str | None = None,
|
||||
impact: str | None = Query(None, pattern="^(HIGH|MODERATE|LOW|MODIFIER)$"),
|
||||
max_af: float | None = Query(None, ge=0, le=1),
|
||||
min_score: float | None = Query(None, ge=0, le=1),
|
||||
limit: int = Query(50, ge=1, le=500),
|
||||
offset: int = Query(0, ge=0),
|
||||
) -> VariantPage:
|
||||
stmt = select(Variant).where(Variant.job_id == job_id)
|
||||
if gene:
|
||||
stmt = stmt.where(Variant.gene == gene.upper())
|
||||
if impact:
|
||||
stmt = stmt.where(Variant.impact == impact)
|
||||
if max_af is not None:
|
||||
stmt = stmt.where((Variant.gnomad_af.is_(None)) | (Variant.gnomad_af <= max_af))
|
||||
if min_score is not None:
|
||||
stmt = stmt.join(Prediction, Prediction.variant_id == Variant.id).where(
|
||||
Prediction.score >= min_score
|
||||
@router.get("/{variant_id}", response_model=VariantDetailOut)
|
||||
async def get_variant(variant_id: int, session: SessionDep) -> VariantDetailOut:
|
||||
"""Every piece of evidence for one variant, including the raw VEP record."""
|
||||
variant = await session.scalar(
|
||||
select(Variant)
|
||||
.where(Variant.id == variant_id)
|
||||
.options(
|
||||
selectinload(Variant.prediction),
|
||||
selectinload(Variant.decision),
|
||||
selectinload(Variant.job),
|
||||
)
|
||||
)
|
||||
if variant is None:
|
||||
raise HTTPException(404, "variant not found")
|
||||
case = await case_view.get_case(session, variant.job.case_id)
|
||||
terms = [p.hpo_id for p in case.phenotypes] if case else []
|
||||
gene_terms = await case_view.gene_terms_for(session, {variant.gene} if variant.gene else set())
|
||||
|
||||
total = await session.scalar(select(func.count()).select_from(stmt.subquery()))
|
||||
rows = await session.scalars(
|
||||
stmt.options(selectinload(Variant.prediction))
|
||||
# id breaks ties between split multiallelics at one position, keeping pages stable.
|
||||
.order_by(CHROM_ORDER, Variant.chrom, Variant.pos, Variant.id)
|
||||
.limit(limit)
|
||||
.offset(offset)
|
||||
# evaluate, not rank: the panel must work for a variant that did not make the candidate list.
|
||||
scored = triage.evaluate(variant, terms, gene_terms)
|
||||
labels = {p.hpo_id: p.label for p in case.phenotypes} if case else {}
|
||||
base = CandidateOut.from_candidate(scored, labels).model_dump()
|
||||
return VariantDetailOut(**base, annotations=variant.annotations or {})
|
||||
|
||||
|
||||
@router.post("/{variant_id}/decision", response_model=DecisionOut)
|
||||
async def decide(variant_id: int, payload: DecisionIn, session: SessionDep) -> DecisionOut:
|
||||
if await session.get(Variant, variant_id) is None:
|
||||
raise HTTPException(404, "variant not found")
|
||||
stmt = insert(VariantDecision).values(
|
||||
variant_id=variant_id, state=payload.state, reason=payload.reason, note=payload.note
|
||||
)
|
||||
return VariantPage(
|
||||
items=[VariantOut.model_validate(v) for v in rows],
|
||||
total=total or 0,
|
||||
limit=limit,
|
||||
offset=offset,
|
||||
# Changing your mind replaces the call rather than failing on the unique constraint.
|
||||
await session.execute(
|
||||
stmt.on_conflict_do_update(
|
||||
index_elements=[VariantDecision.variant_id],
|
||||
set_={
|
||||
"state": stmt.excluded.state,
|
||||
"reason": stmt.excluded.reason,
|
||||
"note": stmt.excluded.note,
|
||||
"decided_at": func.now(),
|
||||
},
|
||||
)
|
||||
)
|
||||
await session.commit()
|
||||
decision = await session.scalar(
|
||||
select(VariantDecision).where(VariantDecision.variant_id == variant_id)
|
||||
)
|
||||
return DecisionOut.model_validate(decision)
|
||||
|
||||
+99
-19
@@ -2,12 +2,15 @@ import re
|
||||
import uuid
|
||||
from datetime import datetime
|
||||
from pathlib import PurePosixPath
|
||||
from typing import Literal
|
||||
from typing import TYPE_CHECKING, Literal
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||||
|
||||
from app.config import settings
|
||||
from app.models import JobStatus
|
||||
from app.models import DecisionState, JobStatus
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from app.services.triage import Candidate
|
||||
|
||||
|
||||
class ORMModel(BaseModel):
|
||||
@@ -19,11 +22,18 @@ VCF_SUFFIXES = (".vcf", ".vcf.gz", ".vcf.bgz", ".bcf")
|
||||
GCS_URI = re.compile(r"gs://[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]/\S+")
|
||||
|
||||
|
||||
class SampleCreate(BaseModel):
|
||||
class PhenotypeTerm(ORMModel):
|
||||
"""An HPO term: the id is what ranking matches on, the label is for people."""
|
||||
|
||||
hpo_id: str = Field(pattern=r"^HP:\d{7}$")
|
||||
label: str = Field(min_length=1, max_length=200)
|
||||
|
||||
|
||||
class CaseCreate(BaseModel):
|
||||
name: str = Field(min_length=1, max_length=120)
|
||||
vcf_uri: str
|
||||
# Passed to VEP --assembly; the VEP cache must contain it.
|
||||
assembly: Assembly = "GRCh38"
|
||||
phenotypes: list[PhenotypeTerm] = Field(default_factory=list, max_length=100)
|
||||
|
||||
@field_validator("vcf_uri")
|
||||
@classmethod
|
||||
@@ -44,17 +54,9 @@ class SampleCreate(BaseModel):
|
||||
return v
|
||||
|
||||
|
||||
class SampleOut(ORMModel):
|
||||
id: uuid.UUID
|
||||
name: str
|
||||
vcf_uri: str
|
||||
assembly: str
|
||||
created_at: datetime
|
||||
|
||||
|
||||
class JobOut(ORMModel):
|
||||
id: uuid.UUID
|
||||
sample_id: uuid.UUID
|
||||
case_id: uuid.UUID
|
||||
status: JobStatus
|
||||
workflow_ref: str | None
|
||||
vep_version: str | None
|
||||
@@ -63,6 +65,17 @@ class JobOut(ORMModel):
|
||||
finished_at: datetime | None
|
||||
|
||||
|
||||
class CaseOut(ORMModel):
|
||||
id: uuid.UUID
|
||||
name: str
|
||||
vcf_uri: str
|
||||
assembly: str
|
||||
created_at: datetime
|
||||
phenotypes: list[PhenotypeTerm] = Field(default_factory=list)
|
||||
latest_job: JobOut | None = None
|
||||
shortlisted: int = 0
|
||||
|
||||
|
||||
class PredictionOut(ORMModel):
|
||||
model_name: str
|
||||
model_version: str
|
||||
@@ -85,14 +98,81 @@ class VariantOut(ORMModel):
|
||||
prediction: PredictionOut | None = None
|
||||
|
||||
|
||||
class ScoreOut(BaseModel):
|
||||
job_id: uuid.UUID
|
||||
scored: int
|
||||
model_version: str
|
||||
class DecisionIn(BaseModel):
|
||||
state: DecisionState
|
||||
reason: str | None = Field(None, max_length=120)
|
||||
note: str | None = Field(None, max_length=2000)
|
||||
|
||||
|
||||
class VariantPage(BaseModel):
|
||||
items: list[VariantOut]
|
||||
class DecisionOut(ORMModel):
|
||||
state: DecisionState
|
||||
reason: str | None
|
||||
note: str | None
|
||||
decided_at: datetime
|
||||
|
||||
|
||||
class CandidateOut(BaseModel):
|
||||
variant: VariantOut
|
||||
score: float
|
||||
components: dict[str, float]
|
||||
matched_terms: list[PhenotypeTerm]
|
||||
scored: bool
|
||||
decision: DecisionOut | None = None
|
||||
|
||||
@classmethod
|
||||
def from_candidate(cls, candidate: "Candidate", labels: dict[str, str]) -> "CandidateOut":
|
||||
variant = candidate.variant
|
||||
return cls(
|
||||
variant=VariantOut.model_validate(variant),
|
||||
score=round(candidate.score, 4),
|
||||
components={name: round(v, 4) for name, v in candidate.components.items()},
|
||||
matched_terms=[
|
||||
PhenotypeTerm(hpo_id=term, label=labels.get(term, term))
|
||||
for term in candidate.matched_terms
|
||||
],
|
||||
scored=candidate.scored,
|
||||
decision=DecisionOut.model_validate(variant.decision) if variant.decision else None,
|
||||
)
|
||||
|
||||
|
||||
class VariantDetailOut(CandidateOut):
|
||||
annotations: dict
|
||||
|
||||
|
||||
class FunnelOut(BaseModel):
|
||||
total: int
|
||||
rare: int
|
||||
candidates: int
|
||||
phenotype_matched: int
|
||||
|
||||
|
||||
class CandidatePage(BaseModel):
|
||||
funnel: FunnelOut
|
||||
weights: dict[str, float]
|
||||
items: list[CandidateOut]
|
||||
total: int
|
||||
limit: int
|
||||
offset: int
|
||||
|
||||
|
||||
class ProvenanceOut(BaseModel):
|
||||
job_id: uuid.UUID | None = None
|
||||
vep_version: str | None = None
|
||||
finished_at: datetime | None = None
|
||||
model_name: str | None = None
|
||||
model_version: str | None = None
|
||||
|
||||
|
||||
class ReportOut(BaseModel):
|
||||
case: CaseOut
|
||||
funnel: FunnelOut
|
||||
generated_at: datetime
|
||||
provenance: ProvenanceOut
|
||||
shortlisted: list[CandidateOut]
|
||||
dismissed: list[CandidateOut]
|
||||
|
||||
|
||||
class ScoreOut(BaseModel):
|
||||
case_id: uuid.UUID
|
||||
scored: int
|
||||
model_version: str
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
"""Assemble a case's ranked candidates: load the latest results, rank them, attach decisions.
|
||||
|
||||
Everything for one job is loaded at once, which is fine for a gene panel or a chromosome — the
|
||||
size of case this demo handles. A whole genome would need the narrowing pushed into SQL.
|
||||
"""
|
||||
import uuid
|
||||
from dataclasses import dataclass
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm import selectinload
|
||||
|
||||
from app.models import Case, GenePhenotype, Job, JobStatus, Variant
|
||||
from app.services import triage
|
||||
|
||||
EMPTY_FUNNEL = triage.Funnel(total=0, rare=0, candidates=0, phenotype_matched=0)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CaseView:
|
||||
case: Case
|
||||
job: Job | None
|
||||
funnel: triage.Funnel
|
||||
candidates: list[triage.Candidate]
|
||||
|
||||
@property
|
||||
def labels(self) -> dict[str, str]:
|
||||
return {p.hpo_id: p.label for p in self.case.phenotypes}
|
||||
|
||||
|
||||
async def get_case(session: AsyncSession, case_id: uuid.UUID) -> Case | None:
|
||||
return await session.scalar(
|
||||
select(Case).where(Case.id == case_id).options(selectinload(Case.phenotypes))
|
||||
)
|
||||
|
||||
|
||||
async def latest_job(
|
||||
session: AsyncSession, case_id: uuid.UUID, *, status: JobStatus | None = None
|
||||
) -> Job | None:
|
||||
stmt = select(Job).where(Job.case_id == case_id).order_by(Job.created_at.desc()).limit(1)
|
||||
if status is not None:
|
||||
stmt = stmt.where(Job.status == status)
|
||||
return await session.scalar(stmt)
|
||||
|
||||
|
||||
async def gene_terms_for(session: AsyncSession, genes: set[str]) -> dict[str, set[str]]:
|
||||
"""gene symbol -> the HPO terms annotated to it."""
|
||||
if not genes:
|
||||
return {}
|
||||
rows = await session.execute(
|
||||
select(GenePhenotype.gene_symbol, GenePhenotype.hpo_id).where(
|
||||
GenePhenotype.gene_symbol.in_(genes)
|
||||
)
|
||||
)
|
||||
index: dict[str, set[str]] = {}
|
||||
for gene, hpo_id in rows:
|
||||
index.setdefault(gene, set()).add(hpo_id)
|
||||
return index
|
||||
|
||||
|
||||
async def build(session: AsyncSession, case: Case) -> CaseView:
|
||||
job = await latest_job(session, case.id, status=JobStatus.succeeded)
|
||||
if job is None:
|
||||
return CaseView(case=case, job=None, funnel=EMPTY_FUNNEL, candidates=[])
|
||||
variants = (
|
||||
await session.scalars(
|
||||
select(Variant)
|
||||
.where(Variant.job_id == job.id)
|
||||
.options(selectinload(Variant.prediction), selectinload(Variant.decision))
|
||||
)
|
||||
).all()
|
||||
case_terms = [p.hpo_id for p in case.phenotypes]
|
||||
gene_terms = await gene_terms_for(session, {v.gene for v in variants if v.gene})
|
||||
return CaseView(
|
||||
case=case,
|
||||
job=job,
|
||||
funnel=triage.funnel(variants, case_terms, gene_terms),
|
||||
candidates=triage.rank(variants, case_terms, gene_terms),
|
||||
)
|
||||
@@ -0,0 +1,106 @@
|
||||
"""Narrow a case's variants the way a clinical scientist does, and say why.
|
||||
|
||||
The rank is a weighted sum of four parts a reviewer can audit. ClinVar is deliberately not one of
|
||||
them: it is shown beside the result as independent confirmation, so a variant never ranks highly
|
||||
merely because ClinVar already called it pathogenic.
|
||||
|
||||
Rarity and consequence *filter* (the usual first pass); phenotype only *ranks*, because a real
|
||||
diagnosis can sit in a gene nobody has annotated yet and filtering on it would hide exactly that.
|
||||
"""
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
|
||||
from app.models import Variant
|
||||
|
||||
WEIGHTS = {"phenotype": 0.35, "rarity": 0.25, "consequence": 0.20, "model": 0.20}
|
||||
|
||||
RARE_AF = 0.001
|
||||
CANDIDATE_IMPACTS = frozenset({"HIGH", "MODERATE"})
|
||||
IMPACT_SEVERITY = {"HIGH": 1.0, "MODERATE": 0.6, "LOW": 0.2, "MODIFIER": 0.0}
|
||||
# Allele frequency ceiling -> score, rarest first.
|
||||
RARITY_STEPS = ((0.0, 1.0), (0.0001, 0.8), (0.001, 0.5), (0.01, 0.2))
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Funnel:
|
||||
"""How many variants survive each narrowing step; the headline of the case page."""
|
||||
|
||||
total: int
|
||||
rare: int
|
||||
candidates: int
|
||||
phenotype_matched: int
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Candidate:
|
||||
variant: Variant
|
||||
score: float
|
||||
components: dict[str, float]
|
||||
matched_terms: list[str]
|
||||
scored: bool
|
||||
|
||||
|
||||
def rarity_score(af: float | None) -> float:
|
||||
if af is None: # absent from gnomAD
|
||||
return 1.0
|
||||
for ceiling, score in RARITY_STEPS:
|
||||
if af <= ceiling:
|
||||
return score
|
||||
return 0.0
|
||||
|
||||
|
||||
def consequence_score(impact: str | None) -> float:
|
||||
return IMPACT_SEVERITY.get(impact or "", 0.0)
|
||||
|
||||
|
||||
def phenotype_score(
|
||||
gene: str | None, case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
|
||||
) -> tuple[float, list[str]]:
|
||||
"""What fraction of the patient's terms HPO associates with this gene, and which ones."""
|
||||
if not gene or not case_terms:
|
||||
return 0.0, []
|
||||
annotated = gene_terms.get(gene, set())
|
||||
matched = [term for term in case_terms if term in annotated]
|
||||
return len(matched) / len(case_terms), matched
|
||||
|
||||
|
||||
def is_rare(variant: Variant) -> bool:
|
||||
return variant.gnomad_af is None or variant.gnomad_af < RARE_AF
|
||||
|
||||
|
||||
def is_candidate(variant: Variant) -> bool:
|
||||
return is_rare(variant) and variant.impact in CANDIDATE_IMPACTS
|
||||
|
||||
|
||||
def funnel(
|
||||
variants: Sequence[Variant], case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
|
||||
) -> Funnel:
|
||||
rare = [v for v in variants if is_rare(v)]
|
||||
candidates = [v for v in rare if v.impact in CANDIDATE_IMPACTS]
|
||||
matched = sum(1 for v in candidates if phenotype_score(v.gene, case_terms, gene_terms)[1])
|
||||
return Funnel(len(variants), len(rare), len(candidates), matched)
|
||||
|
||||
|
||||
def evaluate(
|
||||
variant: Variant, case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
|
||||
) -> Candidate:
|
||||
"""Score one variant, whether or not it survived the filters."""
|
||||
phenotype, matched = phenotype_score(variant.gene, case_terms, gene_terms)
|
||||
prediction = variant.prediction
|
||||
components = {
|
||||
"phenotype": phenotype,
|
||||
"rarity": rarity_score(variant.gnomad_af),
|
||||
"consequence": consequence_score(variant.impact),
|
||||
"model": float(prediction.score) if prediction is not None else 0.0,
|
||||
}
|
||||
score = sum(WEIGHTS[name] * value for name, value in components.items())
|
||||
return Candidate(variant, score, components, matched, prediction is not None)
|
||||
|
||||
|
||||
def rank(
|
||||
variants: Sequence[Variant], case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
|
||||
) -> list[Candidate]:
|
||||
candidates = [evaluate(v, case_terms, gene_terms) for v in variants if is_candidate(v)]
|
||||
# id breaks ties, so equal scores do not shuffle between requests.
|
||||
candidates.sort(key=lambda c: (-c.score, c.variant.id))
|
||||
return candidates
|
||||
Reference in New Issue
Block a user