refactor(most-abundant): source isotope spacing from deconvolution params

Addresses @nbollis round-1 review on PR #2671.

- Replace the hardcoded Constants.C13MinusC12 in both most-abundant mass-diff
  acceptors with an ExpectedIsotopeSpacing arg, threaded from the existing
  DeconvolutionParameters.ExpectedIsotopeSpacing at every construction site
  (Calibration / GPTMD / Search). Removes the carbon-only spacing assumption
  the reviewer flagged for RNA/decoy runs; defaults to C13MinusC12 so no
  existing caller or test changes.
- Revert the unrelated GPTMD filter-serialization feature (GptmdFilterTypes /
  GetActiveFilters / CreateFilter / [TomlIgnore]) out of this PR to be
  resubmitted on its own branch. No property was renamed; the interface-typed
  GptmdFilters never round-tripped through Nett, so old tomls are unaffected.
- Expand the PrecursorMassToMatch doc to explain why it stays separate from the
  monoisotopic PrecursorMass (fragment-bin math and mass-error reporting remain
  monoisotopic-vs-monoisotopic, uncoupled from the per-notch apex offset).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: trishorts

MetaMorpheus/EngineLayer/Ms2ScanWithSpecificMass.cs

@@ -54,6 +54,14 @@ public Ms2ScanWithSpecificMass(MsDataScan mzLibScan, double precursorMonoisotopi
         /// The precursor mass used to select theoretical candidates via the <see cref="EngineLayer.MassDiffAcceptor"/>.
         /// Equals <see cref="PrecursorMass"/> in monoisotopic mode; in most-abundant mode it is the
         /// envelope's most-abundant (or average, if unresolved) observed neutral mass.
+        /// <para>
+        /// This is deliberately a separate property rather than an overwrite of <see cref="PrecursorMass"/>:
+        /// candidate selection is the only step that should key off the most-abundant peak. Fragment-bin
+        /// math and the reported precursor mass error must stay on the monoisotopic mass so that (a) the
+        /// error is the monoisotopic-vs-monoisotopic value comparable across search modes, and (b) it is
+        /// not conflated with the ±k-neutron apex offset the acceptor already models per-notch. Collapsing
+        /// the two would report error against a peak that is intentionally N neutrons off the monoisotopic.
+        /// </para>
         /// </summary>
         public double PrecursorMassToMatch { get; }
         public int PrecursorCharge { get; }

MetaMorpheus/EngineLayer/PrecursorSearchModes/MostAbundantDotMassDiffAcceptor.cs

@@ -33,14 +33,25 @@ public class MostAbundantDotMassDiffAcceptor : MassDiffAcceptor
         public int MaxApexOffsetNeutrons { get; }
         private readonly int[] ApexOffsetsInNeutrons;
 
+        /// <summary>
+        /// Mass spacing between adjacent isotopologues (the "+1 neutron" step) used to place the apex
+        /// notches. Sourced from the deconvolution's
+        /// <see cref="MassSpectrometry.DeconvolutionParameters.ExpectedIsotopeSpacing"/> so the acceptor
+        /// matches the spacing the envelope was built with — the C-13/C-12 difference for peptides/
+        /// proteoforms, but overridable for decoy runs (~0.9444 Da) or non-carbon-dominated polymers.
+        /// </summary>
+        private readonly double ExpectedIsotopeSpacing;
+
         public MostAbundantDotMassDiffAcceptor(string fileNameAddition, IEnumerable<double> acceptableMassShifts,
-            Tolerance tol, AverageResidue averagine, int maxApexOffsetNeutrons = 2) : base(fileNameAddition)
+            Tolerance tol, AverageResidue averagine, int maxApexOffsetNeutrons = 2,
+            double expectedIsotopeSpacing = Constants.C13MinusC12) : base(fileNameAddition)
         {
             Tolerance = tol;
             Averagine = averagine;
             SortedMassShifts = acceptableMassShifts.OrderBy(Math.Abs).ThenBy(p => p < 0).ToArray();
             ShiftNotches = SortedMassShifts.Select(s => (int)Math.Round(s * NotchScalar)).ToArray();
             MaxApexOffsetNeutrons = maxApexOffsetNeutrons;
+            ExpectedIsotopeSpacing = expectedIsotopeSpacing;
 
             var offsets = new List<int> { 0 };
             for (int k = 1; k <= maxApexOffsetNeutrons; k++) { offsets.Add(-k); offsets.Add(k); }
@@ -64,7 +75,7 @@ public override int Accepts(double scanPrecursorMass, double peptideMass)
                 double apex = shiftedMono + ApexOffset(shiftedMono);
                 foreach (int k in ApexOffsetsInNeutrons)
                 {
-                    if (Tolerance.Within(scanPrecursorMass, apex + k * Constants.C13MinusC12))
+                    if (Tolerance.Within(scanPrecursorMass, apex + k * ExpectedIsotopeSpacing))
                     {
                         return ShiftNotches[j];
                     }
@@ -81,7 +92,7 @@ public override IEnumerable<AllowedIntervalWithNotch> GetAllowedPrecursorMassInt
                 double apex = shiftedMono + ApexOffset(shiftedMono);
                 foreach (int k in ApexOffsetsInNeutrons)
                 {
-                    double mass = apex + k * Constants.C13MinusC12;
+                    double mass = apex + k * ExpectedIsotopeSpacing;
                     yield return new AllowedIntervalWithNotch(Tolerance.GetMinimumValue(mass), Tolerance.GetMaximumValue(mass), ShiftNotches[j]);
                 }
             }
@@ -96,7 +107,7 @@ public override IEnumerable<AllowedIntervalWithNotch> GetAllowedPrecursorMassInt
             {
                 foreach (int k in ApexOffsetsInNeutrons)
                 {
-                    double mass = monoApprox - SortedMassShifts[j] - k * Constants.C13MinusC12;
+                    double mass = monoApprox - SortedMassShifts[j] - k * ExpectedIsotopeSpacing;
                     yield return new AllowedIntervalWithNotch(Tolerance.GetMinimumValue(mass), Tolerance.GetMaximumValue(mass), ShiftNotches[j]);
                 }
             }

MetaMorpheus/EngineLayer/PrecursorSearchModes/MostAbundantMassDiffAcceptor.cs

@@ -23,7 +23,7 @@ namespace EngineLayer
     /// yeast top-down data: a single tight-ppm point at the predicted apex under-identifies badly,
     /// because one neutron is ~67 ppm at 15 kDa). To tolerate that apex misprediction while keeping
     /// each match at tight ppm (and FDR controlled per-notch), this acceptor emits a small set of
-    /// notches at <c>apex + k·C13</c> for k in [−<see cref="MaxApexOffsetNeutrons"/> ..
+    /// notches at <c>apex + k·<see cref="ExpectedIsotopeSpacing"/></c> for k in [−<see cref="MaxApexOffsetNeutrons"/> ..
     /// +<see cref="MaxApexOffsetNeutrons"/>]. k = 0 is the confident on-apex match; nonzero k are the
     /// apex-misprediction cases. Each k maps to a contiguous non-negative notch index (its 0-based
     /// position in the apex-offset set), so notches are distinct per k, are always ≥ 0 (a negative
@@ -42,18 +42,29 @@ public class MostAbundantMassDiffAcceptor : MassDiffAcceptor
         private readonly Tolerance Tolerance;
         private readonly AverageResidue Averagine;
 
+        /// <summary>
+        /// Mass spacing between adjacent isotopologues (the "+1 neutron" step) used to place the apex
+        /// notches. Sourced from the deconvolution's
+        /// <see cref="MassSpectrometry.DeconvolutionParameters.ExpectedIsotopeSpacing"/> so the acceptor
+        /// matches the spacing the envelope was built with — the C-13/C-12 difference for peptides/
+        /// proteoforms, but overridable for decoy runs (~0.9444 Da) or non-carbon-dominated polymers.
+        /// </summary>
+        private readonly double ExpectedIsotopeSpacing;
+
         /// <summary>Maximum apex misprediction, in neutrons, tolerated on either side of the averagine-predicted apex.</summary>
         public int MaxApexOffsetNeutrons { get; }
 
         // k values ordered by ascending |k| (then sign) so the on-apex (k = 0) match is preferred.
         private readonly int[] ApexOffsetsInNeutrons;
 
-        public MostAbundantMassDiffAcceptor(string fileNameAddition, Tolerance tol, AverageResidue averagine, int maxApexOffsetNeutrons = 2)
+        public MostAbundantMassDiffAcceptor(string fileNameAddition, Tolerance tol, AverageResidue averagine, int maxApexOffsetNeutrons = 2,
+            double expectedIsotopeSpacing = Constants.C13MinusC12)
             : base(fileNameAddition)
         {
             Tolerance = tol;
             Averagine = averagine;
             MaxApexOffsetNeutrons = maxApexOffsetNeutrons;
+            ExpectedIsotopeSpacing = expectedIsotopeSpacing;
 
             var offsets = new List<int> { 0 };
             for (int k = 1; k <= maxApexOffsetNeutrons; k++)
@@ -80,7 +91,7 @@ public override int Accepts(double scanPrecursorMass, double peptideMass)
             double apex = peptideMass + ApexOffset(peptideMass);
             foreach (int k in ApexOffsetsInNeutrons) // ordered to prefer k = 0
             {
-                if (Tolerance.Within(scanPrecursorMass, apex + k * Constants.C13MinusC12))
+                if (Tolerance.Within(scanPrecursorMass, apex + k * ExpectedIsotopeSpacing))
                 {
                     return NotchFor(k);
                 }
@@ -93,7 +104,7 @@ public override IEnumerable<AllowedIntervalWithNotch> GetAllowedPrecursorMassInt
             double apex = peptideMonoisotopicMass + ApexOffset(peptideMonoisotopicMass);
             foreach (int k in ApexOffsetsInNeutrons)
             {
-                double mass = apex + k * Constants.C13MinusC12;
+                double mass = apex + k * ExpectedIsotopeSpacing;
                 yield return new AllowedIntervalWithNotch(Tolerance.GetMinimumValue(mass), Tolerance.GetMaximumValue(mass), NotchFor(k));
             }
         }
@@ -108,7 +119,7 @@ public override IEnumerable<AllowedIntervalWithNotch> GetAllowedPrecursorMassInt
             double monoApprox = observedMostAbundantMass - ApexOffset(observedMostAbundantMass);
             foreach (int k in ApexOffsetsInNeutrons)
             {
-                double mass = monoApprox - k * Constants.C13MinusC12;
+                double mass = monoApprox - k * ExpectedIsotopeSpacing;
                 yield return new AllowedIntervalWithNotch(Tolerance.GetMinimumValue(mass), Tolerance.GetMaximumValue(mass), NotchFor(k));
             }
         }

MetaMorpheus/GUI/TaskWindows/GPTMDTaskWindow.xaml.cs

@@ -212,8 +212,7 @@ private void UpdateFieldsFromTask(GptmdTask task)
 
             foreach (var filter in FilterOptions)
             {
-                filter.IsSelected = (TheTask.GptmdParameters.GptmdFilters?.Any(f => f.GetType() == filter.Filter.GetType()) ?? false)
-                    || (TheTask.GptmdParameters.GptmdFilterTypes?.Contains(filter.Filter.GetType().Name) ?? false);
+                filter.IsSelected = TheTask.GptmdParameters.GptmdFilters.Any(f => f.GetType() == filter.Filter.GetType());
             }
         }
 
