refactor: replace clean with filterIntensity (issue #89)

- Remove the `clean` method.
- Add the `filterIntensity` method.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Spectra
 Title: Spectra Infrastructure for Mass Spectrometry Data
-Version: 0.5.4
+Version: 0.5.5
 Description: The Spectra package defines a efficient infrastructure
    for storing and handling for raw mass spectrometry spectra.
 Authors@R: c(person(given = "Laurent", family = "Gatto",

NAMESPACE

@@ -44,7 +44,6 @@ exportMethods(backendMerge)
 exportMethods(bin)
 exportMethods(c)
 exportMethods(centroided)
-exportMethods(clean)
 exportMethods(collisionEnergy)
 exportMethods(compareSpectra)
 exportMethods(containsMz)
@@ -56,6 +55,7 @@ exportMethods(filterAcquisitionNum)
 exportMethods(filterDataOrigin)
 exportMethods(filterDataStorage)
 exportMethods(filterEmptySpectra)
+exportMethods(filterIntensity)
 exportMethods(filterIsolationWindow)
 exportMethods(filterMsLevel)
 exportMethods(filterPolarity)
@@ -100,6 +100,7 @@ importClassesFrom(S4Vectors,DataFrame)
 importFrom(BiocParallel,SerialParam)
 importFrom(BiocParallel,bpparam)
 importFrom(IRanges,NumericList)
+importFrom(MsCoreUtils,between)
 importFrom(MsCoreUtils,bin)
 importFrom(MsCoreUtils,coefMA)
 importFrom(MsCoreUtils,coefSG)

R/AllGenerics.R

@@ -21,8 +21,6 @@ setGeneric("bin", function(x, ...) standardGeneric("bin"))
 #' @rdname hidden_aliases
 setMethod("bin", "numeric", MsCoreUtils::bin)
 #' @rdname hidden_aliases
-setGeneric("clean", function(object, ...) standardGeneric("clean"))
-#' @rdname hidden_aliases
 setGeneric("compareSpectra", function(x, y, ...)
     standardGeneric("compareSpectra"))
 #' @rdname hidden_aliases
@@ -35,6 +33,9 @@ setGeneric("containsNeutralLoss", function(object, ...)
 setGeneric("dropNaSpectraVariables", function(object, ...)
     standardGeneric("dropNaSpectraVariables"))
 #' @rdname hidden_aliases
+setGeneric("filterIntensity", function(object, ...)
+    standardGeneric("filterIntensity"))
+#' @rdname hidden_aliases
 setGeneric("isReadOnly", function(object, ...)
     standardGeneric("isReadOnly"))
 #' @rdname hidden_aliases

R/Spectra.R

@@ -336,10 +336,6 @@ NULL
 #' - `bin`: aggregates individual spectra into discrete (m/z) bins. All
 #'   intensity values for peaks falling into the same bin are summed.
 #'
-#' - `clean`: removes 0-intensity data points. For `all = FALSE` (the default)
-#'   0-intensity peaks next to non-zero intensity peaks are retained while with
-#'   `all = TRUE` all 0-intensity peaks are removed.
-#'
 #' - `combineSpectra`: combine sets of spectra into a single spectrum per set.
 #'   For each spectrum group (set), spectra variables from the first spectrum
 #'   are used and the peak matrices are combined using the function specified
@@ -373,6 +369,15 @@ NULL
 #'   the comparison of `x[2]` with `y[3]`). If `SIMPLIFY = TRUE` the `matrix`
 #'   is *simplified* to a `numeric` if length of `x` or `y` is one.
 #'
+#' - `filterIntensity`: filters each spectrum keeping only peaks with
+#'   intensities that are within the provided range (parameter `intensity`). To
+#'   remove only peaks with intensities below a certain threshold, say 100, use
+#'   `intensity = c(100, Inf)`. Note: also a single value can be passed with
+#'   the `intensity` parameter in which case an upper limit of `Inf` is used.
+#'   Note that this function removes also peaks with missing intensities
+#'   (i.e. an intensity of `NA`). Parameter `msLevel.` allows to restrict the
+#'   filtering to spectra of the specified MS level(s).
+#'
 #' - `lapply`: apply a given function to each spectrum in a `Spectra` object.
 #'   The `Spectra` is splitted into individual spectra and on each of them
 #'   (i.e. `Spectra` of length 1) the function `FUN` is applied. Additional
@@ -427,10 +432,6 @@ NULL
 #'
 #' @return See individual method description for the return value.
 #'
-#' @param all for `clean`: `logical(1)` whether all 0 intensity peaks should be
-#'     removed (`TRUE`) or whether 0-intensity peaks directly adjacent to a
-#'     non-zero intensity peak should be kept (`FALSE`).
-#'
 #' @param acquisitionNum for `filterPrecursorScan`: `integer` with the
 #'     acquisition number of the spectra to which the object should be
 #'     subsetted.
@@ -498,6 +499,11 @@ NULL
 #'     total ion current should be (re)calculated on the actual data
 #'     (`initial = FALSE`, same as `ionCount`).
 #'
+#' @param intensity For `filterIntensity`: `numeric` of length 1 or 2 defining
+#'     either the lower or the lower and upper intensity limit for the
+#'     filtering. Defaults to `intensity = c(0, Inf)` thus only peaks with `NA`
+#'     intensity are removed.
+#'
 #' @param k For `pickPeaks`: `integer(1)`, number of values left and right of
 #'  the peak that should be considered in the weighted mean calculation.
 #'
@@ -762,8 +768,8 @@ NULL
 #' intensity(res)[[1]]
 #' intensity(res)[[2]]
 #'
-#' ## Clean all spectra removing all 0-intensity peaks.
-#' res <- clean(res, all = TRUE)
+#' ## Remove all peaks with an intensity below 40.
+#' res <- filterIntensity(res, intensity = c(40, Inf))
 #'
 #' ## Get the intensities of the first and second spectrum.
 #' intensity(res)[[1]]
@@ -1466,19 +1472,25 @@ setMethod("bin", "Spectra", function(x, binSize = 1L, breaks = NULL,
 
 #' @rdname Spectra
 #'
-#' @exportMethod clean
-setMethod("clean", "Spectra",
-          function(object, all = FALSE, msLevel. = unique(msLevel(object))) {
-              if (!is.logical(all) || length(all) != 1)
-                  stop("Argument 'all' must be a logical of length 1")
+#' @exportMethod filterIntensity
+setMethod("filterIntensity", "Spectra",
+          function(object, intensity = c(0, Inf),
+                   msLevel. = unique(msLevel(object))) {
               if (!.check_ms_level(object, msLevel.))
                   return(object)
-              object <- addProcessing(object, .peaks_clean, all = all,
+              if (length(intensity) == 1)
+                  intensity <- c(intensity, Inf)
+              if (length(intensity) != 2)
+                  stop("'intensity' should be of length specifying a lower ",
+                       "intensity limit or of length two defining a lower and",
+                       " upper limit.")
+              object <- addProcessing(object, .peaks_filter_intensity,
+                                      intensity = intensity,
                                       msLevel = msLevel.)
-              object@processing <- .logging(object@processing,
-                                            "Spectra of MS level(s) ",
-                                            paste0(msLevel., collapse = ", "),
-                                            " cleaned.")
+              object@processing <- .logging(
+                  object@processing, "Remove peaks with intensities outside [",
+                  intensity[1], ", ", intensity[2], "] in spectra of MS level(s) ",
+                  paste0(msLevel., collapse = ", "), ".")
               object
           })
 

tests/testthat/test_Spectra-functions.R

@@ -37,7 +37,8 @@ test_that(".apply_processing_queue works", {
     expect_equal(vapply(res, nrow, integer(1)), vapply(pks, nrow, integer(1)))
 
     ## Length 2
-    pq <- c(pq, list(ProcessingStep(.peaks_clean, list(all = TRUE))))
+    pq <- c(pq, list(ProcessingStep(.peaks_filter_intensity,
+                                    list(intensity = c(0.1, Inf)))))
     res <- .apply_processing_queue(pks, msLevel(be),
                                    rep(TRUE, length(be)), pq)
     expect_true(all(vapply(res, function(z) all(z[z[, 2] > 0, 2] > 50000),
@@ -63,13 +64,15 @@ test_that(".peaksapply works", {
     res_2 <- .peaksapply(sps)
     expect_equal(res, res_2)
 
-    res_3 <- .peaksapply(sps, FUN = .peaks_clean, all = TRUE)
+    res_3 <- .peaksapply(sps, FUN = .peaks_filter_intensity,
+                         intensity = c(0.1, Inf))
     expect_true(all(vapply(res_3, nrow, integer(1)) <
                     vapply(res_2, nrow, integer(1))))
     expect_true(!any(vapply(res_3, function(z) any(z[, 2] == 0), logical(1))))
 
     sps@processingQueue <- c(sps@processingQueue,
-                             list(ProcessingStep(.peaks_clean, list(all = TRUE))))
+                             list(ProcessingStep(.peaks_filter_intensity,
+                                                 list(intensity = c(0.1, Inf)))))
     res_4 <- .peaksapply(sps)
     expect_equal(res_3, res_4)
 })
@@ -79,8 +82,9 @@ test_that("applyProcessing works", {
     sps_mzr <- filterRt(Spectra(sciex_mzr), rt = c(10, 20))
     ## Add processings.
     centroided(sps_mzr) <- TRUE
-    sps_mzr <- replaceIntensitiesBelow(sps_mzr, threshold = 5000)
-    sps_mzr <- clean(sps_mzr, all = TRUE)
+    sps_mzr <- replaceIntensitiesBelow(sps_mzr, threshold = 5000,
+                                       value = NA_real_)
+    sps_mzr <- filterIntensity(sps_mzr)
     expect_true(length(sps_mzr@processingQueue) == 2)
     expect_error(applyProcessing(sps_mzr), "is read-only")
 
@@ -207,7 +211,8 @@ test_that(".lapply works", {
     expect_identical(rtime(sps) + 3, unlist(res, use.names = FALSE))
 
     ## After clean and stuff
-    spsc <- clean(replaceIntensitiesBelow(sps, threshold = 4000), all = TRUE)
+    spsc <- filterIntensity(replaceIntensitiesBelow(
+        sps, threshold = 4000, value = NA_real_))
     res <- .lapply(spsc, FUN = function(z) sum(intensity(z)))
     res_2 <- vapply(intensity(spsc), sum, numeric(1))
     expect_identical(unlist(res, use.names = FALSE), res_2)