ingmar — viral polyprotein cleavage-site heads

Per-class linear heads over frozen ESMC-300M embeddings for viral polyprotein protease-cleavage-site prediction, with a family router. Part of the clear-bio/ingmar pipeline (pip install ingmar — these heads ship inside the package; this repo is the standalone artifact + documentation).

What's here

path	content
heads_v5/heads_v5_fold{0-4}.npz	shipped — 16 per-class logistic heads + generalist (v4 classes + TTSP, AVP, assemblin), 5-fold cross-validation ensembles (1,920-dim P1‖P1′ features, ESMC-300M L29 post-norm)
heads_v4/heads_v4_fold{0-4}.npz	v4 baseline (13 classes + generalist), retained for reproducibility
family_profiles.json	kmer-composition family profiles for the homology router fallback
legacy/	superseded single heads (300M/600M "full" recipe with PSSM+disorder features; scan-mode head)

Performance (held-out lockbox, exact labels, 3,980 candidates / 344 positives / 93 parents)

arm	PR-AUC	95% CI
union v5 (default)	0.673	[0.610, 0.727]
generalist v5	0.665	[0.608, 0.719]
gated v5 (family-routed)	0.645	[0.577, 0.703]
union v4 (previous ship)	0.666	—
classic (non-pLM motif track)	0.440	—
legacy full600	0.417	[0.369, 0.473]
legacy full300	0.325	[0.277, 0.382]

Paired bootstrap, v5 union vs v4 union: +0.007 [−0.008, +0.023] (non-inferior; ship gate ≥ 0.666 passed). v5 union vs classic track: +0.233 [+0.168, +0.290]. Glycoprotein holdout (1,778 positives from the UniProt v5 harvest, held out from training): union 0.867 vs generalist 0.805; glyco-maturation slice 0.900 vs 0.843 (+0.058 [+0.042, +0.072]). Evaluation: scripts/lockbox_eval_variant.py in the GitHub repo; audit trail in notes/atlas_v5_extension.md + notes/integrity_audit.md.

Usage

from ingmar.routed import score_sequence_cuts

rows = score_sequence_cuts(
    seq, cuts,                 # cuts = 0-based P1' candidate indices
    family="picornavirus",     # or lineage="...", or omit for union arm
    arm="union",               # union | gated | gated_rules | generalist
)

Known limitations

• TTSP head underperforms the generalist on TTSP cuts (−0.098 PR-AUC, 95% CI [−0.173, −0.020] on the glycoprotein holdout): motif-poor extended loops, enzyme-heterogeneous class. Treat TTSP-class scores as experimental; the union arm still nets positive overall.
• host-signalase and Flavi-Ser classes are weak (representation-limited: ±4-residue embedding features do not capture the signal-peptide h-region context; see notes/fold3_investigation.md). Treat low scores in flavivirus structural regions as uninformative, not negative.
• Trained on RefSeq/ViralZone/poly8/UniProt annotated junctions (14,314-site atlas v5); families outside the training corpus route via kmer homology with degraded class coverage.
• StopGo and VP0-maturation "cuts" are non-proteolytic and handled by rules (ingmar.protease_router), not these heads.

Citation

If you use these heads, cite the ESMC backbone (Hayes et al., Science 2025, 10.1126/science.ads0018) and link the GitHub repo above.