Mass Track Clustering

mass-track-clustering

Summary

Partition m/z data points within a mass bin into distinct mass tracks using nearest-neighbor clustering when high mass resolution cannot resolve all peaks within the bin's m/z range. This skill determines how many independent ion species coexist in the same chromatographic bin and assigns each a consensus m/z and intensity vector.

When to use

After constructing initial data bins from mzTree (indexed by int(mz × 1000)), determine whether a single bin contains one or multiple mass tracks. Apply clustering when the m/z range of points in a bin exceeds 2 × ppm tolerance (e.g., for 5 ppm tolerance, cluster if m/z span > 10 ppm), indicating that high mass resolution alone cannot separate all species and local structure must guide track identity.

When NOT to use

• The m/z range of the bin is already ≤ 2 × ppm tolerance — use single-track assignment directly.
• Data points are already assigned to known reference masses or spike-in standards — use targeted assignment instead of clustering.
• The bin contains only noise or very low-intensity points below min_intensity_threshold — filter or reject the bin before clustering.

Inputs

• data bin (set of (m/z, scan_number, intensity) tuples from mzTree keyed by thousandth-m/z)
• ppm tolerance threshold (default 5 ppm for high-resolution Orbitrap)
• m/z histogram of the bin (for seed identification)
• mz_tolerance_minimum (minimum m/z gap to define separate peaks in histogram)

Outputs

• list of mass tracks, each a (consensus_mz, intensity_vector) tuple
• track assignments for each input point (which cluster each (m/z, scan, intensity) belongs to)

How to apply

First, check the m/z range (max − min) of all data points in the candidate bin. If the range is ≤ 2 × ppm tolerance, assign all points to a single track with consensus m/z = mean(median_mz, mz_at_highest_intensity). Otherwise, apply nearest-neighbor clustering via nn_cluster_by_mz_seeds, using m/z histogram peaks separated by the mz_tolerance_minimum as seed points. This ensures clusters are anchored to actual density maxima in the m/z distribution rather than arbitrary boundaries. For each cluster, build a mass track as (consensus_mz, intensity_vector), using maximum intensity when multiple points exist in the same scan, and inserting zeros for missing scans across the full retention time range.

Related tools

• pymzml (Parse mzML files to retrieve MS1 spectra as (m/z, scan_number, intensity) tuples for input to bin construction)
• nn_cluster_by_mz_seeds (Perform nearest-neighbor clustering on m/z values using histogram peaks as seeds; core algorithm for multi-track assignment) — https://github.com/shuzhao-li/asari
• get_thousandth_bins (Construct initial data bins from mzTree by binning on int(mz × 1000) and merging adjacent bins, prerequisite for clustering decision) — https://github.com/shuzhao-li/asari
• asari chromatograms.extract_massTracks_ (Build final mass track objects (consensus_mz, intensity_vector) after clustering for each sample) — https://github.com/shuzhao-li/asari

Examples

from asari.chromatograms import extract_massTracks_; tracks = nn_cluster_by_mz_seeds(mz_list=bin_points, mz_tolerance_minimum=0.001, ppm=5); mass_tracks = [build_track(cluster) for cluster in tracks]

Evaluation signals

• Verify cluster counts match the number of distinct m/z peaks in the bin's histogram separated by ≥ mz_tolerance_minimum.
• Check that each cluster's consensus m/z lies within the spatial bounds of its assigned points (min_mz ≤ consensus ≤ max_mz).
• Confirm intensity vectors have no gaps within single tracks — missing scans should be zero, not omitted.
• Validate that all (m/z, scan, intensity) points from the input bin are assigned to exactly one cluster (no orphans, no duplicates).
• Cross-check that single-track bins (m/z range ≤ 2 × ppm) were assigned directly without invoking nn_cluster_by_mz_seeds, avoiding unnecessary computation.

Limitations

• Clustering sensitivity depends on mz_tolerance_minimum and histogram resolution; very low-abundance minor peaks may be missed if below noise floor or poorly resolved in histogram.
• Nearest-neighbor clustering assumes clear separation in m/z space; if multiple species have overlapping m/z ranges due to instrumental limitations, track assignment may be ambiguous and may benefit from isotope or adduct annotation (handled separately via khipu pre-annotation).
• Performance scales with bin size; bins with very high point density (e.g., from high-abundance compounds) may incur clustering overhead; asari mitigates this through maximum intensity selection per scan.
• Clustering does not use retention time information; co-eluting species at identical m/z cannot be resolved by this method alone and require MS/MS or auxiliary data.

Evidence

• [other] if m/z range is within 2 × ppm tolerance, create one track; otherwise apply nearest-neighbor clustering via nn_cluster_by_mz_seeds using m/z histogram peaks separated by mz tolerance minimum: "if m/z range is within 2 × ppm tolerance, create one track; otherwise apply nearest-neighbor clustering via nn_cluster_by_mz_seeds using m/z histogram peaks separated by mz tolerance minimum."
• [other] Build each mass track as (consensus_mz, intensity_vector) where consensus_mz = mean(median_mz, mz_at_highest_intensity), maximum intensity is used when multiple points exist in the same scan, and zeros are inserted for missing intensity values across full RT range.: "Build each mass track as (consensus_mz, intensity_vector) where consensus_mz = mean(median_mz, mz_at_highest_intensity), maximum intensity is used when multiple points exist in the same scan, and"
• [other] Index data points into an mzTree dictionary keyed by int(mz × 1000) for efficient retrieval. 3. Create data bins from mzTree using get_thousandth_bins, filtering for minimal required scan count and merging adjacent bins separated by ≤0.001 amu or within ppm tolerance.: "Index data points into an mzTree dictionary keyed by int(mz × 1000) for efficient retrieval. 3. Create data bins from mzTree using get_thousandth_bins, filtering for minimal required scan count and"
• [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] Asari builds mass tracks per data bin by leveraging high mass resolution to prioritize mass separation and alignment during the initial processing of MS1 spectra (m/z, scan number, intensity) from data files.: "Asari builds mass tracks per data bin by leveraging high mass resolution to prioritize mass separation and alignment during the initial processing of MS1 spectra (m/z, scan number, intensity) from"