smith-chem-wisc
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/CorrectedEnvelope.cs‎
Lines changed: 21 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/CorrectedEnvelope.cs‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/CorrectedTrace.cs‎
Lines changed: 29 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/CorrectedTrace.cs‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassFeature.cs‎
Lines changed: 96 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassFeature.cs‎
Lines changed: 96 additions & 0 deletions
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassFeatureBuilder.cs‎
Lines changed: 101 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassFeatureBuilder.cs‎
Lines changed: 101 additions & 0 deletions
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassTrace.cs‎
Lines changed: 37 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassTrace.cs‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassTraceBuilder.cs‎
Lines changed: 95 additions & 0 deletions b/‎mzLib/MassSpectrometry/Deconvolution/Consensus/MassTraceBuilder.cs‎
Lines changed: 95 additions & 0 deletions
@@ -0,0 +1,21 @@
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// One envelope inside a <see cref="CorrectedTrace"/>, carrying both its
+    /// original (algorithm-reported) mass and the post-correction mass.
+    /// <see cref="WasCorrected"/> is true iff <see cref="TraceCorrector"/>
+    /// flagged this envelope as an off-by-one outlier and snapped its
+    /// mass to the trace consensus.
+    /// </summary>
+    public sealed class CorrectedEnvelope
+    {
+        public int ScanIndex;
+        public int ScanNumber;
+        public double RT;
+        public double OriginalMass;
+        public double CorrectedMass;
+        public int Charge;
+        public double Intensity;
+        public bool WasCorrected;
+    }
+}
@@ -0,0 +1,29 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// A <see cref="MassTrace"/> after off-by-one correction by
+    /// <see cref="TraceCorrector"/>. <see cref="ConsensusMass"/> is the
+    /// per-trace (weighted) median; envelopes whose original mass differed
+    /// by approximately +/-1.00335 Da from it have been snapped to the
+    /// consensus and have <see cref="CorrectedEnvelope.WasCorrected"/> set.
+    /// Original masses are preserved on each envelope for diagnostic
+    /// inspection.
+    /// </summary>
+    public sealed class CorrectedTrace
+    {
+        public int Id;
+        public int Charge;
+        public double ConsensusMass;
+        public List<CorrectedEnvelope> Envelopes = new();
+        public double OriginalSpread;
+        public double CorrectedSpread;
+        public int CorrectionCount => Envelopes.Count(e => e.WasCorrected);
+
+        public double FirstRT => Envelopes[0].RT;
+        public double LastRT => Envelopes[^1].RT;
+        public double TotalIntensity => Envelopes.Sum(e => e.Intensity);
+    }
+}
@@ -0,0 +1,96 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// CONSENSUS PIPELINE OVERVIEW (the type hierarchy, narrowest to widest).
+    ///
+    /// The consensus mass-tracing pipeline turns raw per-scan deconvolution
+    /// output into cross-charge features through four nested levels. Each level
+    /// groups the one below it:
+    ///
+    ///   IsotopicEnvelope      one deconvolved species (mass, intensity, charge)
+    ///     |                   reported in a SINGLE MS1 scan. Raw input; not a
+    ///     |                   type in this namespace.
+    ///     |   grouped by <see cref="MassTraceBuilder"/> (charge-locked,
+    ///     |   anchor-mass + scan-adjacency)
+    ///     v
+    ///   <see cref="MassTrace"/>        the same species followed across adjacent
+    ///     |                   scans at ONE charge state. Its envelopes are the
+    ///     |                   raw per-scan tuples above.
+    ///     |   corrected by <see cref="TraceCorrector"/> (off-by-one rescue +
+    ///     |   resolution-aware splitting)
+    ///     v
+    ///   <see cref="CorrectedTrace"/>   a MassTrace after correction, holding
+    ///     |                   <see cref="CorrectedEnvelope"/> entries (original
+    ///     |                   + corrected mass per envelope) and a per-trace
+    ///     |                   <see cref="CorrectedTrace.ConsensusMass"/>. Still
+    ///     |                   one charge state.
+    ///     |   stitched by <see cref="MassFeatureBuilder"/> (cross-charge,
+    ///     |   ppm mass agreement + RT overlap)
+    ///     v
+    ///   MassFeature           THIS type: one species across ALL of its charge
+    ///                         states. The widest grouping, and the unit the
+    ///                         writer turns into an Ms1Feature row.
+    ///
+    /// So: envelopes nest inside traces, traces (after correction) nest inside
+    /// features. Charge is fixed within a trace and varies across a feature.
+    ///
+    /// A cross-charge-state consensus feature: a group of
+    /// <see cref="CorrectedTrace"/> entries (each at one charge state) whose
+    /// consensus masses agree within a ppm tolerance and whose RT windows
+    /// overlap.
+    ///
+    /// A real proteoform or peptide produces envelopes at several charge
+    /// states (BU peptides commonly +2/+3; TD proteoforms across +10..+15
+    /// or wider). The trace builder is charge-locked, so each charge gets
+    /// its own trace. <see cref="MassFeatureBuilder"/> stitches those
+    /// per-charge traces back together. Charge multiplicity then becomes
+    /// a confidence signal: a feature seen at multiple charges is
+    /// corroborated by independent charge calculations; a single-charge,
+    /// single-envelope feature is more likely to be noise.
+    ///
+    /// Mutation policy: callers append to <see cref="Traces"/> during
+    /// construction, then call <see cref="Finalise"/> exactly once to
+    /// derive the aggregate fields. After Finalise, the feature is
+    /// treated as read-only by downstream consumers.
+    /// </summary>
+    public sealed class MassFeature
+    {
+        public int Id;
+        public List<CorrectedTrace> Traces = new();
+        public double ConsensusMass;
+        public HashSet<int> Charges = new();
+        public int ChargeCount => Charges.Count;
+        public int MaxTraceLength;
+        public double RTStart;
+        public double RTEnd;
+        public double SummedIntensity;
+
+        /// <summary>
+        /// Populate derived fields from the current <see cref="Traces"/>
+        /// list. Idempotent; safe to re-run after the trace list changes.
+        /// <see cref="ConsensusMass"/> is the intensity-weighted mean of
+        /// per-trace consensus masses (heavier traces contribute more).
+        /// </summary>
+        public void Finalise()
+        {
+            if (Traces.Count == 0)
+                throw new System.InvalidOperationException("Cannot Finalise a MassFeature with no traces.");
+
+            Charges = new HashSet<int>(Traces.Select(t => t.Charge));
+            SummedIntensity = Traces.Sum(t => t.TotalIntensity);
+            RTStart = Traces.Min(t => t.FirstRT);
+            RTEnd = Traces.Max(t => t.LastRT);
+            MaxTraceLength = Traces.Max(t => t.Envelopes.Count);
+
+            // Intensity-weighted mean of per-trace consensus masses. Heavier
+            // traces (more intense, more confident) contribute more.
+            double w = Traces.Sum(t => t.TotalIntensity);
+            ConsensusMass = w == 0
+                ? Traces.Average(t => t.ConsensusMass)
+                : Traces.Sum(t => t.ConsensusMass * t.TotalIntensity) / w;
+        }
+    }
+}
@@ -0,0 +1,101 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// Stitches per-charge <see cref="CorrectedTrace"/> entries back into
+    /// cross-charge <see cref="MassFeature"/> objects.
+    ///
+    /// Algorithm:
+    ///   1. Sort the corrected traces by ConsensusMass.
+    ///   2. Sweep with a ppm-wide window; for each pair of traces inside
+    ///      the window, if (a) their charges differ and (b) their RT
+    ///      ranges overlap, union-find them.
+    ///   3. Each connected component becomes a <see cref="MassFeature"/>.
+    ///
+    /// Same-charge co-mass traces are intentionally NOT merged here: if
+    /// two traces share a charge and mass, the trace builder would already
+    /// have merged them when their scan ranges overlapped. If they didn't
+    /// overlap (co-eluting twins or a Phase-2 split), they remain separate
+    /// features.
+    /// </summary>
+    public static class MassFeatureBuilder
+    {
+        public static List<MassFeature> BuildFeatures(
+            IReadOnlyList<CorrectedTrace> corrected,
+            double massPpm)
+        {
+            // Sort traces by consensus mass to enable a single sliding-window pass.
+            var sorted = corrected.OrderBy(t => t.ConsensusMass).ToArray();
+            int n = sorted.Length;
+
+            // Union-find over trace indices.
+            int[] parent = new int[n];
+            for (int i = 0; i < n; i++) parent[i] = i;
+            int Find(int x)
+            {
+                while (parent[x] != x) { parent[x] = parent[parent[x]]; x = parent[x]; }
+                return x;
+            }
+            void Union(int x, int y)
+            {
+                int rx = Find(x), ry = Find(y);
+                if (rx != ry) parent[rx] = ry;
+            }
+
+            for (int i = 0; i < n; i++)
+            {
+                double anchorMass = sorted[i].ConsensusMass;
+                double window = anchorMass * massPpm * 1e-6;
+                for (int j = i + 1; j < n; j++)
+                {
+                    double dm = sorted[j].ConsensusMass - anchorMass;
+                    if (dm > window) break;
+                    if (sorted[i].Charge == sorted[j].Charge) continue;
+                    if (!RtOverlap(sorted[i], sorted[j])) continue;
+                    Union(i, j);
+                }
+            }
+
+            // Collect connected components.
+            var byRoot = new Dictionary<int, List<CorrectedTrace>>();
+            for (int i = 0; i < n; i++)
+            {
+                int r = Find(i);
+                if (!byRoot.TryGetValue(r, out var bucket))
+                {
+                    bucket = new List<CorrectedTrace>();
+                    byRoot[r] = bucket;
+                }
+                bucket.Add(sorted[i]);
+            }
+
+            // Finalise each component, then assign IDs in a deterministic order. Dictionary
+            // enumeration is not order-stable, so without this sort the feature IDs -- and the
+            // row order of the written _ms1.feature file -- would vary run-to-run on identical
+            // input. Order by (consensus mass, then min charge, then RT start).
+            var features = new List<MassFeature>(byRoot.Count);
+            foreach (var (_, traces) in byRoot)
+            {
+                var f = new MassFeature { Traces = traces };
+                f.Finalise();
+                features.Add(f);
+            }
+            features.Sort((a, b) =>
+            {
+                int c = a.ConsensusMass.CompareTo(b.ConsensusMass);
+                if (c != 0) return c;
+                c = a.Charges.Min().CompareTo(b.Charges.Min());
+                if (c != 0) return c;
+                return a.RTStart.CompareTo(b.RTStart);
+            });
+            for (int i = 0; i < features.Count; i++)
+                features[i].Id = i + 1;
+            return features;
+        }
+
+        private static bool RtOverlap(CorrectedTrace a, CorrectedTrace b)
+            => a.FirstRT <= b.LastRT && b.FirstRT <= a.LastRT;
+    }
+}
@@ -0,0 +1,37 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// A single mass trace: a sequence of per-scan envelopes that the grouper
+    /// believes belong to the same species. Same charge across all entries,
+    /// scan-adjacency &lt;= MaxGap, mass within tolerance of <see cref="AnchorMass"/>.
+    ///
+    /// <see cref="MassTraceBuilder"/> populates these in scan-order. Off-by-one
+    /// correction is then handled by <see cref="TraceCorrector"/>, which wraps
+    /// each trace in a <see cref="CorrectedTrace"/> rather than mutating it.
+    /// Mutation policy on the trace itself: contents are appended during
+    /// construction and read-only thereafter.
+    /// </summary>
+    public sealed class MassTrace
+    {
+        public int Id;
+        public int Charge;
+
+        /// <summary>
+        /// First envelope's mass; never updated after trace creation. Keeping
+        /// the anchor fixed bounds the trace to AnchorMass +/- tolerance and
+        /// prevents drift over long traces.
+        /// </summary>
+        public double AnchorMass;
+
+        public List<(int ScanIndex, int ScanNumber, double RT, double Mass, double Intensity)> Envelopes
+            = new();
+
+        public int LastScanIndex => Envelopes[^1].ScanIndex;
+        public double MinMass => Envelopes.Min(e => e.Mass);
+        public double MaxMass => Envelopes.Max(e => e.Mass);
+        public double MassSpread => MaxMass - MinMass;
+    }
+}
@@ -0,0 +1,95 @@
+using System.Collections.Generic;
+
+namespace MassSpectrometry.Deconvolution.Consensus
+{
+    /// <summary>
+    /// Greedy mass-trace builder, charge-locked.
+    ///
+    /// For each MS1 scan in input order, every envelope is offered to the
+    /// open traces. An envelope joins a trace if (a) charges match, (b) the
+    /// trace has been touched within MaxGap+1 scans of the current one, and
+    /// (c) the envelope's mass is within tolerance of the trace's anchor.
+    /// Best match (closest mass) wins ties. No drift: the anchor is the
+    /// first envelope's mass, fixed for the life of the trace.
+    ///
+    /// Inputs: per-scan envelope lists in scan order, aligned to a parallel
+    /// list of <see cref="MsDataScan"/>. Output: every trace (open or closed
+    /// at end-of-input) in a flat list. Length-1 singletons are included --
+    /// downstream code applies length filters per its own taste.
+    /// </summary>
+    public static class MassTraceBuilder
+    {
+        public static List<MassTrace> BuildTraces(
+            IReadOnlyList<MsDataScan> ms1Scans,
+            IReadOnlyList<IReadOnlyList<IsotopicEnvelope>> perScanEnvelopes,
+            double toleranceDa,
+            int maxGap)
+        {
+            if (perScanEnvelopes.Count != ms1Scans.Count)
+                throw new System.ArgumentException(
+                    $"perScanEnvelopes ({perScanEnvelopes.Count}) must align 1:1 with ms1Scans ({ms1Scans.Count}).",
+                    nameof(perScanEnvelopes));
+
+            var open = new List<MassTrace>();
+            var closed = new List<MassTrace>();
+            int nextId = 1;
+
+            for (int scanIdx = 0; scanIdx < ms1Scans.Count; scanIdx++)
+            {
+                // Retire open traces whose last-touched scan is too old.
+                for (int i = open.Count - 1; i >= 0; i--)
+                {
+                    int gap = scanIdx - open[i].LastScanIndex - 1;
+                    if (gap > maxGap)
+                    {
+                        closed.Add(open[i]);
+                        open.RemoveAt(i);
+                    }
+                }
+
+                foreach (var env in perScanEnvelopes[scanIdx])
+                {
+                    MassTrace best = null!;
+                    double bestDelta = double.MaxValue;
+                    foreach (var t in open)
+                    {
+                        if (t.Charge != env.Charge) continue;
+                        // Don't add a second envelope from the same scan to the same trace.
+                        if (t.LastScanIndex == scanIdx) continue;
+                        double d = System.Math.Abs(env.MonoisotopicMass - t.AnchorMass);
+                        if (d <= toleranceDa && d < bestDelta)
+                        {
+                            best = t;
+                            bestDelta = d;
+                        }
+                    }
+
+                    var entry = (scanIdx,
+                                 ms1Scans[scanIdx].OneBasedScanNumber,
+                                 ms1Scans[scanIdx].RetentionTime,
+                                 env.MonoisotopicMass,
+                                 env.TotalIntensity);
+
+                    if (best != null)
+                    {
+                        best.Envelopes.Add(entry);
+                    }
+                    else
+                    {
+                        var nt = new MassTrace
+                        {
+                            Id = nextId++,
+                            Charge = env.Charge,
+                            AnchorMass = env.MonoisotopicMass,
+                        };
+                        nt.Envelopes.Add(entry);
+                        open.Add(nt);
+                    }
+                }
+            }
+
+            closed.AddRange(open);
+            return closed;
+        }
+    }
+}