Opt-in: treat a cleavage-blocking modification as abolishing its cleavage site (Modification.BlocksCleavage)

[trishorts]

Trypsin cannot cleave after an acylated lysine. Digestion applies modifications after cleavage, so nothing checked whether a modification abolished the very site a peptide was cut at — and PEPTIDEK[acetyl] was reported as a clean, zero-missed-cleavage tryptic peptide describing an event that cannot occur, while the real peptide (PEPTIDEK[acetyl]AAAAAAAR, reading through the blocked site) was scored as a missed cleavage and often not generated at all.

This PR adds Modification.BlocksCleavage and an opt-in DigestionParams.RespectCleavageBlockingModifications. Default is false, which reproduces historical digestion exactly.

What it does

With the flag on, in a full-specificity search, digestion performs a trade:

Protein AAAAAARPEPTKPEPTRAAAAAAK, acetyl-K variable, maxMissedCleavages: 0

flag OFF                          flag ON
  PEPTK                             PEPTK
  PEPTK[Acetyl]      <- impossible  PEPTK[Acetyl]PEPTR   <- the real peptide, MC=0
  PEPTR                             PEPTR

The impossible peptidoform leaves and the read-through that replaces it arrives, so the peptide stays identifiable. Both halves matter, and they are deliberately coupled — see Scope below.

Three pieces make that work:

1. Modification.BlocksCleavage — classifies a modification as abolishing its cleavage site. Only side-chain (Anywhere.) acylations on K, and citrullination on R, qualify. Charge is the criterion: acylation removes the ε-amine's positive charge, so trypsin cannot cleave; methylation retains it and is therefore excluded (it is a genuine missed cleavage, not an impossible peptide). N-terminal α-amine acetylation on K is correctly not blocking — the side chain stays charged.
2. The C-terminal drop — a peptidoform whose C-terminal residue carries a blocking modification, where that C-terminus is an internal protease cut, is dropped. A peptide ending at the protein's own C-terminus is exempt: no cleavage happened there for a modification to block.
3. Missed cleavages count cleavage events, not residues — a blocked residue is not a cleavage site for the peptidoform carrying it, so it is not a missed cleavage either. Digestion enumerates a wider span internally to reach read-through forms, but that slack is discounted again before a peptide is emitted, so MaxMissedCleavages keeps its meaning: no peptide leaves digestion reporting more missed cleavages than the caller asked for.

Scope: what is and is not in this PR

In scope — full-specificity searches only (SearchModeType == CleavageSpecificity.Full).

Explicitly out of scope — semi-specific and nonspecific searches are left entirely untouched, and that is a deliberate design decision rather than an oversight.

The drop and the wider generation span are two halves of one exchange. The slack is granted only in a full search, so applying the drop outside one performs half the trade. Measured, flag off vs on:

mode	maxMC	dropped	added	net
Full	0	PEPTK[Acetyl]	PEPTK[Acetyl]PEPTR	6 → 6
Semi	0	PEPTK[Acetyl]	(none)	6 → 5

In the semi case the peptide becomes unidentifiable — the wrong answer is removed and the right one never generated. That is strictly worse than leaving it alone, so the drop now requires SearchModeType == Full too. It would have bitten whenever the read-through needs more budget than MaxMissedCleavages allows: one blocked site at 0, three consecutive at 2.

Making semi searches benefit properly is follow-up work, and it is not simply widening that gate. A semi peptide's C-terminus may be a genuine protease cut or a length-driven truncation, and telling them apart requires the protease's cleavage-site list — which full digestion gets free from its own enumeration and semi digestion does not.

Known limitations, carried knowingly

• The classifier is name-keyed. BlocksCleavage matches acyl stems in the modification's name. Broader Unimod coverage and the bluntness of the methyl exclusion are curation refinements. A user-declarable blocking flag persisted in the custom-modification .txt (the BM/BL precedent) is the real upgrade path.
• Blocked internal sites are counted without re-deriving the protease's site list. A modified K or R that was never a cleavage site under the configured protease can discount a missed cleavage it did not occupy. Harmless for trypsin (K|,R|, which cleaves unconditionally); untested for context-restricted proteases such as trypsin|P. The count is clamped so it cannot go negative, and the C-terminal drop is exact.
• Fixed blocking modifications remain an unbounded edge: the generation slack is tied to MaxMods, which bounds variable modifications only.
• Truncation-product ends beyond the protein C-terminus are not exempted from the drop.
• BlocksCleavage recomputes on each access (lowercases and scans the name) rather than caching.
• Not exposed to MetaMorpheus. The flag is a DigestionParams constructor parameter only; it is not on IDigestionParams, has no RNA equivalent, and MetaMorpheus has zero references to it, so every MM path takes the false default. Surfacing it needs GUI plumbing and a check that the flag survives the DigestionParameters.toml round-trip through Nett given its private setter.

