# Mass Tolerance Parameter Calibration

> Use when when converting raw line-scan mass spectrometry imaging data (Agilent .d, Bruker .tsf/.baf/.tdf, Thermo .raw, or .mzML formats) and must decide which m/z values from a reference mass list correspond to peaks in the raw spectra.

- Skill: `holobiomicslab/mass-tolerance-parameter-calibration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-tolerance-parameter-calibration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-tolerance-parameter-calibration/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-tolerance-parameter-calibration

---


# mass-tolerance-parameter-calibration

## Summary

Calibrate mass-to-charge (m/z) and ion mobility tolerance windows for matching observed spectra against a reference mass list during line-scan MSI data processing. Correct tolerance settings are critical for accurate feature extraction and prevent false positive or false negative ion assignments.

## When to use

When converting raw line-scan mass spectrometry imaging data (Agilent .d, Bruker .tsf/.baf/.tdf, Thermo .raw, or .mzML formats) and must decide which m/z values from a reference mass list correspond to peaks in the raw spectra. Tolerances are required separately for MS1 precursor ions, MS2 fragment ions, and ion mobility dimensions when applicable.

## When NOT to use

- Input is already a pre-processed feature table or image matrix — tolerance calibration applies only to raw spectrum–to–mass list matching.
- Mass list file is absent or malformed — tolerance parameters cannot be applied without a reference list to match against.
- Ion mobility dimension is not present in the raw data — mobility_tolerance and mobility_tolerance_units should not be specified.

## Inputs

- Input file path (raw MSI data: Agilent .d, Bruker .tsf/.baf/.tdf, Thermo .raw, or .mzML)
- Mass list file (Excel or CSV with m/z, precursor m/z, fragment m/z, and/or ion mobility columns)
- Instrument mass accuracy specification (ppm or m/z error)

## Outputs

- Matched m/z–intensity pairs within tolerance windows for each spatial pixel
- 3D pixel array of shape (n+1, y, x) where n is the number of matched masses (plus one TIC image)
- JSON metadata file recording tolerance parameter values used for reproducibility

## How to apply

Define three independent mass tolerance parameters before calling get_image_data(): (1) mass_tolerance_MS1 and mass_tolerance_MS1_units for matching m/z values in MS1 spectra (typically ppm or mz); (2) mass_tolerance_prec and mass_tolerance_prec_units for precursor ions in MS2 spectra; (3) mass_tolerance_frag and mass_tolerance_frag_units for fragment ions in MS2 spectra. If ion mobility data is present (e.g., TIMS), also set mobility_tolerance and mobility_tolerance_units (1/K0 or μs). These tolerances act as match windows: a peak in the raw spectrum is assigned to a mass list entry only if its observed m/z (or mobility value) falls within the tolerance window of the reference value. Tighter tolerances reduce false positives but risk missing true signals; looser tolerances increase sensitivity but risk spurious assignments. Choose tolerances based on your instrument's mass accuracy specification and the expected resolution of your MSI acquisition.

## Related tools

- **MSIGen** (Calls get_image_data(verbose=True) with mass tolerance parameters to extract and match spectra against mass list within the specified windows) — https://github.com/LabLaskin/MSIGen
- **pyBaf2Sql** (Decodes Bruker .baf files to extract raw spectra for tolerance-based matching) — https://github.com/gtluu/pyBaf2Sql
- **Python** (Runtime environment (≥3.9 and ≤3.11) for defining and passing tolerance parameters to MSIGen)

## Examples

```
MSIGen_generator = msigen(example_file='sample.d', mass_list_dir='masses.csv', mass_tolerance_MS1=5, mass_tolerance_MS1_units='ppm', mass_tolerance_prec=10, mass_tolerance_prec_units='ppm', mass_tolerance_frag=20, mass_tolerance_frag_units='ppm', img_height=10, img_width=10); metadata, pixels = MSIGen_generator.get_image_data(verbose=True)
```

## Evaluation signals

- Verify that the output 3D pixel array has shape (n+1, y, x) where n equals the number of masses in the reference list successfully matched within tolerance windows; dimension mismatch indicates tolerance miscalibration or mass list parsing failure.
- Check that pixels_metadata.json contains recorded values for all tolerance parameters (mass_tolerance_MS1, mass_tolerance_prec, mass_tolerance_frag, mobility_tolerance if applicable) for reproducibility.
- Visually inspect ion images for expected signal distribution and absence of obvious artifacts; excessively sparse images suggest tolerances too tight; noisy or chemically implausible images suggest tolerances too loose.
- Cross-validate by re-running with tighter and looser tolerance bounds (e.g., ±50% adjustment) and comparing output TIC and ion image intensities; large changes indicate parameter sensitivity.
- If external reference imaging data or known spatial annotations exist, compare the spatial patterns in tolerance-matched images to the ground truth; correlation or AUC should remain high across reasonable tolerance ranges.

## Limitations

- Tolerance values are fixed across all spectra in the dataset; dynamic, spectrum-dependent calibration is not supported by MSIGen.
- No automated tolerance optimization is provided; users must select values a priori based on instrument specifications or manual calibration experiments.
- Separate tolerances for MS1, precursor, and fragment ions require prior knowledge of whether the raw data contains MS2 spectra; inapplicable tolerances are silently ignored.
- Ion mobility tolerance relies on accurate mobility calibration in the raw file; uncalibrated or poorly calibrated mobility axes will yield spurious or missed matches even with correct tolerance windows.

## Evidence

- [other] Define processing parameters: specify the input file path (Agilent .d, Bruker .tsf/.baf/.tdf, Thermo .raw, or .mzML), mass list file (Excel or CSV with m/z, precursor m/z, fragment m/z, and/or ion mobility columns), and MS1 mass tolerance (ppm or mz), precursor ion tolerance, fragment ion tolerance, and mobility tolerance (1/K0 or μs).: "mass list file (Excel or CSV with m/z, precursor m/z, fragment m/z, and/or ion mobility columns), and MS1 mass tolerance (ppm or mz), precursor ion tolerance, fragment ion tolerance, and mobility"
- [other] match m/z values and mobility values within tolerances, bin pixels spatially, and generate a 3D array of shape (n+1, y, x) where n is the number of masses plus one TIC image.: "match m/z values and mobility values within tolerances, bin pixels spatially, and generate a 3D array of shape (n+1, y, x) where n is the number of masses plus one TIC image"
- [methods] Mass tolerance filtering for MS1 spectra  [section=methods; evidence='mass_tolerance_MS1, mass_tolerance_MS1_units for matching m/z values in MS1 spectra']; Precursor ion mass tolerance filtering  [section=methods; evidence='mass_tolerance_prec, mass_tolerance_prec_units for precursor ions in MS2 spectra']; Fragment ion mass tolerance filtering  [section=methods; evidence='mass_tolerance_frag, mass_tolerance_frag_units for fragment ions in MS2 spectra']; Ion mobility tolerance filtering  [section=methods; evidence='mobility_tolerance, mobility_tolerance_units for matching ion mobility values']: "mass_tolerance_MS1, mass_tolerance_MS1_units for matching m/z values in MS1 spectra; mass_tolerance_prec, mass_tolerance_prec_units for precursor ions in MS2 spectra; mass_tolerance_frag,"
- [other] Initialize the msigen object with all parameters and call get_image_data(verbose=True) to extract spectra, match m/z values and mobility values within tolerances: "Initialize the msigen object with all parameters and call get_image_data(verbose=True) to extract spectra, match m/z values and mobility values within tolerances"