File Format Writing Mzml

file-format-writing-mzml

Summary

Serialize simulated or replayed mass spectrometry scan data from a ViMMS Environment into the standard mzML (mzXML Markup Language) format for downstream analysis and archival. This enables portable exchange of LC-MS/MS scan metadata, fragmentation spectra, and retention time information with external metabolomics tools.

When to use

After completing an Environment simulation or replay with scan-level MS2 acquisition control, and evaluation data has been collected in memory. Use this skill when you need to export simulated or replayed scan results into a standard, interoperable format for spectral matching, metabolite identification, or validation against reference libraries (e.g., GNPS-NIST14-MATCHES).

When NOT to use

• If evaluation data has not been collected (save_eval flag was not enabled during environment setup); write_mzML() requires populated scan metadata.
• If the goal is to persist the in-memory EvaluationData object itself (chemicals, fragmentation events, and scan-source linkage) for reuse—use pickle serialization instead, which preserves full Python object state.
• If you need to compare or filter scans before export; write_mzML() commits all collected scans to the file without intermediate curation.

Inputs

• ViMMS Environment object (post-simulation, with populated scan list)
• EvaluationData artifact (in-memory, containing collected scans and fragmentation events)
• Simulated or replayed LC-MS/MS run metadata (retention times, m/z ranges, isolation windows)

Outputs

• mzML file (XML-formatted mass spectrometry data)
• Companion mzML scan records (linked to source chemical definitions and fragmentation metadata)

How to apply

After env.run() completes and the in-memory scan list is populated, invoke Environment.write_mzML() to serialize all collected scans (MS1 survey scans, MS2 fragmentation scans, retention times, m/z values, intensities, and precursor ion information) into a companion mzML file. The method writes structured XML-based scan records linked to the chemical definitions and fragmentation events captured during the simulation. Verify that the output file is well-formed XML and that all scan indices, precursor m/z windows, and isolation windows match the simulated acquisition parameters (e.g., isolation width, collision energy settings). Cross-check that the number of MS2 scans in the mzML matches the number of precursor ions targeted by the controller strategy.

Related tools

• ViMMS (Mass spectrometry simulation framework; provides Environment.write_mzML() method to serialize scan data into mzML format) — https://github.com/glasgowcompbio/vimms
• Python pickle module (Alternative serialization format for persisting in-memory EvaluationData objects alongside mzML output files)

Examples

env.write_mzML('output_simulation.mzML'); import pickle; pickle.dump(env.evaluation_data, open('evaluation_data.p', 'wb'))

Evaluation signals

• Output mzML file exists at the specified path and is valid XML (parseable by standard mzML readers).
• Number of MS2 scans in the mzML equals the number of precursor ions targeted by the acquisition controller strategy.
• All scan indices, retention times, precursor m/z, and isolation windows in the mzML match the simulation metadata and environment parameters.
• The mzML file can be successfully ingested by downstream tools (e.g., MZmine peak picking, GNPS spectral matching) without schema or encoding errors.
• Cross-validation: scan count in mzML matches the length of the Environment's scan list; fragmentation event counts align with collected EvaluationData.

Limitations

• The write_mzML() method requires that evaluation data has been collected during the Environment run (save_eval=True); unevaluated runs will produce an incomplete or empty mzML file.
• The method serializes only the scans present in the Environment's in-memory scan list at the time of the call; scans cannot be selectively filtered or pruned before export without modifying the Environment object.
• The mzML output is linked to the specific simulation parameters and controller strategy used; replay of the same data with different strategies will produce different mzML files (e.g., different MS2 precursor selections).

Evidence

• [other] After env.run() completes, serialize the in-memory EvaluationData object (containing chemicals, generated scans, and fragmentation events) to a pickle file using Python's pickle module. Write the mzML scan output to a companion file using Environment.write_mzML().: "After env.run() completes, serialize the in-memory EvaluationData object (containing chemicals, generated scans, and fragmentation events) to a pickle file using Python's pickle module. Write the"
• [readme] ViMMS provides scan-level control simulation of the MS2 acquisition process in a virtual environment. You can generate new LC-MS/MS data based on empirical data or virtually replay a previous LC-MS/MS analysis using existing data, which allows for testing different fragmentation strategies. With ViMMS, you can evaluate diverse fragmentation strategies using real data, and extract the scan results as mzML files.: "extract the scan results as mzML files"
• [other] Verify both the pickle and mzML files exist and are accessible for subsequent evaluation operations.: "Verify both the pickle and mzML files exist and are accessible for subsequent evaluation operations."