osprey: Surfaced single-peak multiple-ID co-assignment in --model-diagnostics

pwiz_tools/Osprey/Documentation/Help/en/CommandLine.html

@@ -82,7 +82,7 @@ <h1>Osprey command-line usage</h1>
 <table>
 <tr><th>Argument</th><th>Description</th></tr>
 <tr><td><nobr>-d</nobr>,&nbsp;<nobr>--diagnostics</nobr></td><td>Write <nobr>cross-impl</nobr> bisection dumps (OSPREY_DUMP_* bundle)</td></tr>
-<tr><td><nobr>--model-diagnostics</nobr></td><td>Write a <nobr>self-contained</nobr> interactive HTML report of the trained scoring model and FDR calibration</td></tr>
+<tr><td><nobr>--model-diagnostics</nobr></td><td>Write a <nobr>self-contained</nobr> interactive HTML report of the trained scoring model, FDR calibration, and <nobr>single-peak</nobr> <nobr>multiple-ID</nobr> <nobr>co-assignment</nobr></td></tr>
 <tr><td><nobr>-h</nobr>,&nbsp;<nobr>--help</nobr></td><td>Show this help message ([ascii|unicode|sections|html|&lt;Section&gt;])</td></tr>
 <tr><td><nobr>-v</nobr>,&nbsp;<nobr>--version</nobr></td><td>Show version</td></tr>
 </table>

pwiz_tools/Osprey/Osprey.Core/FdrEntry.cs

@@ -77,6 +77,17 @@ public class FdrEntry
         public double Pep { get; set; }
         public string ModifiedSequence { get; set; }
 
+        /// <summary>
+        /// The per-entry score the EXPERIMENT-scope competitions ranked this entry on (sidecar
+        /// v4, issue #4522): max over the entry's rows across runs under the default
+        /// aggregation, <c>TargetDecoyCompetition.ComputeBaseIdMeanBestN</c>'s value under
+        /// mean-best-N. <see cref="Score"/> is the per-ROW discriminant the RUN-scope q-values
+        /// compete on; this is its experiment-scope counterpart, persisted beside the
+        /// experiment q-values so a consumer can re-gate at that scope without rebuilding the
+        /// roll-up and branching on <c>OSPREY_EXPERIMENT_AGG</c>.
+        /// </summary>
+        public double ExperimentAggregateScore { get; set; }
+
         /// <summary>
         /// Full PIN feature vector (21 features) computed during coelution scoring.
         /// Used by Percolator FDR. Null if features have not been computed yet
@@ -157,9 +168,10 @@ public FdrEntry()
         }
 
         /// <summary>
-        /// Reset the discriminant fields to the Rust <c>to_fdr_entry</c> defaults: Score 0,
-        /// every q-value and Pep 1.0. This is the state a Stage 6 rescore target is left in
-        /// for the 2nd pass to fill, and the state a fresh gap-fill stub is appended in.
+        /// Reset the discriminant fields to the Rust <c>to_fdr_entry</c> defaults: Score and
+        /// <see cref="ExperimentAggregateScore"/> 0, every q-value and Pep 1.0. This is the
+        /// state a Stage 6 rescore target is left in for the 2nd pass to fill, and the state a
+        /// fresh gap-fill stub is appended in.
         ///
         /// <para>One method because the same eight assignments had been written out five
         /// times - the rescore overlay, both gap-fill passes, and the rebuild-from-disk - and
@@ -169,6 +181,7 @@ public FdrEntry()
         public void ResetScores()
         {
             Score = 0.0;
+            ExperimentAggregateScore = 0.0;
             RunPrecursorQvalue = 1.0;
             RunPeptideQvalue = 1.0;
             RunProteinQvalue = 1.0;

pwiz_tools/Osprey/Osprey.FDR/FdrProjectionOutput.cs

@@ -119,16 +119,26 @@ public interface IFdrOutputSink
         /// Accept one scored row. <paramref name="fileIdx"/> / <paramref name="rowIdx"/>
         /// locate the row within its per-file list; <paramref name="entryId"/> /
         /// <paramref name="isDecoy"/> / <paramref name="charge"/> / <paramref name="peptide"/>
-        /// identify it; <paramref name="score"/> + <paramref name="q"/> are the freshly
+        /// identify it; <paramref name="score"/> +
+        /// <paramref name="experimentAggregateScore"/> + <paramref name="q"/> are the freshly
         /// computed outputs. Called once per row, in nested (file, row) order == the flat
         /// score-pass index order. <paramref name="charge"/> / <paramref name="peptide"/> are
         /// passed in (not read off a resident row) so the sink's [COUNT] tally + streaming
         /// --model-diagnostics accumulator work whether the caller holds a resident projection
         /// (2nd pass) or streams the rows straight from parquet with no resident buffer at all
         /// (1st-pass streaming, issue #4355 struct-shrink S3 Stage B).
+        ///
+        /// <para><paramref name="experimentAggregateScore"/> is the per-entry score the
+        /// experiment-scope competitions ranked this row's entry on (sidecar v4, issue #4522)
+        /// - constant across every row of an entry, and equal to <paramref name="score"/> only
+        /// on a single-file run whose precursors carry one row each. It rides the sink rather
+        /// than <see cref="FdrQValues"/> because it is a score, not a q-value, and rather than
+        /// <see cref="FdrProjection"/> because that struct is deliberately lean (issue #4355
+        /// S0/S1) and guarded against regrowth.</para>
         /// </summary>
         void Accept(int fileIdx, int rowIdx, uint entryId, bool isDecoy,
-            byte charge, string peptide, double score, in FdrQValues q);
+            byte charge, string peptide, double score, double experimentAggregateScore,
+            in FdrQValues q);
 
         /// <summary>
         /// Finalize the pass: emit the tail <c>[COUNT]</c> lines (per-file pass counts,

pwiz_tools/Osprey/Osprey.FDR/ModelDiagnostics/ModelDiagnosticsData.Accumulator.cs

@@ -142,6 +142,15 @@ public Accumulator(
                 _entExpSets = NewSets(_nFiles);
             }
 
+            /// <summary>
+            /// The entrapment classification this accumulator was built with, so a sibling panel
+            /// computed outside the streamed fold - the pass-1 peak co-assignment source, which
+            /// reads apex RT off the FDR sidecars rather than the score pass - classifies rows
+            /// identically without rebuilding it. Worth exposing rather than recomputing:
+            /// classifying the searched library runs for minutes at 6.3M entries.
+            /// </summary>
+            public IReadOnlyDictionary<uint, EntrapmentClass> ClassByBaseId => _classByBaseId;
+
             private static List<HashSet<string>> NewSets(int n)
             {
                 var list = new List<HashSet<string>>(n);