Select proteoform candidates by the most abundant isotopic peak

[trishorts]

Summary

Adds an opt-in PrecursorMassMatchMode (default Monoisotopic) that, when set to MostAbundant, selects top-down candidates by matching the observed most abundant isotopic peak against each candidate's theoretical apex (exact monoisotopic + averagine offset), instead of the inferred monoisotopic mass. This directly removes the monoisotopic off-by-N errors that cap high-mass proteoform identification.

Why a notch set

A single tight-ppm point at the averagine-predicted apex under-identifies, because the predicted apex misses the experimental apex by ±1–2 neutrons (~67 ppm/neutron at 15 kDa). MostAbundantMassDiffAcceptor therefore emits a small notch set at apex + k·(13C−12C), k ∈ {−2..+2}, each at tight ppm, keeping FDR controlled per notch.

Changes

• PrecursorMassMatchMode enum; CommonParameters.PrecursorMassMatchMode (+ toml/clone/file-specific plumbing).
• Ms2ScanWithSpecificMass.PrecursorMassToMatch (defaults to PrecursorMass, which is left untouched for fragment math/error reporting).
• _GetMs2Scans selects the match mass from the envelope (most-abundant, or average if unresolved).
• New MostAbundantMassDiffAcceptor; SearchTask.GetMassDiffAcceptor returns it when enabled. Classic/Modern search route candidate selection through PrecursorMassToMatch.

Validation (yeast top-down, 1% FDR, pooled across all 24 fractions)

MostAbundant 326 proteoforms / 10,850 PSMs vs monoisotopic ±3-notch baseline 281 / 9,314 — +16.0% / +16.5%, using fewer notches (5 vs 7). Consistent at 8-fraction (+15.1%) and single-fraction scale.

Notes

• Depends on Expose the most-abundant observed mass on IsotopicEnvelope (resolved) mzLib#1078 (most-abundant/average envelope masses + averagine offsets). Draft until that merges and a mzLib release is available; the mzLib PackageReference version here is a local build and must be bumped to the released version before merge.
• Centroid-mass path for isotopically unresolved (>35 kDa) species is plumbed but dormant pending an unresolved charge-determination algorithm (future work).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 90.74890% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.30%. Comparing base (3c8e0b8) to head (92e13e0).

Files with missing lines	Patch %	Lines
...er/PrecursorSearchModes/PrecursorMassExtensions.cs	77.77%	4 Missing and 2 partials ⚠️
...pheus/TaskLayer/CalibrationTask/CalibrationTask.cs	81.25%	0 Missing and 3 partials ⚠️
...cificEnzymeSearch/NonSpecificEnzymeSearchEngine.cs	50.00%	0 Missing and 2 partials ⚠️
...rsorSearchModes/MostAbundantDotMassDiffAcceptor.cs	94.44%	0 Missing and 2 partials ⚠️
...ecursorSearchModes/MostAbundantMassDiffAcceptor.cs	93.93%	0 Missing and 2 partials ⚠️
MetaMorpheus/TaskLayer/GPTMDTask/GPTMDTask.cs	71.42%	0 Missing and 2 partials ⚠️
MetaMorpheus/TaskLayer/SearchTask/SearchTask.cs	71.42%	0 Missing and 2 partials ⚠️
MetaMorpheus/EngineLayer/Gptmd/GptmdEngine.cs	92.85%	0 Missing and 1 partial ⚠️
MetaMorpheus/EngineLayer/SpectralMatch.cs	95.45%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master    #2671    +/-   ##
========================================
  Coverage   93.29%   93.30%            
========================================
  Files         196      199     +3     
  Lines       21320    21495   +175     
  Branches     3994     4037    +43     
========================================
+ Hits        19891    20055   +164     
  Misses        893      893            
- Partials      536      547    +11     

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

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

Files with missing lines	Coverage Δ
...ineLayer/Calibration/DataPointAcquisitionEngine.cs	97.53% <100.00%> (+0.01%)	⬆️
...ineLayer/Calibration/DataPointAquisitionResults.cs	100.00% <100.00%> (ø)
...s/EngineLayer/ClassicSearch/ClassicSearchEngine.cs	99.39% <100.00%> (ø)
MetaMorpheus/EngineLayer/CommonParameters.cs	99.52% <100.00%> (+1.95%)	⬆️
.../EngineLayer/HistogramAnalysis/BinTreeStructure.cs	88.16% <100.00%> (+0.14%)	⬆️
...eus/EngineLayer/Localization/LocalizationEngine.cs	96.82% <100.00%> (+0.15%)	⬆️
...eus/EngineLayer/ModernSearch/ModernSearchEngine.cs	77.72% <100.00%> (ø)
...etaMorpheus/EngineLayer/Ms2ScanWithSpecificMass.cs	95.74% <100.00%> (+0.14%)	⬆️
...Morpheus/EngineLayer/SpectrumMatch/PsmTsvWriter.cs	97.58% <100.00%> (+0.02%)	⬆️
...ons/ViewModels/Deconvolution/DeconHostViewModel.cs	100.00% <100.00%> (ø)
... and 11 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.

