Retention time mz alignment

retention-time-mz-alignment

Summary

Autonomous correction of retention time (RT) and m/z drift across LC/MS samples caused by batch effects and run-order variation, enabling consistent feature detection and quantification without manual parameter tuning. This skill is essential for large-scale metabolomics cohorts where instrumental drift would otherwise compromise signal reproducibility.

When to use

Apply this skill when processing raw LC/MS data (mzML or mzXML format) from multi-sample cohorts where retention time or intensity drift is suspected due to batch effects, instrument calibration drift, or variable run order. This is particularly critical when handling large-scale datasets (hundreds to thousands of files) where manual per-file parameter adjustment is infeasible, or when downstream pre-trained generative models require aligned, normalized feature matrices as input.

When NOT to use

• Input is already a processed feature table (e.g., from xcms, MS-DIAL, or another peak picker) — skip directly to downstream annotation or modeling.
• Targeted LC/MS or SRM/MRM data where m/z and RT windows are pre-defined — mzLearn is designed for untargeted discovery.
• Very small cohorts (<5 files) where batch drift estimation is unreliable or where manual parameter tuning is more practical than automated learning.

Inputs

• Raw LC/MS data files (mzML or mzXML format)
• Multi-sample cohort (no minimum size, but scalability tested to 2,075 files)

Outputs

• Feature abundance table (CSV or mzTab format) with columns: median retention time, m/z value, normalized intensity per sample
• Detected metabolite signals defined by m/z and RT coordinates

How to apply

Load raw LC/MS data files in mzML format into mzLearn, which autonomously learns signal characteristics across the cohort through iterative refinement. The algorithm corrects for retention time drift by identifying consistent m/z and RT landmarks across samples and realigning features to median RT and m/z values within each feature group. Intensity normalization is performed across samples to correct for run-order and batch-dependent intensity drift. The output is a two-dimensional feature abundance table with median RT and m/z coordinates and normalized intensities, requiring no user-specified RT tolerance, mass tolerance, or smoothing parameters. This zero-parameter design ensures reproducible signal detection even in the absence of QC samples or reference standards.

Related tools

• mzLearn (Primary signal detection and RT/m/z drift correction engine; autonomously learns signal characteristics and iteratively refines alignment without user parameters) — github.com/ReviveMed/mzEmbed
• mzEmbed (Framework that integrates mzLearn outputs (aligned feature matrices) for downstream pre-trained generative model development and fine-tuning) — github.com/ReviveMed/mzEmbed

Examples

python -m mz_learn.run_signal_detection --input_dir /path/to/raw_mzml_files --output_csv /path/to/feature_table.csv

Evaluation signals

• Output feature table has shape [n_samples, n_features] with no missing values in RT or m/z columns; all intensities are normalized (e.g., z-scored or log-transformed with consistent mean and variance across samples).
• Retention time distribution across samples for the same m/z feature shows reduced variance post-correction compared to raw data; RT drift (linear or systematic shift across run order) is eliminated.
• Mass accuracy is preserved: m/z values remain within the instrument's typical accuracy range (e.g., <5 ppm for Orbitrap, <10 ppm for Q-TOF); no systematic m/z shift as a function of sample index or batch.
• Feature reproducibility: the same metabolite signal is detected across replicate or similar biological samples at consistent RT and m/z, with intensity variation explained by biological differences rather than instrumental drift.
• Output is compatible with downstream mzEmbed pretraining pipeline: feature matrix shape is [n_samples, feature_count] with no null entries, and intensity values are numeric and normalized.

Limitations

• Zero-parameter design assumes sufficient sample diversity and cohort size (tested at 2,075 files) to learn robust signal characteristics; very small or homogeneous cohorts may produce suboptimal alignment.
• Iterative learning depends on stable instrument performance; extreme instrumental malfunction or calibration failure during a run may introduce artifacts that mzLearn cannot correct without explicit user intervention.
• Output is a 2D feature table and does not include ion mobility, fragment spectra, or other orthogonal dimensions; multi-dimensional data (e.g., LC–IMS–MS) would require custom preprocessing.
• No built-in metabolite annotation or MS/MS spectral matching; the feature table must be passed to downstream annotation tools for compound identification.

Evidence

• [readme] mzLearn is a data-driven algorithm designed to autonomously detect metabolite signals from raw LC/MS data without requiring input parameters from the user.: "mzLearn is a data-driven algorithm designed to autonomously detect metabolite signals from raw LC/MS data without requiring input parameters from the user."
• [readme] iteratively learning signal characteristics to ensure high-quality signal detection: "iteratively learning signal characteristics to ensure high-quality signal detection"
• [readme] mzLearn autonomously refines signal detection, correcting for retention time (rt) and intensity drifts caused by batch effects and run order.: "mzLearn autonomously refines signal detection, correcting for retention time (rt) and intensity drifts caused by batch effects and run order."
• [readme] A two-dimensional table of detected features defined by median rt and m/z values, with normalized intensities across samples.: "A two-dimensional table of detected features defined by median rt and m/z values, with normalized intensities across samples."
• [readme] Capable of handling large-scale datasets (e.g., 2,075 files in a single run).: "Capable of handling large-scale datasets (e.g., 2,075 files in a single run)."
• [other] Apply the data-driven signal detection algorithm to identify peaks and features across the mass-to-charge and retention time dimensions without requiring manual parameter optimization.: "Apply the data-driven signal detection algorithm to identify peaks and features across the mass-to-charge and retention time dimensions without requiring manual parameter optimization."