m/z-alignment-across-samples
Summary
Conditional alignment of mass tracks (extracted ion chromatograms) across LC-MS samples using either pairwise anchor-based or nearest-neighbor clustering strategies, selected by study size to balance statistical power with computational efficiency. Produces a MassGrid mapping that links aligned m/z values and sample membership.
When to use
After mass track construction for individual samples, when you need to establish consensus m/z values across a cohort of LC-MS samples to build a unified feature table. Apply this skill when sample count is known and you have extracted mass tracks with identified anchor mass tracks (13C/12C isotopes or Na/H adducts) for each sample.
When NOT to use
- Input is already a feature table or consensus m/z list (alignment already performed).
- Mass tracks have not yet been extracted or anchor mass tracks have not been identified.
- Study contains only a single sample (no cross-sample alignment needed).
Inputs
- Mass track list per sample (m/z, retention time, intensity values)
- Identified anchor mass tracks (13C/12C isotopes or Na/H adducts) per sample
- Sample count / study size metadata
- User-specified reference sample (optional)
Outputs
- MassGrid: aligned m/z consensus values with sample membership
- _mass_grid_mapping.csv: table of aligned mass track IDs, consensus m/z, and sample membership
- Recalibrated sample m/z values (if pairwise strategy)
How to apply
First, determine study size (sample count) to select alignment strategy: if ≤10 samples, use pairwise alignment with anchor mass track prioritization; otherwise use nearest-neighbor clustering. Identify the reference sample as the one with the highest number of anchor mass tracks, unless user-specified. For small studies, perform sample-wise pairwise alignment: align anchor mass tracks between each sample and reference list first, then recalibrate all sample m/z values if systematic difference exceeds 1 ppm, then align remaining mass tracks. For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance. Construct consensus m/z for each aligned bin as the mean of the median m/z and m/z at highest intensity. Generate _mass_grid_mapping.csv documenting aligned mass track identifiers, consensus m/z values, and sample membership.
Related tools
- asari mass_functions module (nn_cluster_by_mz_seeds) (Performs nearest-neighbor clustering of mass tracks by m/z seeds for large studies (>10 samples)) — https://github.com/shuzhao-li/asari
- asari MassGrid class (build_grid_sample_wise, add_sample, build_grid_by_centroiding, bin_track_mzs) (Core classes for constructing and managing aligned mass track grid across samples) — https://github.com/shuzhao-li/asari
- Python (Implementation language for alignment algorithms)
Examples
From Python: `from asari.mass_functions import nn_cluster_by_mz_seeds; from asari.workflow import MassGrid; grid = MassGrid(); grid.build_grid_sample_wise(samples, sample_count=5, mz_tolerance=5) if sample_count <= 10 else grid.build_grid_by_centroiding(samples, mz_tolerance=5)`
Evaluation signals
- MassGrid contains no missing consensus m/z values for bins with ≥1 sample membership.
- _mass_grid_mapping.csv row count matches total unique aligned mass track identifiers.
- Pairwise strategy (≤10 samples): anchor mass tracks aligned first; verify no m/z recalibrations for differences <1 ppm.
- Nearest-neighbor strategy (>10 samples): verify histogram-based seed m/z separated by ≥mz_tolerance; consensus m/z is within expected range of input sample m/z values.
- Sample membership is complete: all original samples appear in at least one grid row.
Limitations
- Small study threshold (≤10 samples) is fixed; studies near boundary may benefit from sensitivity analysis on strategy choice.
- Anchor mass track identification depends on presence of 13C/12C isotopes or Na/H adducts; samples without detectable anchors may have degraded alignment.
- Nearest-neighbor clustering sensitivity to mz_tolerance parameter; inappropriate tolerance values can merge distinct m/z or fragment bins.
- Systematic m/z differences >1 ppm in pairwise strategy trigger recalibration but may indicate instrument drift or data quality issues unaddressed by this step alone.
Evidence
- [other] if ≤10 samples, use pairwise alignment with anchor mass track prioritization; else use nearest-neighbor clustering method: "if ≤10 samples, use pairwise alignment with anchor mass track prioritization; else use nearest-neighbor clustering method"
- [other] Identify reference sample as the one with highest number of anchor mass tracks (13C/12C isotopes or Na/H adducts) unless user-specified: "Identify reference sample as the one with highest number of anchor mass tracks (13C/12C isotopes or Na/H adducts) unless user-specified"
- [other] For small studies, perform pairwise sample-wise alignment: align anchor mass tracks first between each sample and reference list, recalibrate all sample m/z values if systematic difference exceeds 1 ppm, then align remaining mass tracks: "For small studies, perform pairwise sample-wise alignment: align anchor mass tracks first between each sample and reference list, recalibrate all sample m/z values if systematic difference exceeds 1"
- [other] For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance: "For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance"
- [other] Construct consensus m/z for each aligned bin as mean of median m/z and m/z at highest intensity: "Construct consensus m/z for each aligned bin as mean of median m/z and m/z at highest intensity"
- [other] Asari is designed as a scalable program that uses performance-conscious approaches, operating with disciplined memory and CPU use, enabling it to handle studies of varying sizes through conditional algorithm selection: "Asari is designed as a scalable program that uses performance-conscious approaches, operating with disciplined memory and CPU use, enabling it to handle studies of varying sizes through conditional"
- [readme] Taking advantage of high mass resolution to prioritize mass separation and alignment: "Taking advantage of high mass resolution to prioritize mass separation and alignment"
- [methods] Aignment of mass tracks across samples, resulting in the MassGrid: "Aignment of mass tracks across samples, resulting in the MassGrid"
1---2name: m-z-alignment-across-samples-23description: Use when after mass track construction for individual samples, when you need to establish consensus m/z values across a cohort of LC-MS samples to build a unified feature table.4license: CC-BY-4.05---67# m/z-alignment-across-samples89## Summary1011Conditional alignment of mass tracks (extracted ion chromatograms) across LC-MS samples using either pairwise anchor-based or nearest-neighbor clustering strategies, selected by study size to balance statistical power with computational efficiency. Produces a MassGrid mapping that links aligned m/z values and sample membership.1213## When to use1415After mass track construction for individual samples, when you need to establish consensus m/z values across a cohort of LC-MS samples to build a unified feature table. Apply this skill when sample count is known and you have extracted mass tracks with identified anchor mass tracks (13C/12C isotopes or Na/H adducts) for each sample.1617## When NOT to use1819- Input is already a feature table or consensus m/z list (alignment already performed).20- Mass tracks have not yet been extracted or anchor mass tracks have not been identified.21- Study contains only a single sample (no cross-sample alignment needed).2223## Inputs2425- Mass track list per sample (m/z, retention time, intensity values)26- Identified anchor mass tracks (13C/12C isotopes or Na/H adducts) per sample27- Sample count / study size metadata28- User-specified reference sample (optional)2930## Outputs3132- MassGrid: aligned m/z consensus values with sample membership33- _mass_grid_mapping.csv: table of aligned mass track IDs, consensus m/z, and sample membership34- Recalibrated sample m/z values (if pairwise strategy)3536## How to apply3738First, determine study size (sample count) to select alignment strategy: if ≤10 samples, use pairwise alignment with anchor mass track prioritization; otherwise use nearest-neighbor clustering. Identify the reference sample as the one with the highest number of anchor mass tracks, unless user-specified. For small studies, perform sample-wise pairwise alignment: align anchor mass tracks between each sample and reference list first, then recalibrate all sample m/z values if systematic difference exceeds 1 ppm, then align remaining mass tracks. For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance. Construct consensus m/z for each aligned bin as the mean of the median m/z and m/z at highest intensity. Generate _mass_grid_mapping.csv documenting aligned mass track identifiers, consensus m/z values, and sample membership.3940## Related tools4142- **asari mass_functions module (nn_cluster_by_mz_seeds)** (Performs nearest-neighbor clustering of mass tracks by m/z seeds for large studies (>10 samples)) — https://github.com/shuzhao-li/asari43- **asari MassGrid class (build_grid_sample_wise, add_sample, build_grid_by_centroiding, bin_track_mzs)** (Core classes for constructing and managing aligned mass track grid across samples) — https://github.com/shuzhao-li/asari44- **Python** (Implementation language for alignment algorithms)4546## Examples4748```49From Python: `from asari.mass_functions import nn_cluster_by_mz_seeds; from asari.workflow import MassGrid; grid = MassGrid(); grid.build_grid_sample_wise(samples, sample_count=5, mz_tolerance=5) if sample_count <= 10 else grid.build_grid_by_centroiding(samples, mz_tolerance=5)`50```5152## Evaluation signals5354- MassGrid contains no missing consensus m/z values for bins with ≥1 sample membership.55- _mass_grid_mapping.csv row count matches total unique aligned mass track identifiers.56- Pairwise strategy (≤10 samples): anchor mass tracks aligned first; verify no m/z recalibrations for differences <1 ppm.57- Nearest-neighbor strategy (>10 samples): verify histogram-based seed m/z separated by ≥mz_tolerance; consensus m/z is within expected range of input sample m/z values.58- Sample membership is complete: all original samples appear in at least one grid row.5960## Limitations6162- Small study threshold (≤10 samples) is fixed; studies near boundary may benefit from sensitivity analysis on strategy choice.63- Anchor mass track identification depends on presence of 13C/12C isotopes or Na/H adducts; samples without detectable anchors may have degraded alignment.64- Nearest-neighbor clustering sensitivity to mz_tolerance parameter; inappropriate tolerance values can merge distinct m/z or fragment bins.65- Systematic m/z differences >1 ppm in pairwise strategy trigger recalibration but may indicate instrument drift or data quality issues unaddressed by this step alone.6667## Evidence6869- [other] if ≤10 samples, use pairwise alignment with anchor mass track prioritization; else use nearest-neighbor clustering method: "if ≤10 samples, use pairwise alignment with anchor mass track prioritization; else use nearest-neighbor clustering method"70- [other] Identify reference sample as the one with highest number of anchor mass tracks (13C/12C isotopes or Na/H adducts) unless user-specified: "Identify reference sample as the one with highest number of anchor mass tracks (13C/12C isotopes or Na/H adducts) unless user-specified"71- [other] For small studies, perform pairwise sample-wise alignment: align anchor mass tracks first between each sample and reference list, recalibrate all sample m/z values if systematic difference exceeds 1 ppm, then align remaining mass tracks: "For small studies, perform pairwise sample-wise alignment: align anchor mass tracks first between each sample and reference list, recalibrate all sample m/z values if systematic difference exceeds 1"72- [other] For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance: "For large studies, bin all sample mass tracks by m/z using nearest-neighbor clustering with histogram-based m/z seed detection, ensuring 2 peaks separated by at least mz_tolerance"73- [other] Construct consensus m/z for each aligned bin as mean of median m/z and m/z at highest intensity: "Construct consensus m/z for each aligned bin as mean of median m/z and m/z at highest intensity"74- [other] Asari is designed as a scalable program that uses performance-conscious approaches, operating with disciplined memory and CPU use, enabling it to handle studies of varying sizes through conditional algorithm selection: "Asari is designed as a scalable program that uses performance-conscious approaches, operating with disciplined memory and CPU use, enabling it to handle studies of varying sizes through conditional"75- [readme] Taking advantage of high mass resolution to prioritize mass separation and alignment: "Taking advantage of high mass resolution to prioritize mass separation and alignment"76- [methods] Aignment of mass tracks across samples, resulting in the MassGrid: "Aignment of mass tracks across samples, resulting in the MassGrid"
HolobiomicsLab