Mass track extraction and binning

mass-track-extraction-and-binning

Summary

Extract and bin mass tracks (extracted ion chromatograms, EICs) from individual LC-MS samples by parsing mzML files, binning m/z values at high resolution (0.001 amu), and clustering overlapping m/z traces using nearest-neighbor methods. This foundational step produces raw mass tracks that serve as input to cross-sample alignment.

When to use

When you have centroid mzML files from LC-MS metabolomics acquisition and need to construct sample-level mass tracks before cross-sample alignment. Specifically: you are starting fresh with vendor-converted or pre-processed mzML input; you have not yet built a unified m/z grid across samples; and you need to preserve individual sample m/z calibration and chromatographic resolution for later anchor-track detection and MassGrid construction.

When NOT to use

• Input is already a feature table or pre-aligned MassGrid—skip to feature detection.
• Profile-mode (not centroid) mzML files—requires different peak-picking strategy.
• Raw vendor files (.RAW, .d) without prior mzML conversion—first convert using ThermoRawFileParser or ProteoWizard msconvert.

Inputs

• centroid mzML file (single sample)
• m/z binning resolution parameter (default 0.001 amu)
• nearest-neighbor clustering seed set (m/z values)

Outputs

• mass tracks (EICs) per sample: list of (m/z_bin_id, chromatogram_vector, rt_values)
• per-sample m/z inventory: mapping of binned m/z to track identifiers
• sample-level metadata: acquisition parameters, scan count, m/z range

How to apply

Parse each mzML file using pymzml to extract m/z and intensity pairs across all scans. Bin m/z values at 0.001 amu resolution (thousandth_bins) by merging adjacent bins within tolerance and resolving overlapping m/z values using nearest-neighbor clustering by m/z seeds (nn_cluster_by_mz_seeds). This produces a set of mass tracks per sample, each representing a distinct m/z value and its full retention-time intensity profile. The 0.001 amu binning leverages high mass resolution to prioritize mass separation; the clustering step removes redundant or near-duplicate tracks that would later complicate anchor detection and alignment. Store each mass track as a vector of (m/z, intensity, rt) tuples, indexed by m/z identifier and sample.

Related tools

• pymzml (Parse mzML files and extract m/z and intensity scan data)
• mass_functions.nn_cluster_by_mz_seeds (Cluster overlapping m/z values by nearest-neighbor algorithm to resolve redundant traces) — https://github.com/shuzhao-li/asari
• chromatograms.get_thousandth_bins (Bin m/z values at 0.001 amu resolution and merge adjacent bins within tolerance) — https://github.com/shuzhao-li/asari
• chromatograms.extract_massTracks_ (Extract full retention-time intensity profiles for each binned m/z across all scans) — https://github.com/shuzhao-li/asari
• ThermoRawFileParser (Convert Thermo .RAW files to centroid mzML prior to mass-track extraction) — https://github.com/compomics/ThermoRawFileParser
• ProteoWizard msconvert (Convert vendor data formats (e.g., .d, .raw, .mzXML) to centroid mzML) — https://proteowizard.sourceforge.io/tools.shtml

Examples

from asari.chromatograms import get_thousandth_bins, extract_massTracks_; mass_tracks = extract_massTracks_(mzml_file='sample_001.mzML', binning_resolution=0.001)

Evaluation signals

• Each sample produces ≥1 mass track; median track count scales with sample complexity and m/z range.
• No duplicate or near-identical m/z bins within a sample—clustering has resolved overlaps.
• Each mass track chromatogram vector length matches total scan count in the mzML file.
• m/z values in each bin are within ±0.0005 amu (half the binning tolerance) of the bin center.
• Mass tracks with median intensity below min_intensity_threshold (default 1e3 for Orbitrap) are flagged or removed in downstream QC.

Limitations

• High-resolution instruments (Orbitrap, Q-TOF) yield better mass separation at 0.001 amu; lower-resolution instruments may produce artificially merged or split tracks.
• Binning resolution is fixed (0.001 amu); compounds with m/z differences < 0.001 amu cannot be resolved at this step.
• Centroid mode is required; profile-mode data must be centroided first (e.g., by vendor software or ProteoWizard).
• Nearest-neighbor clustering is sensitive to seed selection; poor seed placement may result in incomplete clustering of true duplicates.

Evidence

• [other] Extract mass tracks from each sample using pymzml and bin m/z values at 0.001 amu resolution, merging adjacent bins within tolerance and applying nearest-neighbor clustering by m/z seeds to resolve overlapping m/z values: "Extract mass tracks from each sample using pymzml and bin m/z values at 0.001 amu resolution, merging adjacent bins within tolerance and applying nearest-neighbor clustering by m/z seeds to resolve"
• [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"
• [other] The default method uses pymzml to parse mzML files.: "The default method uses pymzml to parse mzML files."
• [other] We use ThermoRawFileParser to convert Thermo .RAW files to .mzML. Msconvert in ProteoWizard can handle the conversion of most vendor data formats.: "We use ThermoRawFileParser (https://github.com/compomics/ThermoRawFileParser) to convert Thermo .RAW files to .mzML. Msconvert in ProteoWizard (https://proteowizard.sourceforge.io/tools.shtml) can"
• [readme] Input data are centroid mzML files from LC, GC or DI-MS metabolomics.: "Input data are centroid mzML files from LC, GC or DI-MS metabolomics."