# Mass Track Extraction And Binning

> Use when 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;

- Skill: `holobiomicslab/mass-track-extraction-and-binning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-track-extraction-and-binning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-track-extraction-and-binning/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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."