Select proteoform candidates by the most abundant isotopic peak

MetaMorpheus/CMD/CMD.csproj

@@ -24,7 +24,7 @@
     <PackageReference Include="Microsoft.ML.CpuMath" Version="3.0.1" />
     <PackageReference Include="Microsoft.ML.FastTree" Version="3.0.1" />
     <PackageReference Include="Microsoft.NETCore.App" Version="2.2.8" />
-    <PackageReference Include="mzLib" Version="1.0.579" />
+    <PackageReference Include="mzLib" Version="1.0.581" />
     <PackageReference Include="Nett" Version="0.15.0" />
     <PackageReference Include="SQLite.Interop.dll" Version="1.0.103" />
     <PackageReference Include="System.Data.SQLite" Version="1.0.118" />

MetaMorpheus/EngineLayer/Calibration/DataPointAcquisitionEngine.cs

@@ -113,7 +113,8 @@ protected override MetaMorpheusEngineResults RunSpecific()
                 numMs1MassChargeCombinationsConsidered,
                 numMs1MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks,
                 numMs2MassChargeCombinationsConsidered,
-                numMs2MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks
+                numMs2MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks,
+                CommonParameters.PrecursorMassMatchMode
             );
         }
 

MetaMorpheus/EngineLayer/Calibration/DataPointAquisitionResults.cs

