HolobiomicsLab ionization-mode-detection-from-mass-spectrometry-data
Summary
Infer the ionization polarity (positive or negative) from mzML file headers prior to feature extraction, enabling correct parameterization of Asari processing. This is a prerequisite step that ensures downstream feature detection uses appropriate ion mass-to-charge calibration for the experimental acquisition mode.
When to use
When you have raw LC-MS data in mzML format (converted from .raw or acquired directly in that format) and need to invoke Asari for feature extraction, but the ionization mode is not explicitly specified in your experimental metadata or pipeline configuration. The mode must be inferred from the mzML file headers before Asari processing begins.
When NOT to use
- Ionization mode is already explicitly provided in your experiment metadata or configuration file — use the metadata value directly instead of re-inferring from headers.
- Input files are not in mzML format or do not contain properly formatted MS1 scan headers.
- You are working with GC-MS or other non-LC-MS data types (support under development; not yet fully integrated into PCPFM).
Inputs
- centroid mzML files (from converted .raw acquisitions or native LC-MS output)
- mzML file headers containing MS1 scan metadata
Outputs
- ionization mode (positive or negative)
- validated mode parameter ready for Asari invocation
How to apply
Parse the mzML file headers (MS1 scan metadata) to identify the ionization polarity setting recorded during acquisition. The mzML format encodes the polarity (positive or negative ion mode) in the scan attributes. Extract this value programmatically before invoking Asari with the converted_acquisitions subdirectory. Pass the inferred mode as a parameter to Asari so that feature grouping, m/z tolerance (5 ppm default), and ion mass calculations operate under the correct polarity context. This inferred mode is then used consistently across all downstream feature extraction, annotation, and quality control steps.
Related tools
- Asari (accepts inferred ionization mode to parameterize feature extraction with correct m/z tolerance and ion mass calculations) — https://github.com/shuzhao-li/asari
- Python (language for programmatically parsing mzML headers and extracting polarity metadata)
- ThermoRawFileParser (upstream tool that converts .raw to mzML, encoding polarity information in output headers)
Evaluation signals
- mzML files successfully parsed and polarity attribute read without errors.
- Inferred ionization mode (positive or negative) is consistent across all files in the acquisition batch.
- Asari processes the mzML files using the inferred mode without reporting polarity-related warnings or errors.
- Generated feature tables (full and preferred) contain m/z and intensity values consistent with the inferred ionization polarity (e.g., positive mode should yield predominantly positive m/z features).
- Downstream annotation steps (MS1, MS2) produce sensible compound matches using the mode-appropriate mass calibration.
Limitations
- Relies on correct encoding of polarity metadata in mzML headers; corrupted or non-standard headers may cause inference to fail.
- Does not validate whether the inferred mode matches the actual chemistry of the sample; a mislabeled acquisition will propagate incorrect mode inference.
- Support for mixed-mode or alternating-polarity acquisitions is not yet implemented in PCPFM (under development).
- GC-MS and other non-LC-MS data types are not yet fully supported in the pipeline.
Evidence
- [other] Load the PCPFM experiment object and infer the ionization mode (positive or negative) from the mzML file headers.: "infer the ionization mode (positive or negative) from the mzML file headers"
- [other] Invoke Asari with the inferred ionization mode on the converted_acquisitions subdirectory containing centroid .mzML files, using default parameters (5 ppm m/z tolerance, 2 second retention time tolerance for feature grouping).: "Invoke Asari with the inferred ionization mode on the converted_acquisitions subdirectory containing centroid .mzML files"
- [readme] Inputs should include a set of raw files (.raw or .mzML) and a csv file for metadata (minimal sample names and file path).: "Inputs should include a set of raw files (.raw or .mzML) and a csv file for metadata"