ion-mobility-filtering-and-tolerance-tuning
Summary
Apply ion mobility (1/K0 or μs units) tolerance windows during mass spectrometry imaging data processing to selectively extract and bin spectra by collisional cross-section, improving spatial specificity and reducing chemical noise in line-scan MSI workflows. This skill is essential when processing ion-mobility-resolved MSI data from instruments like Bruker timsTOF or when distinguishing isomers and isobars that co-elute in m/z space but separate in mobility space.
When to use
Use this skill when your raw MSI dataset is acquired on an ion-mobility-enabled instrument (e.g., Bruker .baf, .tsf, or .tdf formats) and your analyte of interest has a known or experimentally determined ion mobility value (1/K0 or drift time μs). Apply it to reduce false positives from isobars, isomers, or background ions that share the same nominal m/z but have distinct mobility signatures, or when you need to extract mobility-resolved spatial images for a multi-pass analysis.
When NOT to use
- Your raw data is from a non-mobility-resolved instrument (e.g., standard Orbitrap, Q-TOF without ion mobility encoding) — mobility filtering requires multi-dimensional raw data.
- Your mass list file lacks a mobility column or reference mobility values are unavailable — filtering requires a target mobility to define the tolerance window.
- You are processing already-centroided or pre-filtered data where mobility information has been discarded — mobility filtering must occur at the raw spectral extraction stage.
Inputs
- raw MSI data file in ion-mobility format (.baf, .tsf, .tdf, .raw, or .mzML from an ion-mobility instrument)
- mass list file (Excel .xlsx or .csv) with at least m/z column and ion mobility column (1/K0 or μs)
- numeric mobility tolerance value (e.g., 0.02 1/K0)
- mobility tolerance units string ('1/K0' or 'μs')
Outputs
- pixels.npy: 3D NumPy array of shape (n+1, y, x) with spatial bins filtered and summed only over spectra within the mobility tolerance window
- pixels_metadata.json: JSON metadata file documenting applied mobility tolerance, units, and per-mass ion mobility range statistics
How to apply
During MSIGen initialization, define the mobility_tolerance parameter (numeric value) and mobility_tolerance_units parameter ('1/K0' or 'μs', depending on your instrument and calibration). These tolerances act as a ±window around the target mobility value: only spectra with ion mobility within [target_mobility − tolerance, target_mobility + tolerance] are retained and binned into the output pixel array. Set tolerance conservatively (typically 0.01–0.05 1/K0 or 1–5 μs) based on your instrument resolution and the reference mobility values in your mass list file (which should include a mobility column). Pass these parameters to the msigen() object, then call get_image_data(verbose=True) to apply the filter during spectral extraction and spatial binning; inspect the resulting pixels.npy array dimensions and metadata to confirm that the number of spatial voxels and intensity distributions reflect successful mobility filtering.
Related tools
- MSIGen (primary tool for applying ion mobility tolerance filtering during spectral extraction and spatial binning in line-scan MSI workflows) — https://github.com/LabLaskin/MSIGen
- pyBaf2Sql (underlying library for reading Bruker .baf files with ion mobility data access when processing Bruker instruments) — https://github.com/gtluu/pyBaf2Sql
- Python (runtime environment (version ≥3.9 and ≤3.11) for MSIGen and mobility tolerance parameter definition)
Examples
metadata, pixels = MSIGen_generator.get_image_data(verbose=True) where MSIGen_generator = msigen(example_file='sample.baf', mass_list_dir='masses.xlsx', mobility_tolerance=0.02, mobility_tolerance_units='1/K0', ...)
Evaluation signals
- Verify that pixels.npy has expected shape (n+1, y, x) where n is the number of masses in the mass list; mismatched dimensions indicate filtering errors.
- Check pixels_metadata.json for a 'mobility_tolerance' and 'mobility_tolerance_units' field matching your input parameters.
- Qualitatively inspect ion images (via vis.get_and_display_images) for spatial localization consistent with known sample structure; diffuse or absent signal suggests tolerance is too stringent or mobility value is incorrect.
- Compare per-pixel intensity distributions and TIC between a mobility-filtered run and a non-filtered run; mobility filtering should reduce background noise and increase contrast for the target analyte.
- Confirm that all output metadata records the actual mobility range (min/max observed 1/K0 or μs) for each extracted mass, falling within the specified tolerance window.
Limitations
- Ion mobility tolerance tuning is instrument and ion-specific; 1/K0 or μs values must be obtained experimentally or from reference databases, and calibration drift or unknown analyte structures can render pre-defined tolerances incorrect.
- MSIGen is designed with nano-DESI MSI in mind; applicability to other ion sources (MALDI, ESI-imaging) with different mobility characteristics is not explicitly validated in the source material.
- Very tight mobility tolerances (e.g., <0.005 1/K0) may result in no spectra passing the filter if instrument resolution or analyte heterogeneity is underestimated; conversely, loose tolerances defeat the specificity benefit.
- The mobility tolerance filter is applied uniformly across all line-scan positions; spatial or temporal variations in instrument calibration are not accounted for within a single MSIGen run.
Evidence
- [other] Set image acquisition parameters: scanned area height and width in specified units (e.g., mm), and whether to normalize all images to the same size using max, min, or mean pixels per line.: "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"
- [methods] Ion mobility tolerance filtering during spectral extraction and binning is a core MSIGen parameter.: "Ion mobility tolerance filtering [section=methods; evidence='mobility_tolerance, mobility_tolerance_units for matching ion mobility values']"
- [other] MSIGen processes data by matching m/z and mobility values within tolerances and binning pixels spatially.: "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, bin pixels spatially, and generate a"
- [intro] MSIGen is designed for nano-DESI MSI, a specific ion source context.: "is designed with nano-DESI MSI in mind"
- [readme] README example initialization shows how parameters are passed to MSIGen.: "An example can be found in the other_files folder. Run the following in Anaconda Prompt: conda activate MSIGen; python "C:/Path/to/MSIGen_CLI.py" "C:/path/to/config_file1.json""
1---2name: ion-mobility-filtering-and-tolerance-tuning-23description: Use when your raw MSI dataset is acquired on an ion-mobility-enabled instrument (e.g., Bruker .baf, .tsf, or .tdf formats) and your analyte of interest has a known or experimentally determined ion mobility value (1/K0 or drift time μs).4license: CC-BY-4.05---67# ion-mobility-filtering-and-tolerance-tuning89## Summary1011Apply ion mobility (1/K0 or μs units) tolerance windows during mass spectrometry imaging data processing to selectively extract and bin spectra by collisional cross-section, improving spatial specificity and reducing chemical noise in line-scan MSI workflows. This skill is essential when processing ion-mobility-resolved MSI data from instruments like Bruker timsTOF or when distinguishing isomers and isobars that co-elute in m/z space but separate in mobility space.1213## When to use1415Use this skill when your raw MSI dataset is acquired on an ion-mobility-enabled instrument (e.g., Bruker .baf, .tsf, or .tdf formats) and your analyte of interest has a known or experimentally determined ion mobility value (1/K0 or drift time μs). Apply it to reduce false positives from isobars, isomers, or background ions that share the same nominal m/z but have distinct mobility signatures, or when you need to extract mobility-resolved spatial images for a multi-pass analysis.1617## When NOT to use1819- Your raw data is from a non-mobility-resolved instrument (e.g., standard Orbitrap, Q-TOF without ion mobility encoding) — mobility filtering requires multi-dimensional raw data.20- Your mass list file lacks a mobility column or reference mobility values are unavailable — filtering requires a target mobility to define the tolerance window.21- You are processing already-centroided or pre-filtered data where mobility information has been discarded — mobility filtering must occur at the raw spectral extraction stage.2223## Inputs2425- raw MSI data file in ion-mobility format (.baf, .tsf, .tdf, .raw, or .mzML from an ion-mobility instrument)26- mass list file (Excel .xlsx or .csv) with at least m/z column and ion mobility column (1/K0 or μs)27- numeric mobility tolerance value (e.g., 0.02 1/K0)28- mobility tolerance units string ('1/K0' or 'μs')2930## Outputs3132- pixels.npy: 3D NumPy array of shape (n+1, y, x) with spatial bins filtered and summed only over spectra within the mobility tolerance window33- pixels_metadata.json: JSON metadata file documenting applied mobility tolerance, units, and per-mass ion mobility range statistics3435## How to apply3637During MSIGen initialization, define the `mobility_tolerance` parameter (numeric value) and `mobility_tolerance_units` parameter ('1/K0' or 'μs', depending on your instrument and calibration). These tolerances act as a ±window around the target mobility value: only spectra with ion mobility within [target_mobility − tolerance, target_mobility + tolerance] are retained and binned into the output pixel array. Set tolerance conservatively (typically 0.01–0.05 1/K0 or 1–5 μs) based on your instrument resolution and the reference mobility values in your mass list file (which should include a mobility column). Pass these parameters to the `msigen()` object, then call `get_image_data(verbose=True)` to apply the filter during spectral extraction and spatial binning; inspect the resulting pixels.npy array dimensions and metadata to confirm that the number of spatial voxels and intensity distributions reflect successful mobility filtering.3839## Related tools4041- **MSIGen** (primary tool for applying ion mobility tolerance filtering during spectral extraction and spatial binning in line-scan MSI workflows) — https://github.com/LabLaskin/MSIGen42- **pyBaf2Sql** (underlying library for reading Bruker .baf files with ion mobility data access when processing Bruker instruments) — https://github.com/gtluu/pyBaf2Sql43- **Python** (runtime environment (version ≥3.9 and ≤3.11) for MSIGen and mobility tolerance parameter definition)4445## Examples4647```48metadata, pixels = MSIGen_generator.get_image_data(verbose=True) where MSIGen_generator = msigen(example_file='sample.baf', mass_list_dir='masses.xlsx', mobility_tolerance=0.02, mobility_tolerance_units='1/K0', ...)49```5051## Evaluation signals5253- Verify that pixels.npy has expected shape (n+1, y, x) where n is the number of masses in the mass list; mismatched dimensions indicate filtering errors.54- Check pixels_metadata.json for a 'mobility_tolerance' and 'mobility_tolerance_units' field matching your input parameters.55- Qualitatively inspect ion images (via vis.get_and_display_images) for spatial localization consistent with known sample structure; diffuse or absent signal suggests tolerance is too stringent or mobility value is incorrect.56- Compare per-pixel intensity distributions and TIC between a mobility-filtered run and a non-filtered run; mobility filtering should reduce background noise and increase contrast for the target analyte.57- Confirm that all output metadata records the actual mobility range (min/max observed 1/K0 or μs) for each extracted mass, falling within the specified tolerance window.5859## Limitations6061- Ion mobility tolerance tuning is instrument and ion-specific; 1/K0 or μs values must be obtained experimentally or from reference databases, and calibration drift or unknown analyte structures can render pre-defined tolerances incorrect.62- MSIGen is designed with nano-DESI MSI in mind; applicability to other ion sources (MALDI, ESI-imaging) with different mobility characteristics is not explicitly validated in the source material.63- Very tight mobility tolerances (e.g., <0.005 1/K0) may result in no spectra passing the filter if instrument resolution or analyte heterogeneity is underestimated; conversely, loose tolerances defeat the specificity benefit.64- The mobility tolerance filter is applied uniformly across all line-scan positions; spatial or temporal variations in instrument calibration are not accounted for within a single MSIGen run.6566## Evidence6768- [other] Set image acquisition parameters: scanned area height and width in specified units (e.g., mm), and whether to normalize all images to the same size using max, min, or mean pixels per line.: "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"69- [methods] Ion mobility tolerance filtering during spectral extraction and binning is a core MSIGen parameter.: "Ion mobility tolerance filtering [section=methods; evidence='mobility_tolerance, mobility_tolerance_units for matching ion mobility values']"70- [other] MSIGen processes data by matching m/z and mobility values within tolerances and binning pixels spatially.: "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, bin pixels spatially, and generate a"71- [intro] MSIGen is designed for nano-DESI MSI, a specific ion source context.: "is designed with nano-DESI MSI in mind"72- [readme] README example initialization shows how parameters are passed to MSIGen.: "An example can be found in the other_files folder. Run the following in Anaconda Prompt: conda activate MSIGen; python "C:/Path/to/MSIGen_CLI.py" "C:/path/to/config_file1.json""
HolobiomicsLab 