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"