SpectriPy_logo

The SpectriPy package allows integration of Python MS packages into a Spectra-based MS analysis in R. By wrapping Python functionality into R functions, SpectriPy allows a seamless integration of Python libraries into R. For example, SpectriPy can leverage the spectral similarity, filtering, normalization etc. calculations from the Python matchms library and contains functions to convert between R’s Spectra::Spectra objects and matchms.Spectrum and spectrum_utils.spectrum.MsmsSpectrum objects from the Python matchms and spectrum_utils libraries, respectively. R and Python spectral objects are easily translated and available in one workflow (i.e., a quarto document), enabling the advanced user or developer to create custom functions or workflows on Spectra objects in Python and executing them in R using the reticulate R package, and vice versa.

If you use SpectriPy in your research, please cite:

Installation

SpectriPy needs Python (version >= 3.12) to be installed on the system. All necessary Python libraries (listed below) are automatically installed by the reticulate R package. SpectriPy’s Python library management uses the py_require() function introduced in reticulate version 1.41 and should hence work on most system without problems. To install SpectriPy:

install.packages("BiocManager")
BiocManager("SpectriPy")

In addition it is possible to install the Python libraries manually (e.g., for the system Python version) and specify the version of Python (or of the local virtualenv or conda environment) using the RETICULATE_PYTHON or RETICULATE_PYTHON_ENV environment variables. If any of these environment variables are defined, all Python libraries listed below must be installed, since SpectriPy (respectively reticulate) will not try to install them automatically. The required Python libraries with the suggested and tested versions are:

matchms 0.30.0
spectrum_utils 0.3.2
numpy 2.2.0

See also sections Startup and Python configuration for more details or Fixing package installation or loading problems if installation or loading fails.

Documentation for users

See the extensive documentation for the use of SpectriPy:

The rendered SpectriPy package’s vignette,
The function reference,
A tutorial for the annotation of LC-MS/MS spectra using an MGF library and the ModifiedCosine algorithm from matchms.

TLDR:

#' R session:

library(Spectra)
library(SpectriPy)

Example: Spectra similarity calculations using `matchms`

The SpectriPy package provides the compareSpectriPy() function that allows to perform spectra similarity calculations using the scoring functions from MS Python packages. For example, the CosineGreedy parameter CosineGreedyParam from the matchms Python package.

We create some simple example spectra.

#' R session:

library(Spectra)
library(SpectriPy)

#' Create a Spectra object with two MS2 spectra for Caffeine.
caf <- DataFrame(
    msLevel = c(2L, 2L),
    name = "Caffeine",
    precursorMz = c(195.0877, 195.0877)
)
caf$intensity <- list(
    c(340.0, 416, 2580, 412),
    c(388.0, 3270, 85, 54, 10111))
caf$mz <- list(
    c(135.0432, 138.0632, 163.0375, 195.0880),
    c(110.0710, 138.0655, 138.1057, 138.1742, 195.0864))
caf <- Spectra(caf)

#' Create a Spectra object with two MS2 spectra for 1-Methylhistidine
mhd <- DataFrame(
    msLevel = c(2L, 2L),
    precursorMz = c(170.0924, 170.0924),
    id = c("HMDB0000001", "HMDB0000001"),
    name = c("1-Methylhistidine", "1-Methylhistidine"))
mhd$mz <- list(
    c(109.2, 124.2, 124.5, 170.16, 170.52),
    c(83.1, 96.12, 97.14, 109.14, 124.08, 125.1, 170.16))
mhd$intensity <- list(
    c(3.407, 47.494, 3.094, 100.0, 13.240),
    c(6.685, 4.381, 3.022, 16.708, 100.0, 4.565, 40.643))
mhd <- Spectra(mhd)

We calculate pairwise similarities between all spectra defined above and those of caffeine using Spectra’s built-in compareSpectra() function.

#' R session:

all <- c(caf, mhd)
res_r <- compareSpectra(all, caf)
res_r

We calculate the similarity using the CosineGreedy function from matchms, changing the tolerance to a value of 0.05 (instead of the default 0.1).

#' R session:

res <- compareSpectriPy(all, caf, param = CosineGreedy(tolerance = 0.05))
res

As a result compareSpectriPy() returns also a numeric matrix of similarities. Note also that the first compareSpectriPy() call takes usually a little longer because the Python setup has to be initialized.

Documentation for developers

See the developer notes.

Contributions

Contributions are highly welcome and should follow the contribution guidelines. General information on the package structure and some helpful pointers are given in the developer notes document. Also, please check the coding style guidelines and importantly, follow our code of conduct.

License

See the DESCRIPTION and LICENSE file.