# Spectral Data Serialization

> Use when after completing MS/MS spectra detection and peak recognition on tandem MS breath samples.

- Skill: `holobiomicslab/spectral-data-serialization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/spectral-data-serialization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/spectral-data-serialization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/spectral-data-serialization

---


# spectral-data-serialization

## Summary

Export detected MS/MS spectra from feature extraction and peak recognition pipelines to MGF (Mascot Generic Format) files for downstream spectral analysis and compound identification. This skill encodes precursor m/z, charge state, retention time, and fragment ion peaks into a standardized text format suitable for spectral library matching and metabolomics workflows.

## When to use

Apply this skill after completing MS/MS spectra detection and peak recognition on tandem MS breath samples. Use when you have FeatureSet or Sample objects from BreathXplorer's find_feature() or merge_result() pipelines and need to export spectral data in a portable, standards-compliant format compatible with spectral matching tools and databases.

## When NOT to use

- Input contains only MS1 feature data without tandem MS/MS spectra — MGF format requires MS2-level spectral data.
- Output destination is a database or binary format — MGF is text-based and designed for file exchange, not for in-memory or database serialization.
- Spectral data is already in another standardized format (e.g., mzML, mzXML) and no format conversion or filtering is needed.

## Inputs

- FeatureSet object (from find_feature) with tandem MS/MS spectral data attached
- Sample object (from merge_result) with aligned features and associated spectra
- mzML or mzXML file path containing raw MS/MS acquisitions

## Outputs

- MGF file (Mascot Generic Format) with formatted MS/MS spectra
- Text file with BEGIN IONS / END IONS sections, PEPMASS, MSLEVEL, and m/z–intensity pairs

## How to apply

Call the to_mgf() function on a FeatureSet or Sample object, passing a path to the output MGF file. The function iterates over detected MS/MS spectra, formats each spectrum with required MGF fields (precursor m/z as PEPMASS, MS level as MSLEVEL=2, and fragment ion m/z–intensity pairs), wraps each spectrum in BEGIN IONS / END IONS delimiters, and writes all entries to a single text file. Validate the output by verifying that: (1) every BEGIN IONS block has a matching END IONS block; (2) every spectrum contains at least one PEPMASS field and one fragment peak pair; (3) m/z and intensity values are numeric and non-negative; (4) the file parses without syntax errors in downstream spectral matching software.

## Related tools

- **BreathXplorer** (Python package providing to_mgf() function to serialize MS/MS spectra and retrieve_tandem() to load tandem MS data) — https://github.com/wykswr/breathXplorer
- **Python** (Runtime environment for executing BreathXplorer's to_mgf() utility and file I/O operations)

## Examples

```
from breathXplorer import retrieve_tandem; retrieve_tandem("sample.mzML").to_mgf("spectra.mgf")
```

## Evaluation signals

- Output file is valid MGF syntax: every BEGIN IONS has a matching END IONS, no malformed delimiters or unclosed sections.
- Every spectrum record contains a PEPMASS field with a numeric m/z value and MSLEVEL=2 marker.
- Fragment ion pairs (m/z intensity) are present for each spectrum and consist of two numeric values per line.
- All m/z and intensity values are non-negative floats; no NaN, Inf, or missing values in peak lists.
- File can be successfully parsed by downstream spectral matching tools (e.g., MASCOT, X!Tandem, or open-source MGF parsers).

## Limitations

- MGF format does not preserve retention time metadata in a standardized field; retention time may be lost or stored in custom annotations depending on the exporting tool and downstream parser expectations.
- Charge state is not explicitly encoded in the MGF standard; precursor charge inference must be handled by downstream spectral matching software.
- Large datasets with many spectra may produce very large MGF files with poor random-access performance; alternative binary formats (mzML, HDF5) are better suited for high-volume data.
- MGF does not support metadata about sample origin, instrument configuration, or quality metrics; these must be tracked separately in documentation or metadata files.

## Evidence

- [readme] If you're using tandem MS, you can also export the MS/MS spectra as mgf file using the `to_mgf` function: "If you're using tandem MS, you can also export the MS/MS spectra as mgf file using the `to_mgf` function"
- [readme] The file contains the MS/MS spectra of the features, each feature has a PEPMASS (precursor mass) and MSLEVEL field, and the following pairs are the m/z and intensity of the MS/MS spectra.: "The file contains the MS/MS spectra of the features, each feature has a PEPMASS (precursor mass) and MSLEVEL field, and the following pairs are the m/z and intensity of the MS/MS spectra."
- [other] Format each spectrum entry with required MGF fields: precursor m/z, precursor charge, retention time, and fragment ion peaks (m/z and intensity pairs).: "Format each spectrum entry with required MGF fields: precursor m/z, precursor charge, retention time, and fragment ion peaks (m/z and intensity pairs)."
- [other] Write all formatted spectra to a single MGF file with proper header and section delimiters.: "Write all formatted spectra to a single MGF file with proper header and section delimiters."
- [other] Validate MGF syntax and verify all spectra contain required fields.: "Validate MGF syntax and verify all spectra contain required fields."