Retention time calibration lowess regression

retention-time-calibration-lowess-regression

Summary

Uses LOWESS (Locally Weighted Scatterplot Smoothing) regression on high-selectivity landmark peaks to derive a retention-time mapping function between a reference sample and each current sample, enabling accurate RT alignment across LC-MS runs. This skill is essential for correcting systematic RT drift and enabling reliable feature matching in untargeted metabolomics.

When to use

Apply this skill after mass track construction and before composite map building, when you need to align retention times across multiple LC-MS samples. Trigger conditions: (1) you have identified high-selectivity landmark peaks (mSelectivity > 0.99) in a reference sample; (2) the same mass tracks are present across current samples; (3) systematic RT drift is expected between samples (common in multi-sample LC-MS experiments); (4) you need a smooth, continuous RT transformation rather than a discrete point-to-point mapping.

When NOT to use

• Fewer than ~5–10 high-selectivity landmark peaks are available; LOWESS requires sufficient data density to estimate local smoothing neighborhoods reliably.
• Retention time drift is non-smooth (e.g., abrupt jumps, multiple disconnected segments); LOWESS assumes local continuity and will produce artifacts across discontinuities.
• Mass tracks have not been pre-aligned across samples; this skill operates on already-matched mass tracks and cannot recover misaligned data.

Inputs

• reference sample with identified high-selectivity landmark peaks (mSelectivity > 0.99)
• current sample mass tracks aligned to reference mass grid
• pairs of (sample_RT_scan_number, reference_RT_scan_number) from good landmark peaks

Outputs

• rt_cal_dict: sparse scan-number mapping dictionary recording only differing RT values
• LOWESS regression function describing RT relationship between samples
• validated RT alignment with bounded extrapolation (±10% extension margins)

How to apply

First, identify high-selectivity landmark peaks in the reference sample using stringent criteria: mSelectivity > 0.99, minimum peak height satisfied (default 1e5 for Orbitrap), peak prominence > 20% of peak height, and one peak per mass track (see constructors.set_RT_reference and peaks.quick_detect_unique_elution_peak). Second, select good landmark peaks from the current sample by applying the same selectivity filter but restricted to mass tracks already aligned to reference landmarks (CompositeMap.calibrate_sample_RT). Third, perform LOWESS regression on pairs of (sample_RT_scan_number, reference_RT_scan_number) using scipy.signal.find_peaks, adding 10% extension boundaries at both ends to constrain convergence and prevent extrapolation artifacts. Fourth, export the fitted regression function as a sparse scan-number mapping dictionary (rt_cal_dict) that records only differing values and respects sample RT boundaries. Finally, validate by confirming that landmark peak scan numbers map correctly through rt_cal_dict and that extrapolation remains bounded within ±10% extension margins.

Related tools

• scipy.signal.find_peaks (Statistical peak detection on mass tracks to identify candidate landmarks before LOWESS fitting) — https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.find_peaks.html
• LOWESS (scipy implementation) (Core regression method to fit smooth RT transformation function from landmark peak pairs)
• asari (chromatograms.rt_lowess_calibration) (Wrapper function that applies LOWESS and exports rt_cal_dict sparse mapping) — https://github.com/shuzhao-li/asari
• asari (CompositeMap.calibrate_sample_RT) (Orchestrates selection of good landmark peaks and invokes LOWESS calibration for each sample) — https://github.com/shuzhao-li/asari
• asari (peaks.quick_detect_unique_elution_peak) (Identifies high-selectivity landmark peaks in reference sample using selectivity and prominence filters) — https://github.com/shuzhao-li/asari

Examples

from asari.chromatograms import rt_lowess_calibration; rt_cal_dict = rt_lowess_calibration(sample_rt_numbers, reference_rt_numbers, sample_rt_min, sample_rt_max)

Evaluation signals

• Landmark peak scan numbers from current sample map correctly through rt_cal_dict to reference RT space (visual inspection or numerical comparison within ±1–2 scan tolerance).
• rt_cal_dict contains only values that differ from identity mapping, indicating sparse representation and computational efficiency.
• Extrapolation remains bounded: all calculated RT values fall within sample RT boundaries ± 10% extension margins; no out-of-bounds predictions.
• LOWESS regression produces monotonically increasing or physically plausible RT transformation (no reversals or wild oscillations inconsistent with linear drift + local wobble).
• Post-alignment RT agreement: when identical metabolite features are detected in reference and current sample, their RT values in aligned space agree within expected instrument/column variability (typically < 0.5–2 min for LC-MS).

Limitations

• LOWESS performance degrades if fewer than ~5–10 high-selectivity landmarks are available; datasets with sparse or absent selective peaks may require alternative alignment strategies (e.g., direct sample–sample pairing).
• Extension boundaries (±10%) are fixed; if true RT drift extends beyond this margin, convergence may be compromised or extrapolation may fail.
• The method assumes landmark peaks are truly conserved across samples; if landmarks are affected by sample-specific suppression, ion competition, or contamination, spurious mappings can result.
• Sparse rt_cal_dict representation assumes interpolation between recorded scan numbers is valid; for highly nonlinear local drifts with few landmarks, interpolation error may accumulate.

Evidence

• [other] Identify high-selectivity landmark peaks in the reference sample using criteria: mSelectivity > 0.99, min_peak_height satisfied (default 1e5), prominence > 20% of peak height, and single peak per mass track.: "Identify high-selectivity landmark peaks in the reference sample using criteria: mSelectivity > 0.99, min_peak_height satisfied (default 1e5), prominence > 20% of peak height, and single peak per"
• [other] Select good landmark peaks from the current sample by applying the same selectivity criteria, restricted to mass tracks already aligned to the reference landmarks.: "Select good landmark peaks from the current sample by applying the same selectivity criteria, but restricted to mass tracks already aligned to the reference landmarks (see"
• [other] Perform LOWESS regression on pairs of (sample_RT_number, reference_RT_number), adding 10% extension boundaries at both ends to constrain convergence.: "Perform LOWESS regression (scipy.signal fitting) on the pairs of (sample_RT_number, reference_RT_number) from the good landmark peaks, adding 10% extension boundaries at both ends to constrain"
• [other] Export the regression function as a sparse scan-number mapping dictionary (rt_cal_dict) that records only differing values and stays within sample RT boundaries.: "Export the regression function as a sparse scan-number mapping dictionary (rt_cal_dict) that records only differing values and stays within sample RT boundaries (see"
• [other] Verify that rt_cal_dict enables accurate RT alignment by confirming landmark peak scan numbers map correctly and extrapolation remains bounded within ±10% extension margins.: "Validation: verify that rt_cal_dict enables accurate RT alignment by confirming landmark peak scan numbers map correctly and that extrapolation remains bounded within ±10% extension margins."
• [other] The retention-time alignment step performs a LOWESS regression to obtain a function describing the RT relationship between samples.: "The retention-time alignment step performs a LOWESS (Locally Weighted Scatterplot Smoothing) regression to obtain a function describing the RT relationship between samples."