conversion: Converting between R and Python MS data structures

In rformassspectrometry/SpectriPy: Enhancing Cross-Language Mass Spectrometry Data Analysis with R and Python

Converting between R and Python MS data structures

Description

The rspec_to_pyspec() and pyspec_to_rspec() functions allow to convert (translate) MS data structures between R and Python. At present the R Spectra::Spectra() objects can be either translated into a list of matchms Python matchms.Spectrum objects or spectrum_utils Python spectrum_utils.spectrum.MsmsSpectrum objects. For better integration with the reticulate R package also a r_to_py.Spectra() method is available.

The mapping of spectra variables (in R) to (Python) spectra metadata can be configured and defined with the setSpectraVariableMapping() and spectraVariableMapping(). These get and set the global (system wide) setting and are thus also used by the r_to_py() method.

Properties for translation to the MS data objects of the different Python libraries are:

• matchms: the matchms.Spectrum objects support arbitrary metadata, so any spectra variable can be translated and stored in these objects.

• spectrum_utils: the spectrum_utils.spectrum.MsmsSpectrum object supports metadata variables identifier (character), precursor_mz (numeric), precursor_charge (integer) and optionally also retention_time (numeric).

See the indivudual function's documentation for more details.

Function to convert R Spectra objects into a Python list of matchms Spectrum objects using the reticulate package.

Usage

## S4 method for signature 'character'
spectraVariableMapping(object, ...)

## S4 method for signature 'missing'
spectraVariableMapping(object, ...)

setSpectraVariableMapping(x)

defaultSpectraVariableMapping()

## S3 method for class 'Spectra'
r_to_py(x, convert = FALSE)

rspec_to_pyspec(
  x,
  mapping = spectraVariableMapping(),
  pythonLibrary = c("matchms", "spectrum_utils")
)

pyspec_to_rspec(
  x,
  mapping = spectraVariableMapping(),
  pythonLibrary = c("matchms", "spectrum_utils")
)

Arguments

object	For spectraVariableMapping(): not used.
...	For spectraVariableMapping(): not used.
x	Spectra object.
convert	Boolean; should Python objects be automatically converted to their R equivalent? Defaults to FALSE.
mapping	named character() vector defining which spectra variables/metadata should be translated between R and Python and how they should be renamed. Defaults to spectraVariableMapping().
pythonLibrary	For rspec_to_pyspec() and pyspec_to_rspec(): character(1) defining the Python library to which (or from which) data structures the data should be converted. Possible options are "matchms" or "spectrum_utils" with "matchms" being the default.

Value

For r_to_py.Spectra() and rspec_to_pyspec(): Python list of MS data structures, either matchms.Spectrum or spectrum_utils.spectrum.MsmsSpectrum objects. For pyspec_to_rspec(): Spectra::Spectra() with the MS data of all matchms.Spectrum objects in the submitted list.

Translation of MS data objects

MS data structures can be translated between R and Python using the rspec_to_pyspec() and pyspec_to_rspec() functions, or with the r_to_py() method.

• rspec_to_pyspec() translates an R Spectra::Spectra() object into a list of Python MS data objects, which can be, depending on parameter pythonLibrary, matchms.Spectrum objects (for pythonLibrary = "matchms", the default) or spectrum_utils.spectrum.MsmsSpectrum objects (for pythonLibrary = "spectrum_utils"). Parameter mapping allows to specify which spectra variables from the Spectra object x should be converted in addition to the peaks data (m/z and intensity values). It defaults to mapping = spectraVariableMapping() (See the respective help below for more information on the variable mapping). While being fast, this function first loads all peaks and spectra data into memory before translating to Python data structures. A less memory intense operation could be to call this function in a loop to only load parts of the data at a time into memory.

• pyspec_to_rspec() translates a single, or a list of matchms.Spectrum objects (with parameter pythonLibrary = "matchms", the default) or a list of spectrum_utils.spectrum.MsmsSpectrum objects (with parameter pythonLibrary = "spectrum_utils") to a Spectra::Spectra() object. Parameter mapping allows to specify the metadata variables that should be translated and mapped in addition to the peaks data. The library used to represent the MS data in Python needs to be specified with parameter pythonLibrary.

• r_to_py.Spectra() is equivalent to rspec_to_pyspec(pythonLibrary = "matchms"). The spectra variables that should be converted can be configures with setSpectraVariableMapping() (see documentation below).

Mapping of spectra variables (metadata)

