Truncation search: follow-on task for N-/C-terminal proteoform truncations

[trishorts]

Truncation search: a follow-on task for proteoform N-/C-terminal truncations

Summary

Adds a new TruncationSearchTask that runs after a normal top-down search and discovers N- and C-terminally truncated proteoforms of the parents identified in that search. It is a standard MetaMorpheus task (run-list [Search, Truncation], dispatchable from CMD) with its own TOML schema and per-class FDR, and it writes results using the existing PSM/proteoform .psmtsv columns.

The task is self-contained and depends on no unreleased code — it builds against the current released mzLib and uses only standard MetaMorpheus/mzLib APIs (digestion, fragmentation, MatchFragmentIons/CalculatePeptideScore, FdrAnalysisEngine, the standard PSM writer). It works on either classic deconvolution or an external precursor source; nothing in the truncation code requires a particular precursor pipeline.

How it works (three passes)

1. Parents from the upstream search. The Search task deposits its resolved, FDR'd proteoform-level PSMs into a small TaskChainContext (in-memory hand-off; a disk AllProteoforms.psmtsv fallback also exists). The truncation task filters those to confident parents and expands pipe-ambiguous identifications into individual parents, then adds reverse decoys for any parent lacking one.
2. Pass 2 — candidate location. A fragment-bin index (N- and C-series of every parent) plus a truncation-aware mass acceptor locate candidate parents per scan; each candidate is scored twice with the standard scorer restricted to the N-series and to the C-series, and the highest (parent, series) wins. Scans already explained intact are skipped.
3. Pass 3 — chopping + scoring. The terminus opposite the winning series is chopped one-or-more residues until the truncated mass matches at an allowed notch; surviving mods are re-indexed onto the shorter form (with terminal-mod retention), both series are scored with the standard scorer, and duplicate truncations collapse into one ambiguous PSM. The truncation type (N-/C-terminal truncation(start-end)) rides the existing Description column, mirroring the existing chain(2-121) descriptors.

Intact PSMs are inherited as full-length, then everything is pooled into one per-class FDR/PEP pass and written to AllTruncatedPSMs.psmtsv / AllTruncatedProteoforms.psmtsv.

Additional pieces in this PR:

• SequenceTagExtractor / ProteinTagIndex — optional sequence-tag candidate restriction (tags emitted only for unambiguous residue gaps).
• InternalTruncationSearch / FragmentationPropensity — opt-in internal (both-ends) fragment search with a separate per-class FDR, plus a fragmentation-propensity scoring foundation.
• PerfLogger — opt-in perf_log.tsv metrics/timings (null path = no-op), for benchmarking.

Tests

66 NUnit tests covering the acceptor, the Pass 2 engine (dual-series scoring, parent filtering, oversized-parent handling, pipe-split, q-filter), the chopper (C/N chop, mod retention, collapse, notch), reverse-decoy generation, pooled FDR + output columns, sequence-tag extraction, fragmentation propensity, TOML round-trip / CMD dispatch, and an end-to-end [Search, Truncation] run that asserts well-formed output. Coverage on EngineLayer.Truncation.* is ~97% line. All 66 pass on the current master base.

Notes

• New MyTask.Truncation enum member; CMD/Program.cs dispatches Toml.ReadFile<TruncationSearchTask>.
• TaskChainContext is a generic deposit/retrieve slot assigned by EverythingRunnerEngine to every task before RunTask; the Search task's deposit is a no-op when no context is present.
• Also removes a stray committed VS hot-reload temp file (GUI_h05aw1sq_wpftmp.csproj).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 73 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.30%. Comparing base (3c8e0b8) to head (bc35c46).

Files with missing lines	Patch %	Lines
...Layer/TruncationSearchTask/TruncationSearchTask.cs	88.35%	15 Missing and 19 partials ⚠️
...s/EngineLayer/Truncation/TruncationSearchEngine.cs	95.57%	6 Missing and 6 partials ⚠️
MetaMorpheus/TaskLayer/PerfLogger.cs	89.18%	3 Missing and 5 partials ⚠️
...Morpheus/EngineLayer/Truncation/TruncationPass3.cs	93.10%	0 Missing and 4 partials ⚠️
MetaMorpheus/CMD/Program.cs	0.00%	3 Missing ⚠️
...Morpheus/EngineLayer/Truncation/ProteinTagIndex.cs	94.33%	2 Missing and 1 partial ⚠️
...EngineLayer/Truncation/InternalTruncationSearch.cs	97.91%	0 Missing and 2 partials ⚠️
...rpheus/EngineLayer/Truncation/ProteoformChopper.cs	96.96%	1 Missing and 1 partial ⚠️
...eus/EngineLayer/Truncation/SequenceTagExtractor.cs	95.65%	0 Missing and 2 partials ⚠️
.../EngineLayer/Truncation/FragmentationPropensity.cs	95.00%	0 Missing and 1 partial ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff            @@
##           master    #2666     +/-   ##
=========================================
  Coverage   93.29%   93.30%             
