ArgumentOutOfRangeException in MSDecHandler.getRefinedModelChromatograms during GC-MS quantitative data processing (v5.5.260323)

[Catosine]

Bug Description

An unhandled System.ArgumentOutOfRangeException is raised during the quantitative analysis workflow of GC-MS data in MS-DIAL v5.5.260323. The exception originates from the MSDecHandler.getRefinedModelChromatograms method, suggesting an index access violation on the modelChromatograms collection during the deconvolution step.

Environment

• Software: MS-DIAL v5.5.260323
• Analysis Type: GC-MS quantitative analysis
• Data Type: ABF data converted from Agilent dotD files
• Operating System: Windows

Steps to Reproduce

1. Launch MS-DIAL v5.5.260323.
2. Load a very large GC-MS dataset (18,000+ samples) for quantitative analysis.
3. Run peak detection and alignment for peak matrix.
4. The application crashes with an unhandled exception dialog.

Note: I am happy to provide the specific project file, parameter set that trigger this crash if required for reproduction.
Note: I am sorry for unable to provide examples of raw data, since they are related to ongoing research projects and I believe there is nothing related to specific files but a very large amount of dataset.

Expected Behavior

The deconvolution and chromatogram refinement pipeline should complete without unhandled exceptions, or gracefully handle edge cases where the model chromatogram collection is empty or misaligned.

Actual Behavior

The application terminates with the following exception:

Unhandled exception in MSDIAL v5.5.260323

索引超出范围。必须为非负值并小于集合大小。
参数名: index