Metadata for MS spectra are represented and stored as spectra variables in the R Spectra::Spectra() objects. Also Python MS data structures store such metadata along with the mass peak data. While spectra metadata is thus supported by data structures in both programming languages, different names and naming conventions are used. The spectraVariableMapping() and setSpectraVariableMapping() functions allow to define how the names of spectra metadata (spectra variables) should be translated between R and Python. To support also the different naming conventions used by the Python libraries matchms and spectrum_utils, spectraVariableMapping() defines different mapping schemes for these, using by default the mapping for matchms. Note also that spectrum_utils supports only few selected metadata/spectra variables, so any additional spectra variables defined by the mapping will be ignored. The r_to_py() and py_to_r() functions will use the selected naming scheme to name the spectra variables accordingly. Also, only spectra metadata/variables in spectraVariableMapping() will be translated. The initial mapping is based on this definition in matchms.

• defaultSpectraVariableMapping(): returns the default mapping between spectra variables and Python metadata names for the matchms library.

• spectraVariableMapping(): returns the currently defined spectra variable mapping as a named character vector, with names representing the names of the spectra variables in R and elements the respective names of the spectra metadata in Python. Use Spectra::spectraVariables() on the Spectra object that should be converted with r_to_py() to list all available spectra variables. r_to_py() and py_to_r() for MS data structures will use this default mapping. Calling spectraVariableMapping() defining also the Python library (e.g., spectraVariableMapping("matchms") or spectraVariableMapping("spectrum_utils")) will return the variable mapping for the specified Python library.

• setSpectraVariableMapping(): sets/replaces the currently defined mapping of spectra variable names to Python metadata names. Setting setSpectraVariableMapping(character()) will only convert the mass peaks data (m/z and intensity values) but no spectra metadata.

Author(s)

Michael Witting, Johannes Rainer, Wout Bittremieux, Thomas Naake

Examples

## Import a MGF file as a `Spectra` object
library(MsBackendMgf)
library(SpectriPy)
s <- Spectra(
    system.file("extdata", "mgf", "spectra2.mgf", package = "SpectriPy"),
    source = MsBackendMgf())
s

#########################
## Conversion R to Python

## A `Spectra` can be translated to a `list` of `matchms.Spectrum` objects
## using either the `r_to_py()` method or the `rspec_to_pyspec()` function:
s_py <- r_to_py(s)
s_py

## The `s_py` can now be used like any other Python variable within the R
## *reticulate* framework. Below we extract the m/z values of the first
## spectrum
s_py[0]$mz

## Extracting that information from the `Spectra` object in R
s[1]$mz

## The `spectraVariableMapping()` defines which spectra variables (metadata)
## should be translated between R and Python:
spectraVariableMapping()

## The names of that character vector represent the names of the spectra
## variables in R, the elements the name of the metadata variable in Python.
## Below we list the available metadata information from the first
## Spectrum in Python
s_py[0]$metadata

## `setSpectraVariableMapping()` allows to replace the default mapping
## of variables. Below we e.g. add a new spectra variable to the `Spectra`
## object.
s$new_col <- 1:4

## To translate that variable to Python we need to include it to the
## `spectraVariableMapping()`. Below we define to translate only the
## precursor m/z and the new spectra variable to Python. Be aware that
## `setSpectraVariableMapping()` **globally** sets the default for any
## spectra variable mapping between R and Python. Thus, any subsequent
## calls mapping calls will use the same mapping. It is suggested to
## eventually *restore* the default mapping again after the call or
## use the `rspec_to_pyspec()` function instead, that allows to configure
## the mapping using a parameter `mapping`.
setSpectraVariableMapping(
    c(precursorMz = "precursor_mz", new_col = "new_col"))
s_py <- r_to_py(s)

s_py[0]$metadata

## Restoring the global spectra variable mapping configuration to
## the default mapping:
setSpectraVariableMapping(defaultSpectraVariableMapping())

## As an alternative to the `r_to_py()` we can use the `rspec_to_pyspec()`
## function and provide a custom mapping using the `mapping` parameter:
s_py <- rspec_to_pyspec(
    s, mapping = c(precursorMz = "precursor_mz", new_col = "new_col"))

## Convert to MS data objects from the spectrum_utils Python library
s_py2 <- rspec_to_pyspec(
    s, mapping = spectraVariableMapping("spectrum_utils"),
    pythonLibrary = "spectrum_utils")

## Convert the data back to R
pyspec_to_rspec(s_py2, pythonLibrary = "spectrum_utils")

#########################
## Conversion Python to R

## A `list` of `matchms.Spectrum` objects in Python can be translated into
## the corresponding MS data structure in R (i.e. a `Spectra`) object using
## the `pyspec_to_rspec()` function:
res <- pyspec_to_rspec(s_py)
res

## All spectra from Python are thus converted into a single `Spectra` object.

## Or providing a custom variable mapping:
res <- pyspec_to_rspec(
    s_py, mapping = c(precursorMz = "precursor_mz", new_col = "new_col"))
res$new_col

rformassspectrometry/SpectriPy documentation built on June 11, 2025, 12:49 a.m.