@@ -588,8 +587,6 @@ private void SaveButton_Click(object sender, RoutedEventArgs e)
                 TheTask.GptmdParameters.ListOfModsGptmd.AddRange(heh.Children.Where(b => b.Use).Select(b => (b.Parent.DisplayName, b.ModName)));
             }
             TheTask.GptmdParameters.GptmdFilters = FilterOptions.Where(f => f.IsSelected).Select(f => f.Filter).ToList();
-            // Also persist the selection in toml-serializable form so it survives a save/load round-trip and CMD runs.
-            TheTask.GptmdParameters.GptmdFilterTypes = FilterOptions.Where(f => f.IsSelected).Select(f => f.Filter.GetType().Name).ToList();
             TheTask.GptmdParameters.WriteDecoys = WriteDecoysCheckBox.IsChecked.Value;
             TheTask.CommonParameters = commonParamsToSave;
 

MetaMorpheus/TaskLayer/CalibrationTask/CalibrationTask.cs

@@ -209,7 +209,8 @@ private DataPointAquisitionResults GetDataAcquisitionResults(MsDataFile myMsData
                 && combinedParameters.DoPrecursorDeconvolution)
             {
                 searchMode = new MostAbundantMassDiffAcceptor("mostAbundant", combinedParameters.PrecursorMassTolerance,
-                    combinedParameters.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine());
+                    combinedParameters.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine(),
+                    expectedIsotopeSpacing: combinedParameters.PrecursorDeconvolutionParameters?.ExpectedIsotopeSpacing ?? Chemistry.Constants.C13MinusC12);
             }
             else
             {

MetaMorpheus/TaskLayer/GPTMDTask/GPTMDParameters.cs

@@ -1,7 +1,6 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Linq;
 using EngineLayer.Gptmd;
-using Nett;
 
 namespace EngineLayer
 {
@@ -13,60 +12,16 @@ public class GptmdParameters
         public GptmdParameters()
         {
             GptmdFilters = new();
-            GptmdFilterTypes = new();
             ListOfModsGptmd = GlobalVariables.AllModsKnown.Where(b =>
                 b.ModificationType.Equals("Common Artifact")
                 || b.ModificationType.Equals("Common Biological")
-                || b.ModificationType.Equals("Metal")
+                || b.ModificationType.Equals("Metal") 
                 //|| b.ModificationType.Equals("Less Common")
             ).Select(b => (b.ModificationType, b.IdWithMotif)).ToList();
         }
 
         public List<(string, string)> ListOfModsGptmd { get; set; }
-
-        /// <summary>
-        /// Runtime list of G-PTM-D acceptance filters (e.g. <see cref="ImprovedScoreFilter"/>). This is a
-        /// list of interface instances and cannot round-trip through the task toml; the toml-serializable
-        /// representation is <see cref="GptmdFilterTypes"/>. The GUI sets this directly for in-memory runs.
-        /// Use <see cref="GetActiveFilters"/> to obtain the effective set (this list plus any named in the toml).
-        /// </summary>
-        [TomlIgnore]
-        public List<IGptmdFilter> GptmdFilters { get; set; }
-
-        /// <summary>
-        /// Toml-serializable filter selection by type name (e.g. "ImprovedScoreFilter"). Lets headless/CMD
-        /// runs enable G-PTM-D acceptance filters that previously could only be set in the GUI. A common
-        /// choice is "ImprovedScoreFilter", which only adds a modification when it improves the match score
-        /// (greatly reducing the number of modifications added).
-        /// </summary>
-        public List<string> GptmdFilterTypes { get; set; }
-
+        public List<IGptmdFilter> GptmdFilters { get; set; } 
         public bool WriteDecoys { get; set; } = true;
-
-        /// <summary>
-        /// The effective filter set: the in-memory <see cref="GptmdFilters"/> plus any filters named in
-        /// <see cref="GptmdFilterTypes"/> (deduplicated by type). Unknown names are ignored.
-        /// </summary>
-        public List<IGptmdFilter> GetActiveFilters()
-        {
-            var active = new List<IGptmdFilter>(GptmdFilters ?? new List<IGptmdFilter>());
-            foreach (var name in GptmdFilterTypes ?? new List<string>())
-            {
-                var filter = CreateFilter(name);
-                if (filter != null && active.All(f => f.GetType() != filter.GetType()))
-                    active.Add(filter);
-            }
-            return active;
-        }
-
-        /// <summary>Creates a filter instance from its type name; returns null for an unrecognized name.</summary>
-        public static IGptmdFilter CreateFilter(string typeName) => typeName switch
-        {
-            nameof(ImprovedScoreFilter) => new ImprovedScoreFilter(),
-            nameof(DualDirectionalIonCoverageFilter) => new DualDirectionalIonCoverageFilter(),
-            nameof(UniDirectionalIonCoverageFilter) => new UniDirectionalIonCoverageFilter(),
-            nameof(FlankingIonCoverageFilter) => new FlankingIonCoverageFilter(),
-            _ => null
-        };
     }
-}
+}

