Spectra Object Serialization and Deserialization for Cross-Language Integration
Summary
Convert R Spectra objects to Python-compatible formats (matchms.Spectrum, spectrum_utils.spectrum.MsmsSpectrum) and back, enabling seamless data exchange between R and Python mass spectrometry workflows. This skill is essential for leveraging Python MS libraries within an R-based Spectra analysis pipeline.
When to use
You have Spectra objects in an R environment and need to apply Python MS algorithms (e.g., matchms similarity scoring, spectrum normalization, or filtering) that operate on Python spectral objects, then return results back to R for further analysis or visualization.
When NOT to use
- Input is already a native Python object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum); use the Python library directly instead of serializing through R.
- Analysis workflow is entirely in Python; no need to serialize/deserialize if working end-to-end in Python.
- Spectra object lacks required peak data (m/z and intensity arrays) or precursor m/z; serialization will fail or produce incomplete objects.
Inputs
- Spectra object (R; containing msLevel, name, precursorMz, mz list-column, intensity list-column, and optional metadata)
- Python MS library function signature (e.g., matchms similarity scorer, spectrum_utils filter)
Outputs
- Python spectral object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum)
- Processed result from Python library (e.g., similarity matrix, normalized spectrum)
- Spectra object (R) or numeric matrix with results re-imported into R environment
How to apply
- Start with a Spectra object in R containing m/z and intensity peaks, precursor m/z, and metadata. 2. Use SpectriPy's conversion functions to serialize the Spectra object into a Python object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum), preserving all spectral variables and peak data. 3. Pass the serialized Python object to the target Python MS library function (e.g., matchms.similarity.CosineGreedy for similarity scoring). 4. Capture the result from the Python function and deserialize it back into an R Spectra object or compatible R data structure. 5. Verify that all expected attributes (m/z arrays, intensity arrays, precursor m/z, spectrum metadata) have been preserved and are accessible in the returned R object. 6. The reticulate package manages the R–Python interface automatically, including environment setup and library dependency resolution via py_require().
Related tools
- SpectriPy (Provides R functions and conversion utilities to serialize R Spectra objects into Python spectral objects and deserialize Python results back into R Spectra objects.) — https://github.com/RforMassSpectrometry/SpectriPy
- Spectra (Defines the R Spectra class and infrastructure for storing mass spectrometry data (peaks, metadata, backends); serves as the source and destination object type for serialization.) — https://github.com/RforMassSpectrometry/Spectra
- reticulate (Manages the R–Python interface, handles environment setup, library dependency installation via py_require(), and automatic serialization of R objects to Python and vice versa.)
- matchms (Python MS library providing spectral similarity scoring (e.g., CosineGreedy) and spectrum processing functions that are called on deserialized Python spectral objects.) — https://github.com/matchms
- spectrum_utils (Python MS library providing spectrum normalization, filtering, and utility functions; compatible with SpectriPy's spectrum_utils.spectrum.MsmsSpectrum conversion.) — https://github.com/bittremieux-lab/spectrum_utils
Examples
library(Spectra); library(SpectriPy); caf <- Spectra(DataFrame(msLevel=2L, precursorMz=195.0877, mz=list(c(135.04, 138.06)), intensity=list(c(340, 416)))); res <- compareSpectriPy(caf, caf, param=CosineGreedy(tolerance=0.05))
Evaluation signals
- Returned R object is a valid Spectra object with class(.) == 'Spectra' and passes bioconductor/Spectra schema checks.
- Peak data (mz and intensity list-columns) are present and match expected dimensions after round-trip serialization.
- Metadata variables (precursorMz, msLevel, name, id) are preserved with identical values before and after serialization.
- Python function outputs (e.g., similarity scores, normalized intensities) are successfully imported back into R as numeric matrices or vectors with expected dimensions and value ranges.
- No data loss or NaN values introduced during serialization/deserialization; compare row counts and peak counts before and after.
Limitations
- Python version ≥ 3.12 must be installed on the system; SpectriPy cannot initialize without it.
- Requires explicit installation of Python dependencies (matchms 0.31, spectrum_utils 0.3.2, numpy 2.2.0) either via reticulate's auto-install or manual system/environment setup; missing packages will cause deserialization to fail.
- First serialization call incurs Python environment initialization overhead (slower than subsequent calls).
- Spectra objects lacking required peak data (empty mz or intensity columns) cannot be serialized; will raise errors or produce incomplete Python objects.
- The reticulate interface may encounter version conflicts or platform-specific issues if Python or dependency versions differ from tested/documented versions.
Evidence
- [intro] SpectriPy integrates Python MS packages into R by wrapping Python functionality into R functions, enabling the use of Python libraries within a Spectra-based MS analysis workflow in R.: "By wrapping Python functionality into R functions, SpectriPy allows a seamless integration of Python libraries into R"
- [readme] SpectriPy provides conversion functions between Spectra objects and Python spectral objects from matchms and spectrum_utils.: "contains functions to convert between R's
Spectra::Spectra objects and matchms.Spectrum and spectrum_utils.spectrum.MsmsSpectrum objects from the Python matchms"
- [readme] The reticulate package manages Python environment setup and automatic library installation via py_require().: "SpectriPy's Python library management uses the
py_require() function introduced in reticulate version 1.41"
- [readme] Serialized objects must preserve all spectral attributes and variables when round-tripping between R and Python.: "R and Python spectral objects are easily translated and available in one workflow (i.e., a quarto document)"
- [readme] First serialization call includes Python environment initialization overhead.: "Note also that the first
compareSpectriPy() call takes usually a little longer because the Python setup has to be initialized."
1---2name: spectra-object-serialization-deserialization3description: Use when you have Spectra objects in an R environment and need to apply Python MS algorithms (e.g., matchms similarity scoring, spectrum normalization, or filtering) that operate on Python spectral objects, then return results back to R for further analysis or visualization.4license: CC-BY-4.05---67# Spectra Object Serialization and Deserialization for Cross-Language Integration89## Summary1011Convert R Spectra objects to Python-compatible formats (matchms.Spectrum, spectrum_utils.spectrum.MsmsSpectrum) and back, enabling seamless data exchange between R and Python mass spectrometry workflows. This skill is essential for leveraging Python MS libraries within an R-based Spectra analysis pipeline.1213## When to use1415You have Spectra objects in an R environment and need to apply Python MS algorithms (e.g., matchms similarity scoring, spectrum normalization, or filtering) that operate on Python spectral objects, then return results back to R for further analysis or visualization.1617## When NOT to use1819- Input is already a native Python object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum); use the Python library directly instead of serializing through R.20- Analysis workflow is entirely in Python; no need to serialize/deserialize if working end-to-end in Python.21- Spectra object lacks required peak data (m/z and intensity arrays) or precursor m/z; serialization will fail or produce incomplete objects.2223## Inputs2425- Spectra object (R; containing msLevel, name, precursorMz, mz list-column, intensity list-column, and optional metadata)26- Python MS library function signature (e.g., matchms similarity scorer, spectrum_utils filter)2728## Outputs2930- Python spectral object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum)31- Processed result from Python library (e.g., similarity matrix, normalized spectrum)32- Spectra object (R) or numeric matrix with results re-imported into R environment3334## How to apply35361. Start with a Spectra object in R containing m/z and intensity peaks, precursor m/z, and metadata. 2. Use SpectriPy's conversion functions to serialize the Spectra object into a Python object (matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum), preserving all spectral variables and peak data. 3. Pass the serialized Python object to the target Python MS library function (e.g., matchms.similarity.CosineGreedy for similarity scoring). 4. Capture the result from the Python function and deserialize it back into an R Spectra object or compatible R data structure. 5. Verify that all expected attributes (m/z arrays, intensity arrays, precursor m/z, spectrum metadata) have been preserved and are accessible in the returned R object. 6. The reticulate package manages the R–Python interface automatically, including environment setup and library dependency resolution via py_require().3738## Related tools3940- **SpectriPy** (Provides R functions and conversion utilities to serialize R Spectra objects into Python spectral objects and deserialize Python results back into R Spectra objects.) — https://github.com/RforMassSpectrometry/SpectriPy41- **Spectra** (Defines the R Spectra class and infrastructure for storing mass spectrometry data (peaks, metadata, backends); serves as the source and destination object type for serialization.) — https://github.com/RforMassSpectrometry/Spectra42- **reticulate** (Manages the R–Python interface, handles environment setup, library dependency installation via py_require(), and automatic serialization of R objects to Python and vice versa.)43- **matchms** (Python MS library providing spectral similarity scoring (e.g., CosineGreedy) and spectrum processing functions that are called on deserialized Python spectral objects.) — https://github.com/matchms44- **spectrum_utils** (Python MS library providing spectrum normalization, filtering, and utility functions; compatible with SpectriPy's spectrum_utils.spectrum.MsmsSpectrum conversion.) — https://github.com/bittremieux-lab/spectrum_utils4546## Examples4748```49library(Spectra); library(SpectriPy); caf <- Spectra(DataFrame(msLevel=2L, precursorMz=195.0877, mz=list(c(135.04, 138.06)), intensity=list(c(340, 416)))); res <- compareSpectriPy(caf, caf, param=CosineGreedy(tolerance=0.05))50```5152## Evaluation signals5354- Returned R object is a valid Spectra object with class(.) == 'Spectra' and passes bioconductor/Spectra schema checks.55- Peak data (mz and intensity list-columns) are present and match expected dimensions after round-trip serialization.56- Metadata variables (precursorMz, msLevel, name, id) are preserved with identical values before and after serialization.57- Python function outputs (e.g., similarity scores, normalized intensities) are successfully imported back into R as numeric matrices or vectors with expected dimensions and value ranges.58- No data loss or NaN values introduced during serialization/deserialization; compare row counts and peak counts before and after.5960## Limitations6162- Python version ≥ 3.12 must be installed on the system; SpectriPy cannot initialize without it.63- Requires explicit installation of Python dependencies (matchms 0.31, spectrum_utils 0.3.2, numpy 2.2.0) either via reticulate's auto-install or manual system/environment setup; missing packages will cause deserialization to fail.64- First serialization call incurs Python environment initialization overhead (slower than subsequent calls).65- Spectra objects lacking required peak data (empty mz or intensity columns) cannot be serialized; will raise errors or produce incomplete Python objects.66- The reticulate interface may encounter version conflicts or platform-specific issues if Python or dependency versions differ from tested/documented versions.6768## Evidence6970- [intro] SpectriPy integrates Python MS packages into R by wrapping Python functionality into R functions, enabling the use of Python libraries within a Spectra-based MS analysis workflow in R.: "By wrapping Python functionality into R functions, *SpectriPy* allows a seamless integration of Python libraries into R"71- [readme] SpectriPy provides conversion functions between Spectra objects and Python spectral objects from matchms and spectrum_utils.: "contains functions to convert between R's `Spectra::Spectra` objects and `matchms.Spectrum` and `spectrum_utils.spectrum.MsmsSpectrum` objects from the Python [*matchms*](https://github.com/matchms)"72- [readme] The reticulate package manages Python environment setup and automatic library installation via py_require().: "*SpectriPy*'s Python library management uses the [`py_require()`](https://rstudio.github.io/reticulate/reference/py_require.html) function introduced in *reticulate* version 1.41"73- [readme] Serialized objects must preserve all spectral attributes and variables when round-tripping between R and Python.: "R and Python spectral objects are easily translated and available in one workflow (i.e., a quarto document)"74- [readme] First serialization call includes Python environment initialization overhead.: "Note also that the first `compareSpectriPy()` call takes usually a little longer because the Python setup has to be initialized."
HolobiomicsLab