Stack trace:
   at System.ThrowHelper.ThrowArgumentOutOfRangeException(ExceptionArgument argument, ExceptionResource resource)
   at CompMs.MsdialCore.MSDec.MSDecHandler.getRefinedModelChromatograms(List`1 modelChromatograms)
   at CompMs.MsdialCore.MSDec.MSDecHandler.GetMSDecResults(IReadOnlyList`1 spectrumList, List`1 chromPeakFeatures, ParameterBase param, ReportProgress reporter)
   at CompMs.MsdialGcMsApi.Process.FileProcess.<DetectScans>d__17.MoveNext()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at CompMs.MsdialGcMsApi.Process.FileProcess.<RunAsync>d__15.MoveNext()
   at CompMs.MsdialCore.Algorithm.ProcessRunner.Consumer.<ConsumeAsync>d__5.MoveNext()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at CompMs.App.Msdial.View.Core.MainWindow.<<ShowMultiProgressBarWindow>b__0>d.MoveNext()
   at System.Windows.Threading.ExceptionWrapper.InternalRealCall(Delegate callback, Object args, Int32 numArgs)
   at System.Windows.Threading.ExceptionWrapper.TryCatchWhen(Object source, Delegate callback, Object args, Int32 numArgs, Delegate catchHandler)

Additional Context

The crash appears to occur specifically within the GC-MS API processing pipeline (CompMs.MsdialGcMsApi.Process.FileProcess) during the scan detection phase, when the MSDec handler attempts to retrieve refined model chromatograms. This may indicate that a chromatographic peak feature is being associated with an invalid index in the model chromatogram list, possibly due to an empty or unexpectedly filtered feature set prior to deconvolution.

Please let me know if further diagnostic information would be helpful.

Thank you for all you have done!

[Catosine]

Follow-up: Reproducibility Confirmed with Reduced Dataset — Alignment Stage Crash at ~75% Progress

Additional Testing

To further isolate this issue, I performed a controlled validation using a reduced batch of 200+ samples consisting exclusively of standard compounds with known identities and known concentrations. The crash persists under these simplified conditions, suggesting the fault is not contingent on sample complexity or matrix effects.

Updated Observations

• Crash timing: The exception is consistently thrown during the Alignment step, specifically when the progress bar reaches approximately 75% completion.
• Exception type: Same System.ArgumentOutOfRangeException ("索引超出范围"), but the stack trace now points to the Alignment / Deduplication pipeline rather than the MSDec deconvolution module reported in the original issue.

Updated Stack Trace (Alignment Stage)

Unhandled exception in MSDIAL v5.5.260323

索引超出范围。必须为非负值并小于集合大小。
参数名: index

Stack trace:
   at System.ThrowHelper.ThrowArgumentOutOfRangeException(ExceptionArgument argument, ExceptionResource resource)
   at CompMs.MsdialCore.Algorithm.Alignment.MatchResultAnnotationDeduplicator.Process(IEnumerable`1 spots)
   at CompMs.MsdialCore.Algorithm.Alignment.AlignmentRefiner.Deduplicate(List`1 alignments)
   at CompMs.MsdialCore.Algorithm.Alignment.AlignmentRefiner.Refine(IList`1 alignments)
   at CompMs.MsdialCore.Algorithm.Alignment.PeakAligner.Alignment(IReadOnlyList`1 analysisFiles, AlignmentFileBean alignmentFile, ChromatogramSerializer`1 spotSerializer)
   at CompMs.App.Msdial.Model.Gcms.GcmsMethodModel.<>c__DisplayClass28_0.<RunAlignment>b__0()
   at System.Threading.Tasks.Task`1.InnerInvoke()
   at System.Threading.Tasks.Task.Execute()
   --- End of inner exception stack trace ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at CompMs.App.Msdial.Model.Gcms.GcmsMethodModel.<RunAlignment>b__28_0.MoveNext()
   --- End of inner exception stack trace ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at CompMs.App.Msdial.View.Core.MainWindow.<>c__DisplayClass8_0.<<ShowProgressBarWindow>b__0>d.MoveNext()
   --- End of inner exception stack trace ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Windows.Threading.ExceptionWrapper.InternalRealCall(Delegate callback, Object args, Int32 numArgs)
   at System.Windows.Threading.ExceptionWrapper.TryCatchWhen(Object source, Delegate callback, Object args, Int32 numArgs, Delegate catchHandler)

Diagnostic Interpretation

The fault now localizes to MatchResultAnnotationDeduplicator.Process, invoked within AlignmentRefiner.Deduplicate during the alignment refinement phase. This implies that at ~75% of the alignment workflow, a spot index or annotation mapping references a position outside the bounds of the deduplicated spot collection. Because the issue is reproducible with a small, well-characterized standard dataset, it is likely a deterministic boundary-condition bug in the deduplication logic rather than a data-corruption artifact.

Request for Guidance

Could the maintainers advise on:

1. Whether the original MSDec crash and this Alignment crash share a common root cause (e.g., an off-by-one index propagated from feature detection into alignment), or if they should be tracked as separate issues?
2. Any specific parameter settings (e.g., alignment tolerance, retention index window, or minimum peak thresholds) that might serve as a temporary workaround?

I remain ready to share the parameter export, the 200+ standard gas dataset, or the project file to facilitate reproduction.

---

Environment (repeated for clarity): MS-DIAL v5.5.260323, GC-MS quantitative workflow, Windows.

[Catosine]

Bug Analysis: ArgumentOutOfRangeException in MS-DIAL v5 GC-MS Workflow

Disclosure: This document was co-authored by human programmer Catosine and DeepSeek V4 Pro (AI). While every effort has been made to ensure accuracy through source-code analysis, the information herein should be independently verified by developers before acting on it. File paths, line numbers, and code excerpts reflect the repository state at the time of writing and may have changed.

TL;DR

MS-DIAL v5.5.260323 crashes during GC-MS quantitative analysis due to two unconditional index-accesses on potentially empty collections. The crashes occur at different pipeline stages with different triggers, but share the same root pattern.

	Bug 1 — MSDec Deconvolution	Bug 2 — Alignment Dedup
Crash site	MSDecHandler.getRefinedModelChromatograms()	MatchResultAnnotationDeduplicator.Process()
File	MsdialCore/MSDec/MSDecHandler.cs:1051	MsdialCore/Algorithm/Alignment/SpotAction.cs:35
Trigger	Matched filter produces zero signal regions	No spots pass reference-library match filter
Fix	Add if (modelChromatograms.Count == 0) return ...; at method entry	Add if (spotList.Count == 0) return; before first-pass loop
Data safe after fix?	✅ Yes — peak features intact; deconvolution columns empty	✅ Yes — data fully unchanged; dedup tagging skipped
Scope	GUI + CLI (GC-MS mode only)	GUI + CLI (all modes: GCMS/LCMS/IM-MS/DI-MS)
MS-DIAL 4 affected?	✅ Yes	N/A (v4 alignment path differs)

Only two files need changing (both under src/MSDIAL5/MsdialCore/), resolving GUI and CLI in one shot. MS-DIAL 4 has the same defect in Deconvolution.cs requiring a separate fix.

---

At a Glance

Aspect	Bug 1 — MSDec Deconvolution	Bug 2 — Alignment Dedup
Stage	Peak detection / deconvolution (single file)	Alignment / dedup (cross-file refinement, ~75% progress)
Severity	Blocks single-file processing	Blocks entire experiment alignment
Root cause	Model chromatogram construction yields empty list	All alignment spots fail reference-library matching
Common pattern	Implicit "at least one result" assumption breaks in large datasets	Same

The two bugs are not the same root cause, but reflect the same class of code-quality defect.

---

Bug 1: MSDec Deconvolution — Empty-List Index in getRefinedModelChromatograms

Files Involved

Component	Path	Lines
MS-DIAL 5	src/MSDIAL5/MsdialCore/MSDec/MSDecHandler.cs	1048–1065
MS-DIAL 4 (same defect)	src/MSDIAL4/MsdialGcmsProcessStandard/Algorithm/Deconvolution.cs	306–323

Call Chain

FileProcess.RunAsync()
  → DetectScans()
    → MSDecHandler.GetMSDecResults()
      → getModelChromatograms()          // may return empty list
      → getRefinedModelChromatograms()   // ← crash: unguarded access to modelChromatograms[0]

Root Cause

private static List<ModelChromatogram> getRefinedModelChromatograms(
    List<ModelChromatogram> modelChromatograms) 
{
    modelChromatograms = modelChromatograms.OrderBy(n => n.ChromScanOfPeakTop).ToList();
    var chromatograms = new List<ModelChromatogram>() { modelChromatograms[0] }; // ← crash line
    // ...
}

Upstream getModelChromatograms() builds models from region markers produced by the matched filter. If the entire matchedFilterArray has no contiguous positive-valued regions, regionMarkers is empty → loop never executes → returns empty list. This can occur in edge-case samples within very large datasets (18,000+) or in low-SNR data.

Key distinction: Peak spotting (_peakSpotting.Run()) produces data independently of this step. The crash does not mean "all peaks were filtered."

Fix

private static List<ModelChromatogram> getRefinedModelChromatograms(
    List<ModelChromatogram> modelChromatograms) 
{
    if (modelChromatograms == null || modelChromatograms.Count == 0)
        return modelChromatograms ?? new List<ModelChromatogram>();
    // ... remainder unchanged
}

Data Flow After Fix

With the fix, GetMSDecResults safely returns an empty list. In FileProcess.RunAsync():

• chromPeakFeatures (from peak spotting) serializes successfully ✅
• msdecResults is empty → Identification returns empty → SpectrumFeatureCollection empty
• The sample appears in the final alignment table, with chromatogram data intact; only deconvolution-derived columns (match scores, spectra) are empty.

---

Bug 2: Alignment Dedup — Empty-List Index in MatchResultAnnotationDeduplicator.Process

Files Involved

src/MSDIAL5/MsdialCore/Algorithm/Alignment/SpotAction.cs, two affected methods:

• MatchResultAnnotationDeduplicator.Process (lines 32–110)
• MspAnnotationDeduplicator.Process (lines 118–192)

Call Chain

GcmsMethodModel.RunAlignment()
  → PeakAligner.Alignment()
    → AlignmentRefiner.Refine()
      → Deduplicate()                     // executes at ~75% alignment progress
        → MatchResultAnnotationDeduplicator.Process()  // ← crash

Root Cause

Deduplication runs three passes: by LibraryID → by InChIKey → by Name. The second and third passes guard against emptiness with if (spotList.Count > 0); the first pass does not:

// First pass "by LibraryID" — unguarded
var spotList = spots.Where(n => n.IsReferenceMatched(_evaluator) 
    && !n.Name.StartsWith("Putative"))
    .OrderByDescending(...).ToList();
var currentLibraryId = spotList[0].MatchResults.Representative.LibraryID; // ← empty-list crash

// Second and third passes — guarded ✓
if (spotList.Count > 0) { ... }

When no alignment spots pass the IsReferenceMatched filter, spotList is empty. This can happen with an unloaded reference library, overly strict matching parameters, or compounds absent from the library.

Fix

public void Process(IEnumerable<AlignmentSpotProperty> spots) {
    var spotList = spots.Where(...).OrderByDescending(...).ToList();
    if (spotList.Count == 0) return;  // ← added
    // ... remainder unchanged
}

MspAnnotationDeduplicator.Process requires the same fix.

Data Flow After Fix

Deduplicate's sole purpose is tagging duplicate-matching spots with a "Putative:" prefix. When no spots pass the filter, Process() returns early → zero modifications → alignment table fully unchanged. Zero data loss.

---

Fix Priority

1. P0 MSDecHandler.getRefinedModelChromatograms() — add empty-list return guard
2. P0 MatchResultAnnotationDeduplicator.Process() — add empty guard to first pass
3. P1 MspAnnotationDeduplicator.Process() — same
4. P1 src/MSDIAL4/MsdialGcmsProcessStandard/Algorithm/Deconvolution.cs — same defect in MS-DIAL 4

---

CLI Version Impact

The CLI uses the same FileProcess and PeakAligner code paths as the GUI via ProcessRunner. Since both bugs reside in the shared MsdialCore library:

Bug	GUI	CLI	Fix file	Single change covers
Bug 1 (MSDec)	✅	✅	MsdialCore/MSDec/MSDecHandler.cs	GUI + CLI
Bug 2 (Alignment)	✅	✅	MsdialCore/Algorithm/Alignment/SpotAction.cs	GUI + CLI (all modes)

Bug 1 affects GC-MS mode only; Bug 2 affects all mass-spectrometry modes' alignment dedup.

---

Note

Per the project's CONTRIBUTING.md, bug reports should be submitted via GitHub Issues. This document serves as technical analysis to support an issue filing, not as a substitute. Before submitting a PR, verify the build under the Debug vendor unsupported configuration and run existing tests in tests/MSDIAL5/MsdialCoreTests to confirm no regressions.

---

Analysis date: 2026-06-30 · Repository: MsdialWorkbench (branch fix-740, commit 77a42a8)