feat: add additional replacement methods

- Add `mz<-` and `intensity<-` methods.

Author: jorainer

NAMESPACE

@@ -50,6 +50,8 @@ importFrom(reticulate,py_run_string)
 importFrom(reticulate,py_set_attr)
 importFrom(reticulate,py_to_r)
 importFrom(reticulate,r_to_py)
+importMethodsFrom(ProtGenerics,"intensity<-")
+importMethodsFrom(ProtGenerics,"mz<-")
 importMethodsFrom(ProtGenerics,"peaksData<-")
 importMethodsFrom(ProtGenerics,"spectraData<-")
 importMethodsFrom(ProtGenerics,acquisitionNum)

NEWS.md

@@ -12,6 +12,7 @@
   variables that contain only missing values.
 - Add `$<-` method for `MsBackendPy`.
 - Add `peaksData()<-` for `MsBackendPy`.
+- Add `intensity()<-` and `mz()<-` methods for `MsBackendPy`.
 
 ## Changes in 0.99.11
 

R/MsBackendPython.R

@@ -55,6 +55,12 @@
 #' If for example data was transformed or metadata added or removed in the
 #' Python object, it immediately affects the `Spectra`/backend.
 #'
+#' Any replacement operation uses internally the `spectraData()<-` method,
+#' thus replacing/updating values for individual spectra variables or peaks
+#' variables will first load the current data from Python to R, update or
+#' replace the values and then store the full MS data again to the
+#' referenced Python attribute.
+#'
 #' @section `MsBackendPy` methods:
 #'
 #' The `MsBackendPy` supports all methods defined by the [Spectra::MsBackend()]
@@ -91,6 +97,28 @@
 #'   instance of `MsBackendPy`. See examples below for different settings
 #'   and conversion of spectra variables.
 #'
+#' - `intensity()`, `intensity()<-`: get or replace the intensity values.
+#'   `intensity()` returns a `NumericList` of length equal to the number of
+#'   spectra with each element being the intensity values of the individual
+#'   mass peaks per spectrum. `intensity()<-` takes the same list-like
+#'   structure as input parameter. Both the number of spectra and the number of
+#'   peaks must match the length of the spectra and the number of existing mass
+#'   peaks. To change the number of peaks use the `peaksData()<-` method
+#'   instead that replaces the *m/z* and intensity values at the same time.
+#'   Calling `intensity()<-` will replace the full MS data (spectra variables
+#'   as well as peaks variables) of the associated Python variable.
+#'
+#' - `mz()`, `mz()<-`: get or replace the *m/z* values. `mz()` returns a
+#'   `NumericList` of length equal to the number of spectra with each element
+#'   being the *m/z* values of the individual mass peaks per spectrum.
+#'   `mz()<-` takes the same list-like structure as input parameter. Both the
+#'   number of spectra and the number of peaks must match the length of the
+#'   spectra and the number of existing mass peaks. To change the number of
+#'   peaks use the `peaksData()<-` method instead that replaces the *m/z* and
+#'   intensity values at the same time.
+#'   Calling `mz()<-` will replace the full MS data (spectra variables
+#'   as well as peaks variables) of the associated Python variable.
+#'
 #' - `peaksData()`: extracts the peaks data matrices from the backend. Python
 #'   code is applied to the data structure in Python to
 #'   extract the *m/z* and intensity values as a list of (numpy) arrays. These
@@ -628,6 +656,18 @@ setMethod("intensity", "MsBackendPy", function(object) {
     NumericList(peaksData(object, "intensity", drop = TRUE), compress = FALSE)
 })
 
