HolobiomicsLab mass-track-consensus-computation
Summary
Compute consensus m/z values for aligned mass tracks across LC-MS samples by combining median and intensity-weighted estimates. This step finalizes MassGrid construction after pairwise or nearest-neighbor alignment, ensuring reproducible mass calibration across study cohorts.
When to use
After mass tracks have been aligned across all samples (either via pairwise alignment for ≤10 samples or nearest-neighbor clustering for larger cohorts), and you need to generate a single representative m/z per aligned bin for downstream feature extraction and annotation.
When NOT to use
- Input is already a finalized feature table; consensus m/z computation is part of the alignment phase, not post-alignment QC.
- Mass tracks have not yet been aligned across samples; compute alignment first using build_grid_sample_wise or build_grid_by_centroiding.
- Study contains only a single sample; consensus m/z is meaningful only when aggregating across multiple samples.
Inputs
- aligned_mass_track_bins (list of grouped mass tracks per consensus m/z bin)
- sample_membership_map (mapping of track IDs to sample origins)
- median_mz_per_bin (pre-computed median m/z for each aligned bin)
- intensity_mz_per_bin (m/z value at highest intensity for each bin)
Outputs
- consensus_mz_values (single representative m/z per aligned bin)
- mass_grid_mapping.csv (table of aligned track IDs, consensus m/z, sample membership)
How to apply
For each aligned bin of mass tracks (representing the same analyte m/z across samples), compute the consensus m/z as the mean of two quantities: (1) the median m/z of all tracks in that bin, and (2) the m/z value at the highest intensity within the bin. This dual-estimate approach balances robustness (median) against signal strength (intensity-weighted), reducing bias from outlier tracks or low-intensity measurements. The resulting consensus m/z is recorded alongside the sample membership and original track identifiers in the MassGrid output. This step is performed after systematic m/z recalibration (if pairwise differences exceed 1 ppm), ensuring the consensus is built on already-corrected m/z values.
Related tools
- asari MassGrid class (Provides build_grid_sample_wise and build_grid_by_centroiding methods to construct aligned bins; consensus computation integrates into add_sample and grid finalization) — https://github.com/shuzhao-li/asari
- asari mass_functions module (Supplies nn_cluster_by_mz_seeds for large-study clustering and utility functions for bin aggregation prior to consensus calculation) — https://github.com/shuzhao-li/asari
- Python (Execution environment; numpy/scipy used for median and intensity indexing operations)
Examples
from asari.mass_functions import build_grid_by_centroiding; mgrid = build_grid_by_centroiding(samples, parameters); mgrid.generate_output(outputdir)
Evaluation signals
- Consensus m/z values fall within 1 ppm of the median m/z in the corresponding bin (validates balance between the two estimates).
- All sample identifiers listed in mass_grid_mapping.csv match the input sample registry; no orphaned or duplicate entries.
- Consensus m/z values are monotonically increasing across bins (no inversions due to sorting or aggregation errors).
- Each aligned bin contains at least one track; isolated bins with single tracks should have consensus m/z equal to that track's (calibrated) m/z.
- mass_grid_mapping.csv has matching row count to the number of aligned bins; output is complete and non-redundant.
Limitations
- Consensus m/z is sensitive to outlier tracks with very high intensity or misaligned m/z; prior recalibration (if systematic difference > 1 ppm) is critical to avoid skewing the intensity-weighted component.
- For small aligned bins (e.g., present in only 1–2 samples), the consensus may not be stable; consider supplementary confidence intervals or sample-coverage thresholds.
- Method assumes high mass resolution (typically <5 ppm instrument error); low-resolution instruments may produce overlapping bins and artificially merged consensus m/z values.
- Bins generated by nearest-neighbor clustering (large studies) may vary in granularity depending on mz_tolerance and histogram-seed detection; consensus computation does not re-validate bin validity.
Evidence
- [methods] 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."
- [methods] Generate _mass_grid_mapping.csv documenting aligned mass track identifiers, consensus m/z values, and sample membership across the MassGrid: "Generate _mass_grid_mapping.csv documenting aligned mass track identifiers, consensus m/z values, and sample membership across the MassGrid."
- [intro] 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] recalibrate all sample m/z values if systematic difference exceeds 1 ppm: "recalibrate all sample m/z values if systematic difference exceeds 1 ppm"