Review history

Round 2 (02bce317) fixed five real correctness bugs found in a second review pass: N-terminal α-amine acetylation on K misclassified as blocking; Clone() dropping the flag on its non-None path; Digestion() bypassing the mutable missed-cleavage property; a fixed slack of 2 losing peptides when more than two sites were blocked (now MaxMods); and the C-terminal drop firing on non-cut termini.

Round 3 — this round, from @nbollis's two review comments, seconded by @Alexander-Sol:

• "the number of missed cleavages we get out of digestion may or may not match our digestion parameters" — confirmed and fixed. At maxMissedCleavages: 0 the emitted peptides reported < 0, 0, 1 >. The filter was already computing the blocked-discounted count to decide survival, but the peptide was still constructed with the modification-blind count, so the generation slack leaked out. The discounted count is now what the surviving peptidoform carries — which is the alternative both reviewers proposed.
• "Cleavage specificity == Full will prevent this from working in nonspecific and semi-specific searches, is that intended?" — tested, and it was worse than intended. It was not inert in semi searches, it was half-applied; see the table above. Now genuinely confined to full searches, with the reasoning documented at the gate.

Tests

New this round, each verified red against the previous source:

• ReadThroughOfABlockedSite_ReportsZeroMissedCleavages_NotOne — was 1, now 0.
• NoEmittedPeptide_EverReportsMoreMissedCleavagesThanRequested(0/1/2) — was < 0, 0, 1 > at a requested max of 0.
• SemiSpecificSearch_IsEntirelyUnaffectedByTheFlag(0/1/2) — fails on all three budgets without the new gate. This replaces SemiSpecific_NonFullPeptides_AreUnaffectedByTheFlag, which compared only the non-Full subset of a semi digest and therefore stayed green while the Full peptides inside that digest were being dropped unreplaced.
• AnUnblockedMissedCleavage_StillCountsWithTheFlagOn and FullSearch_TradesTheImpossibleFormForTheReadThrough — guard the opposite direction, so the fix cannot degrade into blanket zeroing or into dropping without replacing.

Plus the round-2 regressions: citrulline-on-R-only, Clone preserving the flag on both paths, a blocked residue at the protein C-terminus surviving, and a three-blocked-site read-through surviving at 0 missed cleavages.

Full offline suite: 5333 passed, 0 failed.

