Mass spectrometry raw data encoding

Mass Spectrometry Raw Data Encoding

Summary

Encode simulated LC/GC-MS raw mass spectrometry data matrices into Base64 format and write them to standardized .mzML file structures for downstream metabolomics analysis. This skill bridges in-memory peak intensity matrices (with realistic chromatographic profiles, noise, and matrix background) to portable, binary-encoded MS data files.

When to use

You have generated or obtained a two-dimensional mass-spectrometry intensity matrix (m/z × retention time scan points) with simulated or experimental peak shapes, noise, and background, and need to encode it as a binary .mzML file for distribution, archival, or integration into standard metabolomics workflows (e.g., xcms, MZmine2, or other mzML-compatible tools).

When NOT to use

• Input is already a finalized .mzML or .netCDF file; re-encoding is redundant.
• You need only a peak list or feature table, not raw continuous MS data.
• Target format is not mzML (e.g., mzXML, netCDF, or vendor-native binary); use format-specific encoders instead.

Inputs

• Simulated or experimental MS intensity matrix (2D array: scans × detected m/z)
• Scan metadata (acquisition time in seconds, precursor m/z, collision energy, ion mode)
• Peak ground-truth table (m/z, retention time, simulated maximum intensity, compound name)

Outputs

• .mzML file (XML-wrapped binary MS data with Base64-encoded intensity arrays)
• Companion .csv file with ground-truth peak information and sim_ins (absolute maximum intensity per peak)

How to apply

Construct the raw MS intensity matrix by concatenating individual scan records (each scan contains m/z array and intensity array from chromatographic and spectral simulation). Apply Base64 encoding to the binary-formatted (typically little-endian float32 or int32) matrix using the base64enc package. Embed the encoded payload into the mzML XML structure under the appropriate <binaryDataArray> elements, specifying the correct cvParam attributes (e.g., 'MS:1000521' for 32-bit float, 'MS:1000576' for no compression). Write metadata headers (scan acquisition time, precursor m/z for MS2, collision energy, ion mode) into the corresponding mzML elements. Validate the output by confirming the file parses correctly in standard MS software (e.g., mzR::openMSfile in R or pymzml in Python).

Related tools

• base64enc (Encodes the binary MS intensity matrix into Base64 format for safe embedding in XML)
• mzrtsim (Generates simulated LC/GC-MS raw data and wraps simmzml() for end-to-end .mzML file creation) — https://github.com/yufree/mzrtsim
• mzR (Alternative library for reading/validating .mzML files (mzrtsim removes dependency for file generation))
• SummarizedExperiment (Wraps encoded .mzML data for seamless Bioconductor workflow integration via mzrtsim_se())

Examples

library(mzrtsim)
data("monams1")
simmzml(db=monams1, name='test')

Evaluation signals

• Output .mzML file is well-formed XML and parses without error in standard MS software (mzR, pymzml, Proteowizard).
• Base64-decoded binary payload matches the original intensity matrix dimensions and value ranges (accounting for floating-point precision).
• Companion .csv contains exactly one row per simulated compound with non-empty m/z, retention_time, database_intensity, sim_ins, and compound_name columns.
• sim_ins values are positive, realistic absolute intensities (e.g., 100–1,000,000 range typical of LC-MS detectors) and scale consistently with input response factor and peak-height parameters.
• All scans reference valid acquisition times (in seconds) that align with the retention-time entries in the companion CSV.

Limitations

• Base64 encoding increases file size by ~33% compared to raw binary; no compression is applied by default.
• mzML XML structure is verbose and may become slow to parse for very large numbers of scans (>100,000); consider streaming readers or indexed mzML for high-throughput datasets.
• Ground-truth sim_ins values are only as accurate as the underlying chromatographic peak-shape model (Gaussian or exponentially-modified Gaussian) and response-factor calibration; real instruments may deviate.
• No native support for variable m/z arrays (common in high-resolution instruments); requires pre-binning or resampling to a fixed m/z grid for some downstream tools.

Evidence

• [intro] The underlying engine handles binary data encoding via the base64enc package: "The underlying engine handles binary data encoding via the base64enc package"
• [readme] simmzml() generates .mzML files with Base64-encoded peak data and companion CSV: "simmzml() generates one .mzML file and a companion .csv file containing ground-truth peak information (m/z, retention time, database intensity, simulated maximum intensity, compound name)."
• [intro] sim_ins column represents absolute ground-truth maximum intensity calculated by chromatographic profile: "The output CSV now includes a sim_ins column — the absolute ground-truth maximum intensity of each simulated peak, accounting for response factor, peak height, and chromatographic profile."
• [methods] Chromatographic peak-shape modeling applied to retention-time profiles before encoding: "Apply chromatographic peak-shape modeling (Gaussian or exponentially-modified Gaussian) with configurable tailing and peak-width parameters to generate realistic retention-time profiles."
• [readme] Base64 encoding and mzML file structure writing are handled natively: "The native mzML writer handles the binary encoding (Base64) internally without requiring external MS data libraries."