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."
1---2name: retention-time-mz-alignment3description: Use 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.4license: CC-BY-4.05---67# retention-time-mz-alignment89## Summary1011Autonomous 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.1213## When to use1415Apply 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.1617## When NOT to use1819- Input is already a processed feature table (e.g., from xcms, MS-DIAL, or another peak picker) — skip directly to downstream annotation or modeling.20- Targeted LC/MS or SRM/MRM data where m/z and RT windows are pre-defined — mzLearn is designed for untargeted discovery.21- Very small cohorts (<5 files) where batch drift estimation is unreliable or where manual parameter tuning is more practical than automated learning.2223## Inputs2425- Raw LC/MS data files (mzML or mzXML format)26- Multi-sample cohort (no minimum size, but scalability tested to 2,075 files)2728## Outputs2930- Feature abundance table (CSV or mzTab format) with columns: median retention time, m/z value, normalized intensity per sample31- Detected metabolite signals defined by m/z and RT coordinates3233## How to apply3435Load 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.3637## Related tools3839- **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/mzEmbed40- **mzEmbed** (Framework that integrates mzLearn outputs (aligned feature matrices) for downstream pre-trained generative model development and fine-tuning) — github.com/ReviveMed/mzEmbed4142## Examples4344```45python -m mz_learn.run_signal_detection --input_dir /path/to/raw_mzml_files --output_csv /path/to/feature_table.csv46```4748## Evaluation signals4950- 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).51- 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.52- 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.53- 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.54- 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.5556## Limitations5758- 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.59- 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.60- 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.61- No built-in metabolite annotation or MS/MS spectral matching; the feature table must be passed to downstream annotation tools for compound identification.6263## Evidence6465- [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."66- [readme] iteratively learning signal characteristics to ensure high-quality signal detection: "iteratively learning signal characteristics to ensure high-quality signal detection"67- [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."68- [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."69- [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)."70- [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."
HolobiomicsLab