Note on CI: external-service-tests is red on this branch, inherited from master — it has been failing since 2026-07-30 on the commit that added GetProjectFilesFromFtp_LivePxd000001_IsMoreCompleteThanTheRestManifest (#1121). EBI's FTP is unreachable from GitHub runners, and because the walk returns an empty list rather than throwing, ExternalServiceTestHelper cannot classify it as an outage and it fails instead of skipping. Unrelated to this PR.

[codecov]

Codecov Report

❌ Patch coverage is 86.66667% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.53%. Comparing base (22441e1) to head (a30851e).

Files with missing lines	Patch %	Lines
...ics/Modifications/CleavageBlockingModifications.cs	75.00%	2 Missing and 4 partials ⚠️
...teomics/ProteolyticDigestion/ProteolyticPeptide.cs	87.87%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1119      +/-   ##
==========================================
- Coverage   91.53%   91.53%   -0.01%     
==========================================
  Files         445      446       +1     
  Lines       53848    53916      +68     
  Branches     6570     6586      +16     
==========================================
+ Hits        49292    49350      +58     
- Misses       3277     3281       +4     
- Partials     1279     1285       +6     

Files with missing lines	Coverage Δ
mzLib/Omics/Modifications/Modification.cs	97.09% <100.00%> (+0.01%)	⬆️
...Proteomics/ProteolyticDigestion/DigestionParams.cs	99.08% <100.00%> (+0.07%)	⬆️
...roteomics/ProteolyticDigestion/ProteinDigestion.cs	95.26% <100.00%> (+0.08%)	⬆️
...teomics/ProteolyticDigestion/ProteolyticPeptide.cs	94.20% <87.87%> (-5.80%)	⬇️
...ics/Modifications/CleavageBlockingModifications.cs	75.00% <75.00%> (ø)

🚀 New features to boost your workflow:

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

[nbollis]

This concerns me. It means that if we are doing the new mod blocking missed cleavages, then the number of missed cleavages we get out of digestion may or may not match our digestion parameters. This feels bad.

Is this second property needed? An alternative approach would be to treat the mod blocking the cleavage, say acetyl lysine, as not a cleavage site and not considered for the missed cleavage count.

[Alexander-Sol]

I agree with Nic's assessment

[trishorts]

i'm going to look into this but i it seems to me that a blocked cleavage is not a missed cleavage. It's not cleavable. we are reporting cleavages, not lysines.

[nbollis]

Cleavage specificity == Full will prevent this from working in nonspecific and semi-specific searches, is that intended?

[trishorts]

Follow-up commit 02bce317 — round-2 review caught five real correctness bugs; all fixed

A second /review-pr pass returned Request changes with 8 Major findings, and it was right — five were genuine correctness bugs in the first commit, not test nits. Writing them up plainly:

1. N-terminal α-amine acetylation on K was misclassified as blocking. The classifier decided from target motif + name substring and never looked at LocationRestriction. UniProt ships both N6-acetyllysine (ε-amine side chain, genuinely blocking, Anywhere.) and N-acetyllysine (α-amine, N-terminal.) — the terminal form leaves the side chain charged, so trypsin still cleaves, yet both matched. Fix: only side-chain (Anywhere.) modifications classify.

2. Clone() dropped the flag on the non-None path. The flag was passed on only the None-specificity return, so a cloned DigestionParams silently reverted to modification-blind digestion for every other mode (and compared unequal to its source). Fix: both paths pass it.

3. Digestion() bypassed the mutable missed-cleavage property. It read EffectiveMaxMissedCleavages off DigestionParams instead of the MaximumMissedCleavages instance property that SpeedySemiSpecificDigestion also reads, so a caller mutating that property had the mutation silently discarded — even flag-off. Fix: removed EffectiveMaxMissedCleavages; the budget is computed from MaximumMissedCleavages, so flag-off is byte-for-byte the historical path.

4. Slack of 2 lost real peptides when >2 sites were blocked. With three blocked K's in a row, the read-through spanning them was never generated while the shorter forms were still dropped — the peptide vanished. Fix: slack is now MaxMods (a peptidoform carries at most that many variable mods, hence blocked sites, so every variable-mod read-through is reachable). Fixed blocking mods remain a documented unbounded edge.

5. The C-terminal drop fired on non-cut termini. It ignored specificity, so semi- and single-terminus peptides whose C-terminus is a length truncation were wrongly dropped — my "exact, all modes" claim was false. Fix: gated on CleavageSpecificityForFdrCategory == Full, matching where the slack applies.

Also corrected: arginine is now reachable and right — the previously-dead R branch classifies citrullination (deimination removes Arg's charge → trypsin doesn't cleave); and the BlocksCleavage doc no longer claims a terminal acylated residue is an impossible peptide end (it's a real one — position is digestion's call).

New regression tests pin each fix: citrulline-on-R-only, Clone preserves the flag on both paths, a blocked residue at the protein C-terminus survives, semi non-Full peptides are untouched by the flag, and a three-blocked-site read-through survives at 0 missed cleavages with slack = MaxMods. The residue and location gates are now exercised (a blocking name on a non-cleavage residue; an N-terminal-K), and "reproduces historical behaviour" pins concrete pre-PR output plus that the impossible form is kept — instead of comparing two flag-off runs.

Deferred, and raised here honestly for a follow-up (all Minor):

• The surviving read-through still reports the modification-blind MissedCleavages count (the blocked site "isn't a cut" but the stored count doesn't reflect that). Recomputing it per-peptidoform is a deeper change.
• Truncation-product ends beyond the protein C-terminus aren't exempted from the drop.
• BlocksCleavage recomputes (lowercases + scans the name) on each access rather than caching.
• The name-keyed acyl-stem classifier is inherently a heuristic; broader Unimod coverage and the contains("methyl") bluntness are curation refinements. The persisted-custom-.txt-field path (BM/BL precedent) remains the upgrade for user-declarable blocking mods.

Full suite: 5343 passed, 0 failed.

This is exactly why the second review pass is worth running — same as #1102, the round-1 hardening had bugs a first review of the original PR could not have seen.