# Retention Time Mz Alignment

> 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.

- Skill: `holobiomicslab/retention-time-mz-alignment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/retention-time-mz-alignment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/retention-time-mz-alignment/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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."