# XML Structured Metadata Construction

> Use when 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.

- Skill: `holobiomicslab/xml-structured-metadata-construction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/xml-structured-metadata-construction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/xml-structured-metadata-construction/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/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 <indexedmzML> element, then nest <mzML> with appropriate scan-level metadata (scan number, retention time, MS level, polarity). For each scan, create a <scan> 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: <indexedmzML>, <mzML>, <run>, <spectrumList>, <scan>, <precursorList> (if MS2+), and <binaryDataArrayList>

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