mass-track-clustering
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
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"
1---2name: mass-track-clustering-23description: Use when 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.4license: CC-BY-4.05---67# mass-track-clustering89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Partition 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.1314## When to use1516After 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.1718## When NOT to use1920- The m/z range of the bin is already ≤ 2 × ppm tolerance — use single-track assignment directly.21- Data points are already assigned to known reference masses or spike-in standards — use targeted assignment instead of clustering.22- The bin contains only noise or very low-intensity points below min_intensity_threshold — filter or reject the bin before clustering.2324## Inputs2526- data bin (set of (m/z, scan_number, intensity) tuples from mzTree keyed by thousandth-m/z)27- ppm tolerance threshold (default 5 ppm for high-resolution Orbitrap)28- m/z histogram of the bin (for seed identification)29- mz_tolerance_minimum (minimum m/z gap to define separate peaks in histogram)3031## Outputs3233- list of mass tracks, each a (consensus_mz, intensity_vector) tuple34- track assignments for each input point (which cluster each (m/z, scan, intensity) belongs to)3536## How to apply3738First, 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.3940## Related tools4142- **pymzml** (Parse mzML files to retrieve MS1 spectra as (m/z, scan_number, intensity) tuples for input to bin construction)43- **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/asari44- **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/asari45- **asari chromatograms.extract_massTracks_** (Build final mass track objects (consensus_mz, intensity_vector) after clustering for each sample) — https://github.com/shuzhao-li/asari4647## Examples4849```50from 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]51```5253## Evaluation signals5455- Verify cluster counts match the number of distinct m/z peaks in the bin's histogram separated by ≥ mz_tolerance_minimum.56- Check that each cluster's consensus m/z lies within the spatial bounds of its assigned points (min_mz ≤ consensus ≤ max_mz).57- Confirm intensity vectors have no gaps within single tracks — missing scans should be zero, not omitted.58- Validate that all (m/z, scan, intensity) points from the input bin are assigned to exactly one cluster (no orphans, no duplicates).59- Cross-check that single-track bins (m/z range ≤ 2 × ppm) were assigned directly without invoking nn_cluster_by_mz_seeds, avoiding unnecessary computation.6061## Limitations6263- 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.64- 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).65- 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.66- 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.6768## Evidence6970- [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."71- [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"72- [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"73- [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"74- [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"
HolobiomicsLab