[nbollis]

My beef with this implementation is that the Ms2ScanWithSpecificMass and SpectralMatch representations depend upon the state of the search engine when they should be stateless for the search type being performed. The addition of these new properties introduces many potential bugs and sources of error.

For example, the localization engine calculates the mass difference based upon psm.ScanPrecursorMass and peptide.MonoisotpicMass. Now the localization engine will be wrong if we do a most abundant search because it will be comparing the scan most abundant and the peptide monoisotopic.

I am not sure what the solution is, but this has potential to cause a lot of bugs and confusion. Maybe something like having mono and avg mass as separate fields then the code that needs it will pick the correct one? Maybe a helper method that is GetPrecursorMass(bool isMostAbundant) in both ms2scanwithspecificmass and SpectralMatch. Maybe it's an extension method instead?

[trishorts]

This was the right call, and it was worse than you thought. Restructured across three commits (4102843, 0e4ba37, a9b0449) — full suite green, 1568/1568.

1. The representations are now stateless w.r.t. search type

PrecursorMassToMatch / ScanPrecursorMassToMatch are deleted. Ms2ScanWithSpecificMass and SpectralMatch carry only observations, populated identically in every search:

property	meaning
PrecursorMass	the deconvoluted monoisotopic mass — always, in every mode
PrecursorMostAbundantMass	the observed apex of the envelope (0 if none was deconvoluted)

PrecursorMass never changes meaning, so it can't be silently wrong. The search-type knowledge lives on the MassDiffAcceptor — the object that is the search type — and is reached by extension method, your suggestion #3:

scan.GetPrecursorMassForSearch(massDiffAcceptor)
psm.GetPrecursorMassForSearch(massDiffAcceptor)

GetMs2Scans no longer branches on the mode at all. Classic/Modern search and all three scan sorts go through the extension, so the sort key and the search key can't diverge.

2. Your localization example — inverted mechanism, real bug

Strictly, the mechanism you describe doesn't occur: ScanPrecursorMass stays monoisotopic in most-abundant mode, so LocalizationEngine is comparing scan-monoisotopic to peptide-monoisotopic.

But the conclusion is correct, for a sharper reason. Most-abundant matching deliberately accepts candidates whose deconvoluted monoisotopic peak is off by ±1–2 neutrons — that's the entire point of the apex notch set, and those PSMs are exactly the ones this feature exists to rescue. For them, ScanPrecursorMass - peptide.MonoisotopicMass ≈ k · 1.00335 Da. That is an isotope-assignment artifact, not chemistry — and three places were reading it as chemistry:

• LocalizationEngine:58 — localized a phantom ~1–2 Da modification onto a residue.
• GptmdEngine:104 — fed the same bogus difference into mod-candidate matching. This one is a bug we shipped in this PR, and you found it. Worse, MostAbundantDotMassDiffAcceptor carried a remark asserting the opposite — "downstream G-PTM-D mod assignment recomputes the modification from the monoisotopic precursor mass, so it is unaffected by this acceptor." That claim was the bug. Corrected in code and comment.
• DataPointAquisitionResults — counted it as m/z drift (the 1940 ppm runaway tolerance). This was the only one we'd found, and we'd patched it in place with the hardcoded C13MinusC12 you flagged above — i.e. we hit this bug class once, fixed the symptom, and missed that it was systemic. Your review is what surfaced that.

All three now go through one accessor:

public virtual double MassDiffAcceptor.ToObservedMonoisotopicMass(double observedPrecursorMass, double theoreticalMonoisotopicMass)

which undoes exactly the offsets the acceptor itself allowed (averagine apex offset + the k-neutron apex misprediction), using the isotope spacing it took from DeconvolutionParameters. It is the identity on every monoisotopic acceptor, so default-mode behaviour is unchanged bit-for-bit — the calibration/localization/G-PTM-D diffs are all "route through the acceptor," not "special-case most-abundant."

One design note: I did not use GetPrecursorMass(bool isMostAbundant). A bool at the call site is the same coupling in a thinner disguise — the caller still has to know which search it's in. Asking the acceptor means there's exactly one source of truth. It also turned out to be load-bearing for G-PTM-D: the Dot acceptor's notch encodes only the mass shift (all k share a notch, to preserve per-shift FDR grouping), so k can't be read back from the notch — the acceptor has to re-derive the (shift, k) pair itself, and only the acceptor knows its shift set.

