Open format mass spectrometry file handling

open-format-mass-spectrometry-file-handling

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Convert vendor-specific mass spectrometry data formats to open-source formats (mzML or mzXML) required for deposition in public repositories and downstream analysis in GNPS and ReDU. This skill ensures data interoperability and enables spectral library matching workflows at repository scale.

When to use

You have raw mass spectrometry data in vendor-proprietary formats (e.g., .raw, .d, .ms) that you need to upload to MassIVE for public sharing or submit to GNPS for spectral library matching and chemical annotation. The conversion is a mandatory prerequisite before launching GNPS spectral library workflows or contributing data to ReDU.

When NOT to use

• Data is already in mzML or mzXML format — proceed directly to upload and annotation
• You are analyzing data locally without intent to share publicly — proprietary formats may be acceptable for local analysis, though open formats are still recommended for reproducibility
• Your workflow requires vendor-specific metadata that is lost during conversion to open formats — consult conversion tool documentation for metadata preservation options

Inputs

• Vendor-specific mass spectrometry data files (.raw, .d, .ms, or other proprietary formats)
• Mass spectrometry instrument metadata (acquisition parameters, instrument type)

Outputs

• Open-format mass spectrometry files (.mzML or .mzXML)
• Preserved MS2 product-ion spectra with fragmentation metadata

How to apply

Use dedicated file conversion software (referenced in GNPS documentation) to transform vendor-specific MS data into mzML or mzXML open formats. The conversion preserves MS2 product-ion spectra and associated metadata needed for spectral library matching. After conversion, validate that the output files are readable by GNPS and MassIVE by attempting upload and confirming file acceptance. The converted files serve as input to the GNPS spectral library search workflow, which compares MS2 spectra against reference fragmentation patterns to generate chemical annotations and detection matrices.

Related tools

• GNPS (Accepts converted mzML/mzXML files as input to spectral library matching workflow; provides file format specifications and conversion guidance) — https://github.com/CCMS-UCSD/GNPSDocumentation
• MassIVE (Public data repository that requires open-format files (.mzML or .mzXML) for deposition and archival)
• ReDU (Reanalysis user interface that bridges GNPS and MassIVE; operates on publicly deposited open-format files) — https://github.com/mwang87/ReDU-MS2-GNPS

Evaluation signals

• Converted files are successfully uploaded to MassIVE without format rejection errors
• GNPS spectral library search workflow accepts the converted files and initiates processing
• Output files contain valid MS2 spectra with m/z values and intensity information intact
• Chemical annotations and detection matrix are generated by GNPS post-workflow with non-zero annotation counts
• File passes ReDU validation when submitted with sample information template

Limitations

• Conversion may lose vendor-specific metadata (e.g., instrument-vendor calibration parameters, proprietary annotations) not represented in the mzML/mzXML schema
• The same chemical can produce multiple GNPS annotations if MS2 spectra vary slightly in m/z or abundance patterns, complicating downstream interpretation of the detection matrix
• Conversion accuracy depends on the quality of the conversion tool and source file integrity; corrupted vendor files may produce invalid or incomplete mzML/mzXML output
• Open-format conversion is computationally intensive for large datasets; file size may increase during conversion depending on compression settings

Evidence

• [methods] convert your data to open-source file format accepted in MassIVE: "convert your data to open-source file format accepted in MassIVE"
• [other] Retrieve MS2 spectra in open format (.mzML or .mzXML) from a public MassIVE dataset: "Retrieve MS2 spectra in open format (.mzML or .mzXML) from a public MassIVE dataset"
• [readme] Instructions on file conversion software: "Instructions on file conversion software - link here"
• [other] GNPS library search compares MS2 product-ion spectra against reference fragmentation patterns in its public spectral library, producing tabulated chemical annotations with file detection information: "GNPS library search compares MS2 product-ion spectra against reference fragmentation patterns in its public spectral library, producing tabulated chemical annotations with file detection information"