Mgf file parsing

mgf-file-parsing

Summary

Parse and extract MS/MS spectral records from Mascot Generic Format (MGF) files generated by MZmine or other mass spectrometry instruments. MGF parsing is a foundational step in untargeted metabolomics workflows that enables downstream annotation, dereplication, and molecular networking.

When to use

Use this skill when you have raw or MZmine-processed MGF files (containing MS/MS spectra with m/z values, intensities, and precursor masses) that need to be segmented by sample, deduplicated, or prepared for fragment annotation and adduct analysis in the MolNotator pipeline. Apply it before sample slicing, duplicate filtering, or fragment/adduct annotation steps.

When NOT to use

• Input is already in an alternative format (mzML, mzXML, netCDF) — use format conversion tools first
• MGF file is corrupted or missing required PEPMASS or fragment peak records — validate integrity before parsing
• You need to visualize or explore raw spectra interactively — use dedicated mass spectrometry viewers (e.g., Cytoscape for networks post-processing)

Inputs

• MGF file from MZmine output or mass spectrometry instrument
• Ion mode designation (NEG or POS) to filter or contextualize spectra

Outputs

• Parsed spectrum records with precursor m/z, charge, and fragment ion peaks
• In-memory spectrum objects or intermediate data structures indexed by spectrum title/sample

How to apply

Load the MGF file using Python file I/O to extract spectrum records. Each spectrum record contains a precursor m/z value, charge state, and fragment ion peaks (m/z and intensity pairs). Parse header metadata (PEPMASS, CHARGE, TITLE, RTINSECONDS if present) to identify spectral attributes. Store parsed spectra in memory or as intermediate data structures (e.g., list of dictionaries or Spectrum objects from matchms library) that preserve m/z values, intensities, and precursor information. Validate that all required fields (PEPMASS, fragment peaks) are present and numeric. The parsed spectra are then ready for ionization-mode-specific processing (NEG or POS) in downstream MolNotator modules.

Related tools

• MolNotator (Framework that wraps MGF parsing in duplicate_filter and sample_slicer modules to process and segment MGF spectra by ionization mode and sample identifier) — https://github.com/ZzakB/MolNotator
• matchms (Python library for spectrum data handling and parsing; version ≤0.6.2 required for MolNotator compatibility)
• Python file I/O (Low-level MGF file reading and text parsing)

Examples

import os
import yaml
from MolNotator.duplicate_filter import duplicate_filter
with open('./params/params.yaml') as info:
    params = yaml.load(info, Loader=yaml.FullLoader)
duplicate_filter(params=params, ion_mode='NEG')

Evaluation signals

• All spectrum records are successfully extracted with non-null PEPMASS (precursor m/z) and CHARGE fields
• Fragment ion peaks (m/z and intensity pairs) are correctly parsed and stored as numeric tuples
• Parsed spectrum count matches the expected number of scans from the original MGF file (no records dropped)
• Downstream modules (duplicate_filter, sample_slicer) execute without parse errors or missing field exceptions
• Sample identifiers or spectrum titles are correctly preserved and can be used for segmentation in sample_slicer

Limitations

• MGF format allows optional fields (e.g., RTINSECONDS, SCANS); parsers must handle missing optional metadata gracefully
• Large MGF files (>1 GB) may require streaming or chunked parsing to avoid memory overflow; standard MolNotator workflow assumes files fit in memory
• MGF files from different MS instruments may have vendor-specific header formats or field naming conventions not fully standardized; manual inspection may be needed
• No built-in validation of fragment peak mass accuracy or intensity calibration; assumes upstream QC by MZmine or instrument software

Evidence

• [other] Load the MZmine MGF and CSV files for the specified ionization mode (NEG or POS) using Python file I/O.: "Load the MZmine MGF and CSV files for the specified ionization mode (NEG or POS) using Python file I/O."
• [other] The duplicate_filter function accepts parameters and an ion_mode argument to filter duplicate features from MZmine's MGF and CSV files for either negative (NEG) or positive (POS) ionization modes.: "The duplicate_filter function accepts parameters and an ion_mode argument to filter duplicate features from MZmine's MGF and CSV files for either negative (NEG) or positive (POS) ionization modes."
• [readme] import os import yaml from MolNotator.duplicate_filter import duplicate_filter from MolNotator.sample_slicer import sample_slicer: "import os import yaml from MolNotator.duplicate_filter import duplicate_filter from MolNotator.sample_slicer import sample_slicer"
• [readme] The databases folder contains database files in MGF, TSV or CSV format.: "The databases folder contains database files in MGF, TSV or CSV format."
• [readme] MZmine works within a user-defined project folder with a specific file structure. An example is given in the examples folder: "MolNotator works within a user-defined project folder with a specific file structure."