MetaMorpheus/TaskLayer/GPTMDTask/GPTMDTask.cs

@@ -81,7 +81,7 @@ protected override MyTaskResults RunSpecific(string OutputFolder, List<DbForTask
             // temporary search type for writing prose
             // the actual search type is technically file-specific but we don't allow file-specific notches, so it's safe to do this
             MassDiffAcceptor tempSearchMode = CommonParameters.PrecursorMassMatchMode == PrecursorMassMatchMode.MostAbundant
-                ? new MostAbundantDotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), CommonParameters.PrecursorMassTolerance, CommonParameters.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine())
+                ? new MostAbundantDotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), CommonParameters.PrecursorMassTolerance, CommonParameters.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine(), expectedIsotopeSpacing: CommonParameters.PrecursorDeconvolutionParameters?.ExpectedIsotopeSpacing ?? Chemistry.Constants.C13MinusC12)
                 : new DotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), CommonParameters.PrecursorMassTolerance);
             ProseCreatedWhileRunning.Append("precursor mass tolerance(s) = {" + tempSearchMode.ToProseString() + "}; ");
 
@@ -116,7 +116,7 @@ protected override MyTaskResults RunSpecific(string OutputFolder, List<DbForTask
 
                 CommonParameters combinedParams = SetAllFileSpecificCommonParams(CommonParameters, fileSettingsList[spectraFileIndex]);
                 MassDiffAcceptor searchMode = combinedParams.PrecursorMassMatchMode == PrecursorMassMatchMode.MostAbundant
-                    ? new MostAbundantDotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), combinedParams.PrecursorMassTolerance, combinedParams.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine())
+                    ? new MostAbundantDotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), combinedParams.PrecursorMassTolerance, combinedParams.PrecursorDeconvolutionParameters?.AverageResidueModel ?? new Averagine(), expectedIsotopeSpacing: combinedParams.PrecursorDeconvolutionParameters?.ExpectedIsotopeSpacing ?? Chemistry.Constants.C13MinusC12)
                     : new DotMassDiffAcceptor("", GetAcceptableMassShifts(fixedModifications, variableModifications, gptmdModifications, combos), combinedParams.PrecursorMassTolerance);
 
                 NewCollection(Path.GetFileName(origDataFile), new List<string> { taskId, "Individual Spectra Files", origDataFile });
