cross-sample-feature-alignment
Summary
Aligns detected LC-MS features across multiple samples to construct a unified feature list with consistent m/z and retention time coordinates, enabling quantitative comparison of molecular abundances across the cohort. This is a critical preprocessing step in untargeted metabolomics that enables downstream bioassay integration and molecular networking.
When to use
You have run mass detection and chromatogram building independently on each LC-MS/MS sample and produced per-sample feature lists with m/z, retention time, and intensity values. You need a single unified feature table with per-sample abundance columns to enable cross-sample statistical comparisons, quality control filtering, and bioassay correlation in bioactive molecular networking workflows.
When NOT to use
- Input is already a pre-aligned feature table or was generated by a previous alignment step — re-aligning may introduce coordinate drift or duplicate features.
- Working with targeted metabolomics data with pre-defined m/z and retention time windows — use exact-match lookup instead.
- Samples have drastically different chromatographic conditions or instrumental parameters that make retention time alignment unreliable — consider sample-specific processing or manual curation first.
Inputs
- per-sample mass detection results (peak lists with m/z and retention time)
- per-sample chromatogram features (intensity values indexed by m/z and retention time)
Outputs
- aligned feature quantification matrix (m/z, retention time, per-sample abundance columns)
- unified feature list with consensus coordinates
How to apply
Load the per-sample feature lists (each containing m/z, retention time, and intensity) into MZmine2 or Optimus and apply the alignment algorithm, which groups peaks across all samples using mass tolerance (typically 5 ppm or less) and retention time tolerance windows to match features with equivalent m/z and chromatographic position. The algorithm produces a single aligned feature matrix where rows are unique features (identified by consensus m/z and retention time) and columns are per-sample abundances. After alignment, apply the 'fill missing feature values' step to impute zeros for features detected in some samples but not others, ensuring the final quantification matrix has no missing values and is suitable for normalization and downstream statistical analysis.
Related tools
- MZmine2 (performs feature detection, alignment, and gap-filling; exports aligned feature quantification matrix) — http://mzmine.github.io/
- Optimus (KNIME-based workflow wrapping OpenMS algorithms for feature alignment and quantification with optional filtering and normalization) — https://github.com/MolecularCartography/Optimus
- OpenMS (underlying C++ library providing state-of-the-art feature detection and alignment algorithms leveraged by Optimus)
Evaluation signals
- Aligned feature table has no null or missing values in the intensity matrix after gap-filling; all features are represented in all samples.
- Feature coordinates (m/z and retention time) are consistent across all samples for each feature row — verify by checking that the same feature ID has identical m/z and RT in every sample column.
- Number of aligned features is reasonable relative to the number of per-sample features detected — typically 70–90% of individual features align across samples (remaining are sample-specific or noise).
- Distribution of feature intensities across samples passes visual or statistical inspection (e.g., heatmap, PCA) — no unexpected clustering or outliers caused by alignment artifacts.
- Reproducibility check: pooled quality control (QC) samples show high correlation in feature intensities across replicates (cosine similarity > 0.8 or Pearson r > 0.9).
Limitations
- Alignment accuracy depends critically on retention time reproducibility across LC runs; drift > 0.5 min or LC column degradation can cause misalignment or missed features.
- Mass tolerance and retention time tolerance windows are not adaptive; features at the margin of these windows (e.g., exactly 5 ppm away) may be ambiguously aligned or split into multiple features.
- Gap-filling by zero-imputation can bias downstream statistics if features are missing non-randomly (e.g., always absent in low-abundance samples); consider dropout mechanisms in QC filtering.
- The workflow does not perform MS/MS validation of aligned features; putative annotation requires separate matching to spectral libraries (e.g., via GNPS) or in-silico prediction tools.
Evidence
- [other] Build chromatogram features by grouping detected peaks across retention time and m/z dimensions. 4. Align features across samples to construct a unified feature list.: "Build chromatogram features by grouping detected peaks across retention time and m/z dimensions. 4. Align features across samples to construct a unified feature list."
- [other] Fill missing feature values across samples where peaks were not detected. 6. Export the processed feature table with m/z, retention time, and per-sample abundance columns to a quantification file.: "Fill missing feature values across samples where peaks were not detected. 6. Export the processed feature table with m/z, retention time, and per-sample abundance columns to a quantification file."
- [readme] Alignment and quantification of features detected across all the runs. 3. (Optional) Visualization of the timeline of internal standards intensities.: "Alignment and quantification of features detected across all the runs. 3. (Optional) Visualization of the timeline of internal standards intensities."
- [readme] Optimus employes the state-of-the-art LC-MS feature detection and quantification algorithms by OpenMS: "Optimus employes the state-of-the-art LC-MS feature detection and quantification algorithms by OpenMS"
- [readme] a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS: "a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS"
1---2name: cross-sample-feature-alignment3description: Use when you have run mass detection and chromatogram building independently on each LC-MS/MS sample and produced per-sample feature lists with m/z, retention time, and intensity values.4license: CC-BY-4.05---67# cross-sample-feature-alignment89## Summary1011Aligns detected LC-MS features across multiple samples to construct a unified feature list with consistent m/z and retention time coordinates, enabling quantitative comparison of molecular abundances across the cohort. This is a critical preprocessing step in untargeted metabolomics that enables downstream bioassay integration and molecular networking.1213## When to use1415You have run mass detection and chromatogram building independently on each LC-MS/MS sample and produced per-sample feature lists with m/z, retention time, and intensity values. You need a single unified feature table with per-sample abundance columns to enable cross-sample statistical comparisons, quality control filtering, and bioassay correlation in bioactive molecular networking workflows.1617## When NOT to use1819- Input is already a pre-aligned feature table or was generated by a previous alignment step — re-aligning may introduce coordinate drift or duplicate features.20- Working with targeted metabolomics data with pre-defined m/z and retention time windows — use exact-match lookup instead.21- Samples have drastically different chromatographic conditions or instrumental parameters that make retention time alignment unreliable — consider sample-specific processing or manual curation first.2223## Inputs2425- per-sample mass detection results (peak lists with m/z and retention time)26- per-sample chromatogram features (intensity values indexed by m/z and retention time)2728## Outputs2930- aligned feature quantification matrix (m/z, retention time, per-sample abundance columns)31- unified feature list with consensus coordinates3233## How to apply3435Load the per-sample feature lists (each containing m/z, retention time, and intensity) into MZmine2 or Optimus and apply the alignment algorithm, which groups peaks across all samples using mass tolerance (typically 5 ppm or less) and retention time tolerance windows to match features with equivalent m/z and chromatographic position. The algorithm produces a single aligned feature matrix where rows are unique features (identified by consensus m/z and retention time) and columns are per-sample abundances. After alignment, apply the 'fill missing feature values' step to impute zeros for features detected in some samples but not others, ensuring the final quantification matrix has no missing values and is suitable for normalization and downstream statistical analysis.3637## Related tools3839- **MZmine2** (performs feature detection, alignment, and gap-filling; exports aligned feature quantification matrix) — http://mzmine.github.io/40- **Optimus** (KNIME-based workflow wrapping OpenMS algorithms for feature alignment and quantification with optional filtering and normalization) — https://github.com/MolecularCartography/Optimus41- **OpenMS** (underlying C++ library providing state-of-the-art feature detection and alignment algorithms leveraged by Optimus)4243## Evaluation signals4445- Aligned feature table has no null or missing values in the intensity matrix after gap-filling; all features are represented in all samples.46- Feature coordinates (m/z and retention time) are consistent across all samples for each feature row — verify by checking that the same feature ID has identical m/z and RT in every sample column.47- Number of aligned features is reasonable relative to the number of per-sample features detected — typically 70–90% of individual features align across samples (remaining are sample-specific or noise).48- Distribution of feature intensities across samples passes visual or statistical inspection (e.g., heatmap, PCA) — no unexpected clustering or outliers caused by alignment artifacts.49- Reproducibility check: pooled quality control (QC) samples show high correlation in feature intensities across replicates (cosine similarity > 0.8 or Pearson r > 0.9).5051## Limitations5253- Alignment accuracy depends critically on retention time reproducibility across LC runs; drift > 0.5 min or LC column degradation can cause misalignment or missed features.54- Mass tolerance and retention time tolerance windows are not adaptive; features at the margin of these windows (e.g., exactly 5 ppm away) may be ambiguously aligned or split into multiple features.55- Gap-filling by zero-imputation can bias downstream statistics if features are missing non-randomly (e.g., always absent in low-abundance samples); consider dropout mechanisms in QC filtering.56- The workflow does not perform MS/MS validation of aligned features; putative annotation requires separate matching to spectral libraries (e.g., via GNPS) or in-silico prediction tools.5758## Evidence5960- [other] Build chromatogram features by grouping detected peaks across retention time and m/z dimensions. 4. Align features across samples to construct a unified feature list.: "Build chromatogram features by grouping detected peaks across retention time and m/z dimensions. 4. Align features across samples to construct a unified feature list."61- [other] Fill missing feature values across samples where peaks were not detected. 6. Export the processed feature table with m/z, retention time, and per-sample abundance columns to a quantification file.: "Fill missing feature values across samples where peaks were not detected. 6. Export the processed feature table with m/z, retention time, and per-sample abundance columns to a quantification file."62- [readme] Alignment and quantification of features detected across all the runs. 3. (*Optional*) Visualization of the timeline of internal standards intensities.: "Alignment and quantification of features detected across all the runs. 3. (*Optional*) Visualization of the timeline of internal standards intensities."63- [readme] Optimus employes the state-of-the-art LC-MS feature detection and quantification algorithms by OpenMS: "Optimus employes the state-of-the-art LC-MS feature detection and quantification algorithms by OpenMS"64- [readme] a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS: "a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS"
HolobiomicsLab 