3. Tests

New coverage for the observation/selection split, for ToObservedMonoisotopicMass across k = −2..+2 (asserting the mass difference collapses to ~0 rather than k·1.00335, and that a monoisotopic acceptor is the identity), and for the scan no longer changing shape with the mode.

The old calibration test was also replaced: it never exercised the path it claimed to — it built PSMs with no observed apex, so the "neutron stripping" it asserted was running on a fallback. It now builds a real apex observation plus a k-neutron misprediction, with a control asserting the same PSMs show a >50 ppm IQR when read without the acceptor, so the test proves the correction (not the fixture) is what tightens the spread.

[nbollis]

Love the direction this is going in. I beleive in most cases where the mass diff acceptor was added to the engine parameters (for the purpose of switching masses) we only need the enum in common params which is passed into all engines. Therefor if we make the extension methods operate upon the enum, we will not need the mass diff acceptor in the engines.

In addition, you should do a search for all .PrecurorMasses in the codebase for both Ms2scanWithSpecificMass as well as SpectralMatch. There are likely numerous locations to make the switch yet.

[nbollis]

It would be great if these could operate upon booleans and/or the new enum you created that is stored in common parameters. I think this would allow you to get away with not adding the mass diff accepter to all of the engines.

You could then pass the common params enum into the extension method to get the correct mass

[trishorts]

Done — the extensions now take CommonParameters and read PrecursorMassMatchMode (commit fe221b0).

You were right that this pays for itself: MassDiffAcceptor is back to untouched (the MatchesMostAbundantPeak and ToObservedMonoisotopicMass virtuals I added are deleted), and the acceptor parameter is gone from DataPointAcquisitionEngine, LocalizationEngine and GptmdEngine — all three already had CommonParameters, so those signatures return to exactly what they were.

Three methods, and which one you want depends on the question you're asking:

scan.GetPrecursorMassForSearch(commonParameters)       // which mass do we SELECT candidates with
psm.GetObservedMonoisotopicMass(theoretical, params)   // read a mass DIFFERENCE without the isotope offset
psm.MatchesCandidateMass(candidate, tol, params)       // does the observation support this candidate

One place the enum alone genuinely isn't enough, and I want you to sanity-check my reasoning: G-PTM-D.

GetObservedMonoisotopicMass recovers the k-neutron apex misprediction by rounding the residual to the nearest isotopologue. That is exact for calibration and localization because most-abundant mode always searches with the zero-centred apex acceptor — GetMassDiffAcceptor overrides the MassDiffAcceptorType in that mode — so the residual is k neutrons plus a within-tolerance ppm error and nothing else.

G-PTM-D breaks that invariant: it searches with discrete mass shifts, so the residual also contains an unknown modification mass. Round it and the modification gets folded into k and destroyed (a phospho at +79.966 would come back as ~-0.06 Da). The mod mass and the isotope offset land in the same residual and cannot be separated after the fact.

So G-PTM-D doesn't correct the precursor once — GetPossibleMods tests each candidate mass (peptide + modification) against the observation apex-to-apex via MatchesCandidateMass. That's the same acceptance rule as MostAbundantDotMassDiffAcceptor.Accepts, just expressed over the deconvolution parameters, so it still needs no acceptor. Its combo recursion now accumulates a candidate-mass offset rather than subtracting from the target mass — equivalent arithmetic, but it leaves the observed mass untouched so the apex test always sees what was actually measured.

New test pins it: a phosphorylated proteoform observed one neutron off its apex is still matched to phospho, and still not matched to oxidation.

MostAbundantMassDiffAcceptor.DefaultMaxApexOffsetNeutrons is now shared with the extensions, so the acceptor and the read-back can't drift apart on the k range.

[trishorts]

Both asks done — fe221b0 (production) and 92e13e0 (tests). Full suite green, 1569/1569.

1. Extensions operate on the enum; acceptor out of the engines