=========================================
  Files         196      212     +16     
  Lines       21320    22414   +1094     
  Branches     3994     4210    +216     
=========================================
+ Hits        19891    20913   +1022     
- Misses        893      923     +30     
- Partials      536      578     +42     

Flag	Coverage Δ
unittests	93.30% <93.33%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...pheus/EngineLayer/Truncation/TruncationAcceptor.cs	100.00% <100.00%> (ø)
...taMorpheus/EngineLayer/Truncation/TruncationFdr.cs	100.00% <100.00%> (ø)
...orpheus/EngineLayer/Truncation/TruncationOutput.cs	100.00% <100.00%> (ø)
.../EngineLayer/Truncation/TruncationParentBuilder.cs	100.00% <100.00%> (ø)
...rpheus/EngineLayer/Truncation/TruncationTimings.cs	100.00% <100.00%> (ø)
MetaMorpheus/TaskLayer/EverythingRunnerEngine.cs	71.60% <100.00%> (+0.71%)	⬆️
MetaMorpheus/TaskLayer/MetaMorpheusTask.cs	86.39% <100.00%> (+0.01%)	⬆️
...TruncationSearchTask/TruncationSearchParameters.cs	100.00% <100.00%> (ø)
.../EngineLayer/Truncation/FragmentationPropensity.cs	95.00% <95.00%> (ø)
MetaMorpheus/TaskLayer/SearchTask/SearchTask.cs	95.73% <66.66%> (-0.29%)	⬇️
... and 10 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[trishorts]

Manual unit-test review

Every unit test this PR adds was reviewed individually by the author, rather than relied on solely as automated/AI-generated checks. Of the 65 tests added:

• 55 were approved as written;
• 8 received explanatory doc-comments (the Met-excision / internal-fragment cases in TruncationChopperTests);
• 1 was strengthened (Acceptor_ProseString_DescribesRule now asserts the full acceptance rule, not just that the prose mentions "observed");
• 1 was removed as a tautology (Scaffolding_TestProjectWired, a leftover Assert.True placeholder that tested nothing) — leaving 64 retained.

This satisfies the author's standing AI-use policy that AI-assisted tests receive human review before being relied upon. Recorded 2026-06-22.

[pcruzparri]

K-LLM ensemble code review — 3 finding(s) at severity >= High, posted as inline comments.

All three share the same root cause: a single List<Product> is created outside a candidate loop and passed to PeptideWithSetModifications.Fragment(...), which appends without clearing, so MatchFragmentIons scores each candidate against an ever-growing union of fragments from all prior candidates. This inflates matched-ion counts and biases winner selection.

Method: 9 independent open-source LLM reviewers (Big Pickle, DeepSeek V4 Flash/Pro, MiMo-V2.5, Nemotron 3 Ultra, North Mini Code, Qwen 3.5/3.6 Plus, Kimi K2.6) each analyzed a differently-shuffled copy of this PR's diff. Findings were clustered by (file region, root cause), majority-voted, then validated against the PR branch source. 8/9 reviewers returned results; 3 findings survived validation.

All three are in code added by this PR. One reviewer (nemotron-3-ultra-free) returned empty output on two attempts; it is excluded from the vote denominator.

[trishorts]

Updated the branch and addressed the review:

• Merged current smith-chem-wisc/master into the branch (now current with master).
• Fixed all three K-LLM ensemble findings (the shared List<Product> accumulation root cause) in 3aafb51b: cleared the reused fragment list before each Fragment(...) call at the three sites — internal-span loop, Pass-2 N/C rescoring, and the fragment-index build. Per-comment replies inline.
• Truncation test suite green locally (76/76, Release/x64).

[trishorts]

Correction / follow-up on the K-LLM review: after verifying against the source and at runtime, all three findings are false positives, and I've reverted my earlier change (a9b35ac3).

The findings assumed PeptideWithSetModifications.Fragment(...) appends to the passed list. It does not — it calls products.Clear(); as its first line (mzLib PeptideWithSetModifications.cs:240), in the perf-critical path that is deliberately called once per candidate. Reusing a single List<Product> across candidates is therefore the intended, memory-efficient idiom; there is no cross-candidate accumulation and no score inflation. MatchFragmentIons is always invoked immediately after Fragment(...), so it only sees the current candidate's products.

Runtime check (mzLib 1.0.579): fragment parent A into a list → 79 products; fragment parent B into the same list → 29 (B's own count), not 108.

Net state of the branch: synced to current smith-chem-wisc/master; the three engine files are unchanged from their reviewed form; truncation test suite green locally (76/76, Release/x64). Marking the three threads resolved.