+#' @importMethodsFrom ProtGenerics intensity<-
+#'
+#' @rdname MsBackendPy
+setReplaceMethod("intensity", "MsBackendPy", function(object, value) {
+    .check_mz_intensity(value, length(object), lengths(object))
+    spd <- spectraData(object, union(names(spectraVariableMapping(object)),
+                                     peaksVariables(object)))
+    spd[["intensity"]] <- value
+    spectraData(object) <- spd
+    object
+})
+
 #' @importMethodsFrom ProtGenerics isolationWindowLowerMz
 setMethod("isolationWindowLowerMz", "MsBackendPy", function(object) {
     spectraData(object, "isolationWindowLowerMz", drop = TRUE)
@@ -653,6 +693,18 @@ setMethod("mz", "MsBackendPy", function(object) {
     NumericList(peaksData(object, "mz", drop = TRUE), compress = FALSE)
 })
 
+#' @importMethodsFrom ProtGenerics mz<-
+#'
+#' @rdname MsBackendPy
+setReplaceMethod("mz", "MsBackendPy", function(object, value) {
+    .check_mz_intensity(value, length(object), lengths(object))
+    spd <- spectraData(object, union(names(spectraVariableMapping(object)),
+                                     peaksVariables(object)))
+    spd[["mz"]] <- value
+    spectraData(object) <- spd
+    object
+})
+
 #' @importMethodsFrom ProtGenerics polarity
 setMethod("polarity", "MsBackendPy", function(object) {
     spectraData(object, "polarity", drop = TRUE)
@@ -877,3 +929,25 @@ reindex <- function(object) {
     keep <- c(setdiff(colnames(x), svs), svs[keep])
     x[, colnames(x) %in% keep, drop = FALSE]
 }
+
+#' helper to check input/validity of intensity or mz: has to be a list-like
+#' structure with numeric vectors.
+#'
+#' @param x `list` or `NumericList`.
+#'
+#' @param l `integer(1)` with the number of spectra/expected elements in `x`.
+#'
+#' @param ls `integer` with the number of peaks, i.e., the lengths of the
+#'     numeric vectors.
+#'
+#' @noRd
+.check_mz_intensity <- function(x, l = length(x), ls = lengths(x)) {
+    if (!(is.list(x) | inherits(x, "SimpleList")))
+        stop("'value' has to be a list-like data structure.")
+    if (length(x) != l)
+        stop("length of 'value' has to match the number of spectra")
+    if (!all(lengths(x) == ls))
+        stop("lengths(value) has to match the number of peaks per spectrum")
+    if (!all(vapply1l(x, is.numeric)))
+        stop("elements of 'value' are expected to be numeric vectors.")
+}

man/MsBackendPy.Rd

@@ -709,6 +709,60 @@ test_that("peaksData<-,MsBackendPy works", {
     expect_equal(spd, spd_2)
 })
 
+test_that(".check_mz_intensity works", {
+    mzs <- mz(s)
+    expect_silent(.check_mz_intensity(mzs, length(mzs), lengths(mzs)))
+    expect_silent(.check_mz_intensity(as.list(mzs), length(mzs), lengths(mzs)))
+    expect_error(.check_mz_intensity(3, 1, 1), "list-like")
+    expect_error(.check_mz_intensity(mzs, 1, 1), "number of spectra")
+    expect_error(.check_mz_intensity(mzs[1:3], 3, c(3, 3, 3)),
+                 "number of peaks")
+    a <- list(c(1:4), c(1.1, 2.2, 3), c("a", "b"))
+    expect_error(.check_mz_intensity(a, 4, c(4, 3, 2)), "number of spectra")
+    expect_error(.check_mz_intensity(a, 3, c(4, 1, 2)), "number of peaks")
+    expect_error(.check_mz_intensity(a, 3, c(4, 3, 2)), "numeric vectors")
+})
+
+test_that("mz<-,MsBackendPy works", {
+    a <- setBackend(
+        s, MsBackendPy(), pythonVariableName = "mz_test",
+        spectraVariableMapping = c(INCHI = "inchi",
+                                   defaultSpectraVariableMapping()))@backend
+    spd <- spectraData(a)
+    mzs <- mz(a)
+    expect_equal(spd$mz, mzs)
+    mzs <- mzs / 3
+    mz(a) <- mzs
+    expect_equal(mz(a), mzs)
+    expect_equal(a$INCHI, spd$INCHI)
+    mzs <- as.list(mzs)
+    mzs[[1L]] <- mzs[[1L]] * 2
+    mz(a) <- mzs
+    expect_equal(as.list(mz(a)), mzs)
+    ## errors/issues
+    expect_error(mz(a) <- mzs[1:3], "match the number")
+})
+
+test_that("intensity<-,MsBackendPy works", {
+    a <- setBackend(
+        s, MsBackendPy(), pythonVariableName = "intensity_test",
+        spectraVariableMapping = c(INCHI = "inchi",
+                                   defaultSpectraVariableMapping()))@backend
+    spd <- spectraData(a)
+    ints <- intensity(a)
+    expect_equal(spd$intensity, ints)
+    ints <- ints / 3
+    intensity(a) <- ints
+    expect_equal(intensity(a), ints)
+    expect_equal(a$INCHI, spd$INCHI)
+    ints <- as.list(ints)
+    ints[[1L]] <- ints[[1L]] * 2
+    intensity(a) <- ints
+    expect_equal(as.list(intensity(a)), ints)
+    ## errors/issues
+    expect_error(intensity(a) <- ints[1:3], "match the number")
+})
+
 ## Comments, thoughts TODO
 ## DONE spectraData()<-: replaces the full data and allows adding/removing
 ##      spectra variables. number of spectra has to match.
@@ -718,8 +772,8 @@ test_that("peaksData<-,MsBackendPy works", {
 ##      in @spectraVariableMapping
 ## DONE $<- : replace the full data?
 ## DONE peaksData()<-: replace the full data?
-## TODO mz()<-
-## TODO intensity()<-
+## DONE mz()<-
+## DONE intensity()<-
 ## TODO applyProcessing(): replace the full data? is that needed? should
 ##      internally call peaksData()<-
 ## DONE all other replacement methods.

tests/testthat/test_MsBackendPython.R

@@ -631,6 +631,17 @@ sps$SMILES |> head()
 See also the next section for more information on the mapping between
 `Spectra`'s spectra variables and *matchms* metadata.
 
+The `MsBackendPy` has full *read/write* support, i.e., it allows to add new
+spectra variables or change existing spectra and/or peaks variables through the
+available replacement methods `spectraData()<-`, `peaksData()<-`,
+`intensity()<-`, `mz()<-` and `$<-`. Currently, this operations change however
+the full MS data of the associated Python variable. Thus, even if for example
+only the retention times are replaced using `$rtime<-`, the (full!) data is
+first loaded from Python to R, the retention time values are then replaced and
+finally the full data (spectra and peaks variables) are again stored to the
+associated Python variable. Replacement operations are thus quite memory
+demanding.
+
 ## Conversion of spectra variables
 
 Conversion of the MS peaks data (i.e. the *m/z* and intensity values) is always