@@ -21,7 +21,8 @@ public DataPointAquisitionResults(
             int numMs1MassChargeCombinationsConsidered,
             int numMs1MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks,
             int numMs2MassChargeCombinationsConsidered,
-            int numMs2MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks)
+            int numMs2MassChargeCombinationsThatAreIgnoredBecauseOfTooManyPeaks,
+            PrecursorMassMatchMode precursorMassMatchMode = PrecursorMassMatchMode.Monoisotopic)
             : base(dataPointAcquisitionEngine)
         {
             Psms = psms;
@@ -35,7 +36,25 @@ public DataPointAquisitionResults(
             var ms1PpmRange = Ms1List.Select(b => (b.ExperimentalMz - b.TheoreticalMz) / b.TheoreticalMz).ToArray();
             var ms2PpmRange = Ms2List.Select(b => (b.ExperimentalMz - b.TheoreticalMz) / b.TheoreticalMz).ToArray();
 
-            var precursorErrors = psms.Select(p => (p.ScanPrecursorMass - p.BioPolymerWithSetModsMonoisotopicMass.Value) / p.BioPolymerWithSetModsMonoisotopicMass.Value * 1e6).ToList();
+            // In most-abundant mode only, use the neutron-modulo residual of the precursor mass error
+            // instead of the raw difference. Most-abundant matching admits PSMs whose deconvoluted
+            // monoisotopic peak is off by +/-1-2 neutrons (the apex notch set), so the raw
+            // (ScanPrecursorMass - peptideMonoisotopic) difference carries whole-neutron offsets that are
+            // isotope-assignment errors, not instrument m/z drift; left in, they inflate the IQR and make
+            // calibration write runaway precursor tolerances (e.g. 1940 ppm). In default Monoisotopic mode
+            // the raw difference is used unchanged - baseline calibration behavior is preserved exactly.
+            bool stripNeutronOffsets = precursorMassMatchMode == PrecursorMassMatchMode.MostAbundant;
+            var precursorErrors = psms.Select(p =>
+            {
+                double deltaDa = p.ScanPrecursorMass - p.BioPolymerWithSetModsMonoisotopicMass.Value;
+                if (stripNeutronOffsets)
+                {
+                    // AwayFromZero so the nearest-neutron assignment at an exact half-neutron boundary is
+                    // parity-independent (default banker's rounding would snap to the even integer).
+                    deltaDa -= Math.Round(deltaDa / Constants.C13MinusC12, MidpointRounding.AwayFromZero) * Constants.C13MinusC12;
+                }
+                return deltaDa / p.BioPolymerWithSetModsMonoisotopicMass.Value * 1e6;
+            }).ToList();
             PsmPrecursorIqrPpmError = precursorErrors.InterquartileRange();
             PsmPrecursorMedianPpmError = precursorErrors.Median();
 

MetaMorpheus/EngineLayer/ClassicSearch/ClassicSearchEngine.cs

@@ -40,7 +40,10 @@ public ClassicSearchEngine(SpectralMatch[] globalPsms, Ms2ScanWithSpecificMass[]
         {
             SpectralMatches = globalPsms;
             ArrayOfSortedMS2Scans = arrayOfSortedMS2Scans;
-            MyScanPrecursorMasses = arrayOfSortedMS2Scans.Select(b => b.PrecursorMass).ToArray();
+            // PrecursorMassToMatch is the candidate-selection mass (equals PrecursorMass in
+            // monoisotopic mode; the most-abundant/average observed mass in most-abundant mode).
+            // The scans are sorted by this same quantity, keeping the binary search valid.
+            MyScanPrecursorMasses = arrayOfSortedMS2Scans.Select(b => b.PrecursorMassToMatch).ToArray();
             VariableModifications = variableModifications;
             FixedModifications = fixedModifications;
             SilacLabels = silacLabels;

MetaMorpheus/EngineLayer/CommonParameters.cs

@@ -63,6 +63,7 @@
             bool useMostAbundantPrecursorIntensity = true,
             DIAparameters diaParameters = null,
             IFragmentationParams fragmentationParams = null,
+            PrecursorMassMatchMode precursorMassMatchMode = PrecursorMassMatchMode.Monoisotopic,
             string rtPredictorName = "Chronologer")
 
         {
@@ -95,6 +96,7 @@
             MS2ChildScanDissociationType = ms2childScanDissociationType;
             MS3ChildScanDissociationType = ms3childScanDissociationType;
             UseMostAbundantPrecursorIntensity = useMostAbundantPrecursorIntensity;
+            PrecursorMassMatchMode = precursorMassMatchMode;
             AssumeOrphanPeaksAreZ1Fragments = assumeOrphanPeaksAreZ1Fragments;
             MaxHeterozygousVariants = maxHeterozygousVariants;
             MinVariantDepth = minVariantDepth;
@@ -207,7 +209,13 @@
         public DissociationType MS3ChildScanDissociationType { get; set; }
 
         public bool UseMostAbundantPrecursorIntensity { get; set; }
+
+        /// <summary>
+        /// Which precursor mass is used to select theoretical proteoform candidates during search.
+        /// Defaults to <see cref="EngineLayer.PrecursorMassMatchMode.Monoisotopic"/>.
+        /// </summary>
+        public PrecursorMassMatchMode PrecursorMassMatchMode { get; set; }
         public DIAparameters? DIAparameters { get; set; } //only for DIA analysis involving pseudo ms2 scan generation
         public IFragmentationParams FragmentationParameters { get; set; }
         public string RTPredictorName { get; private set; }
 
@@ -282,7 +290,9 @@
                                 ProductDeconvolutionParameters,
                                 UseMostAbundantPrecursorIntensity,
                                 DIAparameters,
-                                FragmentationParameters);
+                                FragmentationParameters,
+                                PrecursorMassMatchMode,
+                                RTPredictorName);
         }
 
         public void SetCustomProductTypes()

MetaMorpheus/EngineLayer/EngineLayer.csproj

@@ -29,7 +29,7 @@
     <PackageReference Include="Microsoft.ML.CpuMath" Version="3.0.1" />
     <PackageReference Include="Microsoft.ML.FastTree" Version="3.0.1" />
     <PackageReference Include="Microsoft.NETCore.App" Version="2.2.8" />
-    <PackageReference Include="mzLib" Version="1.0.579" />
+    <PackageReference Include="mzLib" Version="1.0.581" />
     <PackageReference Include="NETStandard.Library" Version="2.0.3" />
     <PackageReference Include="Nett" Version="0.15.0" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

MetaMorpheus/EngineLayer/ModernSearch/ModernSearchEngine.cs

@@ -100,7 +100,7 @@ protected void IndexScoreScan(Ms2ScanWithSpecificMass scan, byte[] scoringTable,
             // note that this is the OPPOSITE of the classic search (which calculates experimental masses from theoretical values)	
             // this is just PRELIMINARY precursor-mass filtering	
             // additional checks are made later to ensure that the theoretical precursor mass is acceptable
-            List<AllowedIntervalWithNotch> notches = MassDiffAcceptor.GetAllowedPrecursorMassIntervalsFromObservedMass(scan.PrecursorMass).ToList();
+            List<AllowedIntervalWithNotch> notches = MassDiffAcceptor.GetAllowedPrecursorMassIntervalsFromObservedMass(scan.PrecursorMassToMatch).ToList();
             double lowestMassPeptideToLookFor = notches.Min(p => p.Minimum);
             double highestMassPeptideToLookFor = notches.Max(p => p.Maximum);
 
@@ -305,7 +305,7 @@ protected void IncrementPeptideScoresInBin(int start, int end, List<int> bin, by
                     // at least one fragment in the scan will get fine-scored.
 
                     // add possible search results to the list of id's (only once)
-                    if (scoringTable[peptideId] == 0 && MassDiffAcceptor.Accepts(scan.PrecursorMass, PeptideIndex[peptideId].MonoisotopicMass) >= 0)
+                    if (scoringTable[peptideId] == 0 && MassDiffAcceptor.Accepts(scan.PrecursorMassToMatch, PeptideIndex[peptideId].MonoisotopicMass) >= 0)
                     {
                         peptidesPossiblyObserved.Add(peptideId);
                     }
@@ -324,7 +324,7 @@ protected void IncrementPeptideScoresInBin(int start, int end, List<int> bin, by
 
                     // if the peptide has met the score cutoff, add it to the list of peptides 
                     // possibly observed so it can be re-scored with the "fine scoring" algorithm
-                    if (score == byteScoreCutoff && MassDiffAcceptor.Accepts(scan.PrecursorMass, PeptideIndex[peptideId].MonoisotopicMass) >= 0)
+                    if (score == byteScoreCutoff && MassDiffAcceptor.Accepts(scan.PrecursorMassToMatch, PeptideIndex[peptideId].MonoisotopicMass) >= 0)
                     {
                         peptidesPossiblyObserved.Add(peptideId);
                     }
@@ -345,7 +345,10 @@ protected SpectralMatch FineScorePeptide(int id, Ms2ScanWithSpecificMass scan, i
             List<MatchedFragmentIon> matchedIons = MatchFragmentIons(scan, peptideTheorProducts, CommonParameters);
 
             double thisScore = CalculatePeptideScore(scan.TheScan, matchedIons);
-            int notch = MassDiffAcceptor.Accepts(scan.PrecursorMass, peptide.MonoisotopicMass);
+            // Use PrecursorMassToMatch (the candidate-selection mass) so the final notch is consistent
+            // with the coarse selection above; in most-abundant mode this is the apex mass, not the
+            // monoisotopic PrecursorMass. PrecursorMass still drives fragment math / error reporting.
+            int notch = MassDiffAcceptor.Accepts(scan.PrecursorMassToMatch, peptide.MonoisotopicMass);
 
             bool meetsScoreCutoff = thisScore >= CommonParameters.ScoreCutoff;
             bool scoreImprovement = PeptideSpectralMatches[scanIndex] == null || (thisScore - PeptideSpectralMatches[scanIndex].RunnerUpScore) > -SpectralMatch.ToleranceForScoreDifferentiation;

MetaMorpheus/EngineLayer/Ms2ScanWithSpecificMass.cs

@@ -11,11 +11,17 @@
     {
         public Ms2ScanWithSpecificMass(MsDataScan mzLibScan, double precursorMonoisotopicPeakMz, int precursorCharge, string fullFilePath, CommonParameters commonParam,
             IsotopicEnvelope[] neutralExperimentalFragments = null, double? precursorIntensity = null, int? envelopePeakCount = null, double? precursorFractionalIntensity = null,
+            double? precursorMassToMatch = null,
             double precursorDeconvolutionScore = 0)
         {
             PrecursorMonoisotopicPeakMz = precursorMonoisotopicPeakMz;
             PrecursorCharge = precursorCharge;
             PrecursorMass = PrecursorMonoisotopicPeakMz.ToMass(precursorCharge);
+            // Mass used for candidate selection by the MassDiffAcceptor. Defaults to the monoisotopic
+            // PrecursorMass; in most-abundant mode the caller passes the envelope's most-abundant (or,
+            // for unresolved species, average) observed mass. PrecursorMass itself is left unchanged
+            // because it still drives fragment-bin math and precursor mass-error reporting.
+            PrecursorMassToMatch = precursorMassToMatch ?? PrecursorMass;
             PrecursorIntensity = precursorIntensity ?? 1;
             PrecursorEnvelopePeakCount = envelopePeakCount ?? 1;
             PrecursorFractionalIntensity = precursorFractionalIntensity ?? -1;
@@ -43,6 +49,21 @@
         public MsDataScan TheScan { get; }
         public double PrecursorMonoisotopicPeakMz { get; }
         public double PrecursorMass { get; }
+
+        /// <summary>
+        /// 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; }
         public double PrecursorIntensity { get; }
         public int PrecursorEnvelopePeakCount { get; }
@@ -67,7 +88,7 @@
         /// An array containing the intensities of the reporter ions for isobaric mass tags. 
         /// If multiplex quantification wasn't performed, this will be null
         /// </summary>
         public double[]? IsobaricMassTagReporterIonIntensities { get; private set; }
 
         public static IsotopicEnvelope[] GetNeutralExperimentalFragments(MsDataScan scan, CommonParameters commonParam)
         {