MassDiffAcceptor is back to untouched, and the acceptor parameter is removed from DataPointAcquisitionEngine, LocalizationEngine and GptmdEngine. Details and the one exception (G-PTM-D, which searches with discrete mass shifts, so the isotope offset can't be recovered by rounding) are in the thread reply above — worth a look, since that's the only place I didn't do exactly what you asked.

2. The audit — you were right, there were more

Swept every Ms2ScanWithSpecificMass.PrecursorMass and SpectralMatch.ScanPrecursorMass consumer. Three more sites were reading the wrong mass:

site	what was wrong
NonSpecificEnzymeSearchEngine:88, :128	Selected candidates off the raw monoisotopic mass — so non-specific search silently ignored most-abundant mode entirely.
BinTreeStructure:19, :97	Builds the mass-shift histogram from ScanPrecursorMass - peptideMonoisotopic. Same defect as localization: it would have grown spurious ~1 and ~2 Da bins that look like real modifications.
PSM ranking tie-breakers (CalibrationTask, NonSpecificEnzymeSearchEngine ×2)	Rank equal-scoring matches by precursor closeness. An isotope offset is not "closeness" — left in, a correct match with a 1-neutron apex misprediction ranks behind an inferior one.

Deliberately left on the monoisotopic mass — flagging these explicitly so you can push back rather than have it be silent:

• Fragment-bin / complementary-ion math (ModernSearchEngine, MetaMorpheusEngine.MatchFragmentIons). The monoisotopic mass is what that math means; the apex mass would be wrong there.
• All reporting and writing (PsmTsvWriter, PepXMLWriter, WriteXlFile, MetaDraw). The psmtsv Mass Diff column stays monoisotopic-vs-monoisotopic so it remains comparable across search modes, with the optional Most Abundant Mass Diff (ppm) column reported alongside it. Read together they separate the two error sources.
• Crosslink / glyco search. They build their own acceptors and don't expose this mode. Worth noting: if a user sets PrecursorMassMatchMode = MostAbundant in a toml and runs an XL or glyco task, it is currently a silent no-op. Happy to make that an explicit warning (or wire it up) if you'd rather — say the word and I'll do it in this PR.

3. Tests

MatchesCandidateMass_FindsModification_DespiteApexMisprediction is the new one worth reading — it's the case a rounding correction cannot handle. GetObservedMonoisotopicMass_RemovesApexAndNeutronOffsets (k = −2..+2) now also asserts that read raw, the same PSM shows a whole-neutron mass difference, so the phantom modification is pinned explicitly rather than just being absent.

[nbollis]

One question and one suggestion

[nbollis]

Why is this method needed if we have the special mass diff accepters?

[trishorts]

Fair question — they do compute the same test, so let me justify why the method exists rather than the acceptor.

MatchesCandidateMass and MostAbundantDotMassDiffAcceptor.Accepts are the same apex-to-apex arithmetic (candidate apex = mono + averagine offset; accept if the observed apex is within tolerance of apex + k·spacing for k in ±DefaultMaxApexOffsetNeutrons). It is deliberately not a second implementation — both go through the same AveragineApexOffset model and share DefaultMaxApexOffsetNeutrons.

The reason it's a method on the extensions and not just a call to .Accepts is your own round-2 request: take the MassDiffAcceptor back out of the engines and drive everything off CommonParameters. GptmdEngine.GetPossibleMods is inside that boundary. So the choice was:

1. thread the Dot acceptor back into GetPossibleMods purely so it can call .Accepts — which puts back exactly the coupling you asked me to remove, in the one engine where I couldn't use the rounding correction, or
2. express the same acceptance test over CommonParameters — which is MatchesCandidateMass.

I went with (2) so no engine holds an acceptor. If you'd rather GPTMD just take the MostAbundantDotMassDiffAcceptor and call .Accepts directly, I'm happy to switch — it's a wash on correctness, and it would delete MatchesCandidateMass. The tradeoff is purely "GPTMD carries an acceptor again" vs. "the apex test lives in one more small method." Your call; tell me which you prefer.

(One structural note in favour of keeping it off the acceptor: Accepts folds the candidate's shifts into its own shift set, whereas GetPossibleMods already enumerates each fully-formed candidate mass and just needs a yes/no on it. MatchesCandidateMass fits that caller exactly; routing through Accepts would mean constructing a Dot acceptor whose shift set is the single candidate, which is a stranger shape than the plain per-candidate test.)

[nbollis]

I guess I am confused why GPTMD specifically needed this correction but it is not needed elsewhere

[nbollis]

We should likely also write out the MostAbundantMass as a new column in addition to the mass error, but I will not hold up the PR on this

[trishorts]

Agreed, and I've teed up the mzLib half so we can do it right (owned by mzLib, not MM-local):

smith-chem-wisc/mzLib#1097 — adds the optional Precursor Most Abundant Mass psmtsv column to the reader/header. Same recipe as #1086 (which added Most Abundant Mass Diff (ppm)): optional, mapped by name, reads back null when absent, so old files are unaffected. The one difference from the error column is that this is an observation of the precursor envelope, not a per-hypothesis value — so it's one number per row and copies straight through disambiguation rather than being |-split.

Once #1097 releases, the MetaMorpheus side is the same pattern we used for the error column: PsmTsvWriter writes SpectralMatch.ScanPrecursorMostAbundantMass keyed by the mzLib header const, gated by the same includeMostAbundantColumn flag so normal output is unchanged. Since you said you won't hold up this PR on it, I'll add the MM writer change here once #1097 is merged/released, or as an immediate follow-up PR — whichever you prefer for merge sequencing.