Mgf File Parsing

---
name: mgf-file-parsing
description: Use 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3763
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_0121
  tools:
  - MolNotator
  - PyYAML
  - matchms
  - Python file I/O
  - Python
  - gensim
  - run_gensim.py
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1101/2021.12.21.473622v1
  title: MolNotator
- doi: 10.1073/pnas.1608041113
  title: ''
evidence_spans:
- from MolNotator.duplicate_filter import duplicate_filter
- from MolNotator.sample_slicer import sample_slicer
- import yaml
- pipenv --python 2.7
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_molnotator_cq
    doi: 10.1101/2021.12.21.473622v1
    title: MolNotator
  - build: coll_ms2lda_substructure_discovery_mass2motif_cq
    doi: 10.1073/pnas.1608041113
    title: MS2LDA
  dedup_kept_from: coll_molnotator_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1101/2021.12.21.473622v1
  all_source_dois:
  - 10.1101/2021.12.21.473622v1
  - 10.1073/pnas.1608041113
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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."