[htsugawa]

Why

Within one lipid class on reversed-phase LC:

• more carbons elute later;
• more double bonds elute earlier;
• more oxygens elute earlier.

Curators use these rules by eye to reject false positives, and that manual pass is the bottleneck. It gets worse on very sensitive instruments: on ZenoTOF 8600 data, false positives are numerous even at a 0.5 min LBM2 RT tolerance. It is also worse for outside users, whose LC differs from the library's predicted RTs.

This PR lets MS-DIAL check lipid annotations against the rules and add the existing PeakSpotTag.CONFIRMED to the consistent ones:

• on per-sample peaks (ChromatogramPeakFeature);
• on alignment spots (AlignmentSpotProperty).

It never removes or overrides a person's tag.

The check (rule version 1.0)

• Species level only. It compares the sum composition (class, total C, total DB, total O; P- counted as O- with one more DB). Fatty-acid composition is not used for RT. A class-level match is eligible, but by default it is Confirmed only when a second adduct or the other polarity corroborates it.

• Exact order consistency. Within each class, the check finds the maximum-weight consistent subset of the dominance order, exactly, with an integer max-flow (Dilworth antichain). An annotation is Confirmed only if it belongs to every maximum subset and has adjacent directional support (a +C neighbour and a +DB neighbour bracketing it).

• Rejection rules:

  • margins scale with the run's RT span;
  • a local magnitude check rejects an RT that sits too far from what its neighbours predict.

• MS1 artefact layer. A brighter co-eluting partner that explains the annotation means it is not Confirmed. Covered: isotopes, Na/H, NH4/K, acetate/formate/Cl, demethylation, in-source chain or head losses, oxidised ions.

• Propagation. A confirmed feature's other adducts ([M+Na]+ included) are Confirmed with it.

• Chromatography gate. A positive carbon slope and order concordance are required. HILIC data get no Confirmed.

• Optional chain-rule plausibility profile "Mammalian" (off by default):

  • no chain has DB ≥ 7;
  • a sphingolipid N-acyl chain has DB ≤ 2;
  • a sphingoid base has C16–20 and DB ≤ 2.

  It has no lipid-class bias, by design.

• Outcomes. Each annotation gets a verdict: Confirmed, NotEvaluable (with a reason code) or Inconsistent (with evidence). Inconsistent is reported only; the check never writes Misannotation.

• Cross-polarity corroboration (step 11) is implemented as a pure function with tests. Applying it from the GUI or Console is deferred to v1.1.

Evaluation (Python reference; the C# reproduces it object for object)

The truth sets are human curations. The primary held-out set is the author's own curation of ZT Scan DIA mouse liver, scored only on what was curated. Development used plasma.

Setting	Liver (held out): precision / share of curated "confirmed" recovered
All candidates (null)	0.43 / 1.00
HighPrecision (default, class-level corroborated)	0.86 / 0.37
Strict	0.93 / 0.20
Confirmed in both polarities	0.98 / 0.13

• Other sets: NIST SRM1950 NEG 0.95; a FastLC dataset 0.98 / 1.00.
• Negative controls: three HILIC datasets get 0 Confirmed. MS1-realistic decoys (isotope, Na/H, in-source fragments) get 0 Confirmed.

Where it runs

• Hook A: LC-MS FileProcess, after annotation and before save. Console and GUI share it.
• Hook B: after alignment, after isotope tracking, before save and export.
• GUI: a ribbon action, "Re-run lipid RT check", for LC-MS alignment results (the MS-CleanR pattern).
• Parameters: LipidRtCheckParameter at ParameterBase Key 18. Console method-file keys start with Lipid RT check…; they are registered, templated and listed in ParametersAsText.
• Outputs:
  • the Console writes <alignment>_lipidrt_review.tsv;
  • mzTab-M gets opt_global_lipid_rt_outcome, _reason and _score;
  • tags keep appearing as Tag: Confirmed in the Comment column.

Tag provenance (who set a tag) and compatibility

• Provenance lives in the existing _tags.xml files, readable by people and external tools:

  • <Tag Source="MsdialLipidRtCheck/1.0">1</Tag> marks a tag set by the check;
  • <Suppressed Source="User">1</Suppressed> records that a person removed a tag the check had set.

  Older readers read only the <Tag> values, so they still see the same tags.

• How the check treats tags:

  • it removes only its own tags before re-evaluating;
  • a person's tags stay the person's; GUI toggles, "Mark all as confirmed" and undo are routed through the person path;
  • a person's annotation change withdraws the check's tag on that object.

• Verdict storage: the verdict is a MessagePack record:

  • AlignmentSpotProperty Key 66;
  • ChromatogramPeakFeature Key 56.

  ChromatogramPeakFeature keys 54 and 55 are reserved as integers for the MS-DIAL 5.6 line's RawDataIDType and AccumulatedDataIDType. Replace the placeholders with those members when the 5.6 line is merged.

• Backward compatibility: old files load, and master's MsdialCore reads files written by this branch.

Verification

• Builds (Release): MsdialCore, MsdialLcMsApi, the Console and MsdialGuiApp all build with 0 errors.

• Tests:

  Project	Result
  MsdialCoreTests	688 passed, including the reference-gated parity tests (run with MSDIAL_LIPIDRT_REFERENCE_DIR)
  MsdialCoreTestAppTests	194 passed
  MsdialLcMsApiTests	109 passed, 2 skipped (existing skips)
  MsdialGuiAppTests	179 passed, 1 failed

  The GUI failure is LcmsAnalysisModelWithoutRawTests.ASampleWithoutRawDataOpensFromWhatTheProjectStores. Its cleanup cannot delete a locked temporary .dcl, and it fails the same way before this PR's GUI commits.

• Parity with the Python reference: 100% agreement, object by object (outcome, reason, score and evidence fields). Covered: demo POS/NEG alignments and per-sample peaks, ClassLevelPolicy Consistent and Corroborated, cross-polarity, and seven evaluation runs.

• Console smoke runs on public verification data:

  • With Lipid RT check: False, or on a non-lipidomics method, outputs match master except for version strings, timestamps and paths.
  • Binary project files still differ by the new nil keys.

Decisions still open

1. Default. The check is on by default for lipidomics projects (IsEnabled null means on for TargetOmics Lipidomics). An existing lipidomics method file therefore now gets verdicts, Confirmed tags, the review TSV and the mzTab-M columns. An opt-in default is a one-line change.
2. Re-ticking. A person who removes the check's Confirmed, re-ticks it and removes it again currently lets a later run set it again. The alternative: any removal by a person blocks the check.

Deferred to v1.1: applying cross-polarity from the GUI or Console (MS-DIAL Interactive's lab pos/neg merge will call it), LC-IM-MS / GC-MS / DIMS hooks, and light-mode persistence.

🤖 Generated with Claude Code

[htsugawa]

Follow-up after the lead developer's MVVM review: two commits now remove the ViewModel → View dependency this PR had added to LcmsMethodViewModel.

• 87691ea: the "Re-run lipid RT check" command no longer creates the window, shows a MessageBox or uses Application.Current.MainWindow. It publishes ErrorMessageBoxRequest (no alignment selected) or the LipidRtCheckSettingViewModel on the broker, and MainWindow opens the window as a modal child dialog with ShowChildDialog. This is the pattern the authors use for AlignmentResultExportViewModel.
• 4b40331: a test that, without an alignment result, the command asks the View for the same error box it showed before.

The Model side of this PR was already free of ViewModel and WPF references. Merge order: #833 first, which fixes the failing GUI test behind this PR's red check, then #834 (lock files).

🤖 Generated with Claude Code