XML Structured Metadata Construction

xml-structured-metadata-construction

Summary

Construct properly-formatted mzML XML structures with nested scan headers, precursor metadata, and base64-encoded binary product ion arrays for mass spectrometry data files. This skill is essential for generating standards-compliant MS data files that can be read by downstream analysis software.

When to use

When you have synthesized or assembled mass spectrometry spectral data (m/z values, intensities, retention times) and need to encode it as a portable, standard mzML file format rather than a proprietary binary or text representation. Specifically required after generating background noise and optional matrix peaks, or after simulating chromatographic peak shapes with realistic isotope and fragment ion distributions.

When NOT to use

• Input spectral data is already in mzML, NetCDF, or other standard MS format — use file conversion tools instead.
• You only need a feature table (peak list with m/z, RT, intensity) — use peak list simulation (simmzml or mzrtsim) which outputs CSV directly.
• Binary MS data is already encoded and you need only to read it — use mzR or other MS file readers instead of constructing XML.

Inputs

• synthetic m/z array (numeric vector or matrix)
• intensity array (numeric vector or matrix, same dimensions as m/z)
• retention time values (numeric vector, one per scan)
• MS level (integer: 1 for full scan, 2+ for fragmentation)
• optional precursor m/z and collision energy (for MS2+)
• optional polarity string ('positive' or 'negative')

Outputs

• .mzML file (XML with base64-encoded binary spectral data)
• mzML-compliant structured metadata (scan headers, precursor info, array descriptors)

How to apply

After generating or collecting spectral arrays (m/z, intensity, retention time), encode the binary intensity data using base64 encoding via the base64enc package. Construct the XML document tree with root element, then nest with appropriate scan-level metadata (scan number, retention time, MS level, polarity). For each scan, create a block containing precursor information (if MS2+), product ion m/z and intensity arrays as base64-encoded binary, and array descriptors specifying precision (32-bit vs 64-bit) and compression method. Write the complete XML tree to a .mzML file. Validate that the XML is well-formed and the base64 encoding is byte-accurate; downstream tools (mzR, xcms, etc.) will fail silently on malformed XML or encoding errors.

Related tools

• base64enc (Encodes binary spectral intensity arrays to base64 strings for embedding in XML)
• mzR (Reads and validates mzML files; used to verify that constructed XML is parseable)
• R (Primary language for XML tree construction and base64 encoding in mzrtsim workflow)

Examples

# After generating m/z and intensity arrays:
simmzml(db=monams1, name='test')
# This produces test.mzML with internal XML structure and base64-encoded spectral data

Evaluation signals

• Output .mzML file is valid XML (parses without namespace or schema errors)
• base64-encoded binary data decodes back to original m/z and intensity arrays with no precision loss or byte misalignment
• mzR or other MS tools can successfully read the .mzML file and extract all scan metadata (RT, MS level, precursor m/z) without warnings
• Scan count, array lengths, and retention time ordering match the input spectral data dimensions
• XML structure includes all required elements: , , , , , (if MS2+), and

Limitations

• Base64 encoding increases file size by ~33% compared to raw binary; large datasets (1000+ scans) may produce multi-MB .mzML files.
• XML construction must maintain strict element nesting and namespace declarations; typos in tag names or attribute keys will cause silent failures in downstream readers.
• Precision loss can occur if floating-point m/z or intensity values are not rounded consistently before encoding; verify numeric precision (32-bit vs 64-bit) matches instrument specifications.
• The mzML standard is complex; custom metadata (collision energy, cone voltage, custom tags) may not round-trip correctly through all readers.
• No automatic validation of spectral chemistry (e.g., isotope patterns, mass accuracy relative to formula); construction is purely structural.

Evidence

• [other] Encode the combined spectral data (noise + optional matrix) as base64-encoded binary using the base64enc package.: "Encode the combined spectral data (noise + optional matrix) as base64-encoded binary using the base64enc package."
• [other] Construct mzML XML structure with appropriate scan headers, precursor metadata, and product ion arrays, then write to the output .mzML file.: "Construct mzML XML structure with appropriate scan headers, precursor metadata, and product ion arrays, then write to the output .mzML file."
• [intro] The underlying engine handles binary data encoding via the base64enc package: "The underlying engine handles binary data encoding via the base64enc package"
• [readme] The native mzML writer handles the binary encoding (Base64) internally without requiring external MS data libraries.: "The native mzML writer handles the binary encoding (Base64) internally without requiring external MS data libraries."