@@ -177,7 +177,7 @@ protected override MyTaskResults RunSpecific(string OutputFolder, List<DbForTask
             // GPTMD doesn't work as well if you do FDR on a file-by-file basis. Presumably this is because it takes multiple files to get enough PSMs for all the different notches
             new FdrAnalysisEngine(allPsms, tempSearchMode.NumNotches, CommonParameters, this.FileSpecificParameters, new List<string> { taskId }, doPEP: false).Run();
             Dictionary<string, HashSet<Tuple<int, Modification>>> allModDictionary = new();
-            new GptmdEngine(allPsms, gptmdModifications, combos, filePathToPrecursorMassTolerance, CommonParameters, this.FileSpecificParameters, new List<string> { taskId }, allModDictionary, GptmdParameters.GetActiveFilters()).Run();
+            new GptmdEngine(allPsms, gptmdModifications, combos, filePathToPrecursorMassTolerance, CommonParameters, this.FileSpecificParameters, new List<string> { taskId }, allModDictionary, GptmdParameters.GptmdFilters).Run();
 
             //Move this text after search because proteins don't get loaded until search begins.
             ProseCreatedWhileRunning.Append("The combined search database contained " + proteinList.Count(p => !p.IsDecoy) + $" non-decoy {GlobalVariables.AnalyteType.GetBioPolymerLabel().ToLower()} entries including " + proteinList.Count(p => p.IsContaminant) + " contaminant sequences. ");