feat: script to annotate proteome hits onto winnow outputs

[JemmaLDaniel]

Summary

Adds a post-winnow predict utility that annotates prediction outputs with a proteome_hit column by matching peptides against a reference FASTA proteome.

The command drops short peptides (default: fewer than 7 tokeniser residues), strips modifications and normalises I/L for matching, then uses Aho-Corasick substring search. It updates preds_and_fdr_metrics.csv in place and filters metadata.csv to the retained spectra.

The resulting proteome_hit column is designed to feed winnow diagnose-calibration via diagnostics.label_source=precomputed diagnostics.label_column=proteome_hit.

Changes

• New library module winnow/scripts/annotate_proteome_hits.py holding the matching logic (FASTA loading, modification stripping, residue tokenisation, batched substring search, folder annotation).
• New CLI subcommand winnow annotate-proteome-hits on the main Typer app in winnow/scripts/main.py, following the existing lazy-import pattern..
• Tokenisation uses instanovo.utils.residues.ResidueSet.tokenize.
• biopython and pyahocorasick are added as an optional proteome extra (pip install 'winnow-fdr[proteome]'), not as core dependencies. Their imports are lazy and guarded, so the base install and winnow.scripts.main remain importable without the extra.
• Documentation for the new command and the [proteome] extra added to docs/cli.md.
• Unit tests in tests/scripts/test_annotate_proteome_hits.py covering modification stripping, short-peptide filtering, the cross-protein separator guarantee, residue token counting edge cases, and a full folder round-trip.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	0	0	100%
data_types.py	4	0	100%
calibration
__init__.py	0	0	100%
calibration_features.py	9	0	100%
calibrator.py	102	11	89%	69–70, 72, 107, 134–135, 137, 163, 168, 195–196
diagnostics.py	168	50	70%	70, 96, 101, 111, 115, 137, 146, 203–218, 261–262, 266, 307, 309–324, 335–341
calibration/features
__init__.py	10	0	100%
base.py	8	0	100%
beam.py	47	0	100%
chimeric.py	82	1	98%	213
constants.py	9	0	100%
fragment_match.py	78	1	98%	203
mass_error.py	67	2	97%	16, 20
retention_time.py	135	9	93%	183, 190, 206, 257–259, 269, 272–273
sequence.py	19	0	100%
token_score.py	37	1	97%	82
utils.py	261	3	98%	96, 368, 594
compat
__init__.py	0	0	100%
instanovo.py	10	6	40%	12, 14–15, 17, 24–25
datasets
__init__.py	0	0	100%
calibration_dataset.py	109	17	84%	155, 169, 171, 173, 183, 196, 249, 251–252, 258–261, 263–266
interfaces.py	3	0	100%
psm_dataset.py	25	0	100%
datasets/data_loaders
__init__.py	5	0	100%
instanovo.py	119	19	84%	90, 93, 119, 142, 168–169, 172–174, 176–177, 179, 182–183, 185, 343–345, 356
mztab.py	215	55	74%	103, 106, 157, 161, 210–211, 223, 236–240, 287, 290, 302–303, 315–317, 319–320, 322, 324, 330, 334–336, 338–339, 343–346, 350, 514–515, 518, 521, 528, 542–546, 550–555, 561, 570–571, 573, 599
pointnovo.py	7	0	100%
utils.py	59	1	98%	11
winnow.py	39	4	89%	54–55, 91–92
fdr
__init__.py	0	0	100%
base.py	58	15	74%	81, 85–86, 91, 98–99, 105, 126, 129–130, 135, 137–138, 144, 186
database_grounded.py	27	1	96%	54
nonparametric.py	25	4	84%	62, 68–69, 72
scripts
__init__.py	0	0	100%
annotate_proteome_hits.py	110	12	89%	33, 40, 53, 63, 68, 72, 103, 151, 153, 157, 159, 172
main.py	279	279	0%	8, 10–14, 17–21, 24–25, 27–29, 33, 40, 45, 48, 54, 56–57, 60, 69, 77, 80, 87, 89–91, 93, 95–100, 103, 105–106, 111, 126, 129, 136–142, 145–146, 149, 162–164, 167, 170, 175, 177–179, 181, 183–184, 187–188, 191, 193–194, 196, 198, 200–201, 203, 206–207, 210–211, 214–215, 218–220, 222–225, 228–230, 232, 235, 249–251, 253, 255, 260, 262–264, 266–267, 269, 271–272, 274–276, 278, 280, 282–283, 287–290, 292–293, 295–296, 298–299, 301, 304, 318–320, 323, 326, 331, 333–335, 337–339, 341–342, 345–346, 349, 351–352, 354, 356, 358–359, 361, 364–365, 371–373, 375–378, 381–382, 385–386, 389–390, 393–394, 402–404, 408, 411, 415, 418, 424–426, 428–429, 436–437, 439, 441, 446, 448–450, 452–453, 456, 458–459, 461–464, 466–467, 469–470, 472–474, 480–481, 485–486, 489, 496, 501–502, 507–509, 512, 517, 527, 534, 536, 540, 542–543, 547–548, 551, 574, 587–588, 591, 613, 625–626, 629, 654, 667–668, 671, 686, 698–699, 702, 704–707, 710, 725, 729, 731–732, 737, 739–741, 747–748, 754–756, 765, 777, 812, 820, 835, 847–848, 851, 863, 875–876, 879, 894, 906–907, 910, 919, 931–932
utils
__init__.py	4	0	100%
config_formatter.py	53	40	24%	29, 37–38, 40–42, 44, 55, 58–60, 62–63, 66–69, 72–74, 77–78, 80, 91, 102, 113, 127–128, 130–132, 145–147, 150, 153–154, 157–158, 160
config_path.py	76	5	93%	24–26, 117–118
peptide.py	16	0	100%
TOTAL	2275	536	76%

Tests	Skipped	Failures	Errors	Time
442	0 💤	0 ❌	0 🔥	37.933s ⏱️