From bd1784b5735c924fb95e79aa368219e5f7654e0f Mon Sep 17 00:00:00 2001 From: Johannes Rainer Date: Thu, 18 Jul 2024 17:01:30 +0200 Subject: [PATCH] docs: fix Phili's comments --- DESCRIPTION | 2 +- R/MsBackend.R | 2 +- R/Spectra-functions.R | 23 ++++++++++++++--------- R/Spectra.R | 15 +++++++++------ man/MsBackend.Rd | 2 +- man/Spectra.Rd | 15 +++++++++------ man/filterPeaksRanges.Rd | 23 ++++++++++++++--------- 7 files changed, 49 insertions(+), 33 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 082e156a..47b81ac5 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: Spectra Title: Spectra Infrastructure for Mass Spectrometry Data -Version: 1.15.4 +Version: 1.15.5 Description: The Spectra package defines an efficient infrastructure for storing and handling mass spectrometry spectra and functionality to subset, process, visualize and compare spectra data. It provides different diff --git a/R/MsBackend.R b/R/MsBackend.R index dc73ee5f..eae122b1 100644 --- a/R/MsBackend.R +++ b/R/MsBackend.R @@ -774,7 +774,7 @@ #' #' @return See documentation of respective function. #' -#' @author Johannes Rainer, Sebastian Gibb, Laurent Gatto +#' @author Johannes Rainer, Sebastian Gibb, Laurent Gatto, Philippine Louail #' #' @md #' diff --git a/R/Spectra-functions.R b/R/Spectra-functions.R index 67d47517..8bb9042d 100644 --- a/R/Spectra-functions.R +++ b/R/Spectra-functions.R @@ -1194,11 +1194,11 @@ processingChunkFactor <- function(x) { #' has to be an available spectra or peaks variable. `` can be a #' `numeric` of length 2 defining the lower and upper boundary, or a `numeric` #' two-column matrix (multi-row matrices are also supported, see further -#' below). `filterPeaksRanges(s, mz = c(200, 300))` woudl for example reduce +#' below). `filterPeaksRanges(s, mz = c(200, 300))` would for example reduce #' the peaks matrices of the `Spectra` object `s` to mass peaks with an m/z #' value between 200 and 300. `filterPeaksRanges()` returns the original #' `Spectra` object with the filter operation added to the processing queue. -#' Thus, the filter gets only applied when the peaks data gets extracted +#' Thus, the filter gets **only** applied when the peaks data gets extracted #' with `mz()`, `intensity()` or `peaksData()`. If ranges for both spectra #' **and** peaks variables are defined, the function evaluates first whether #' the spectra variable value for a spectrum is within the provided range and, @@ -1221,19 +1221,24 @@ processingChunkFactor <- function(x) { #' or peaks variables) have to match. #' #' **Missing value handling**: any comparison which involves a missing value -#' (beingvit a spectra variable value, a peaks variable value or a value -#' in one of thevprovided ranges) is treated as a logical `FALSE`. For +#' (being it a spectra variable value, a peaks variable value or a value +#' in one of the provided ranges) is treated as a logical `FALSE`. For #' example, if the retention time of a spectrum is `NA` and the data is #' filtered using a retention time range, an empty peaks matrix is returned #' (for `keep = TRUE`, for `keep = FALSE` the full peaks matrix is returned). #' #' @note #' -#' In contrast to other *filter* functions, this function does not provide a -#' `msLevel.` parameter to apply the filter only on spectra of the specified -#' MS levels. In contrast, to apply no, or different, filters to spectra from -#' different MS levels, multi-row range matrices can be used (see examples -#' below). +#' In contrast to some other *filter* functions, this function does not provide +#' a `msLevel` parameter that allows to define the MS level of spectra on which +#' the filter should be applied. The filter(s) will always be applied to +#' **all** spectra (irrespectively of their MS level). Through combination of +#' multiple filter ranges it is however possible to apply MS level-dependent +#' filters (see examples below for details). +#' +#' The filter will not be applied immediately to the data but only executed when +#' the mass peak data is accessed (through `peaksData()`, `mz()` or +#' `intensity()`) or by calling `applyProcessing()`. #' #' @param object A [Spectra] object. #' diff --git a/R/Spectra.R b/R/Spectra.R index 24b5f8ae..a20a44ba 100644 --- a/R/Spectra.R +++ b/R/Spectra.R @@ -334,10 +334,10 @@ NULL #' @section Filter spectra data: #' #' Filter a `Spectra` object based on the spectra data. This includes subset -#' operations that reduce the number of spectra in the object as well as filters -#' that reduce the *content* of the `Spectra` object. See section -#' *Filter peaks data* below for functions that filter the peaks data of a -#' `Spectra`. +#' operations that immediately reduce the number of spectra in the object as +#' well as filters that reduce the *content* of the `Spectra` object. +#' See section *Filter peaks data* below for functions that filter the peaks +#' data of a `Spectra`. #' #' - `[`: subsets the spectra keeping only selected elements (`i`). The method #' **always** returns a `Spectra` object. @@ -456,7 +456,10 @@ NULL #' @section Filter or aggregate mass peak data: #' #' Operations that filter or aggregate the mass peak data from each spectrum -#' without changing the number of spectra in a `Spectra` object. +#' without changing the number of spectra in a `Spectra` object. Also, the +#' actual subsetting/aggregation operation is only executed once peaks data is +#' accessed (through `peaksData()`, `mz()` or `intensity()`) or +#' `applyProcessing()` is called. #' #' - `combinePeaks()`: combines mass peaks **within each spectrum** with a #' difference in their m/z values that is smaller than the maximal @@ -1115,7 +1118,7 @@ NULL #' #' @param ... Additional arguments. #' -#' @author Sebastian Gibb, Johannes Rainer, Laurent Gatto +#' @author Sebastian Gibb, Johannes Rainer, Laurent Gatto, Philippine Louail #' #' @md #' diff --git a/man/MsBackend.Rd b/man/MsBackend.Rd index 2e9292e9..19bd8b7c 100644 --- a/man/MsBackend.Rd +++ b/man/MsBackend.Rd @@ -1090,5 +1090,5 @@ be$peak_ann <- NULL peaksVariables(be) } \author{ -Johannes Rainer, Sebastian Gibb, Laurent Gatto +Johannes Rainer, Sebastian Gibb, Laurent Gatto, Philippine Louail } diff --git a/man/Spectra.Rd b/man/Spectra.Rd index 53c36e5a..b4f87b54 100644 --- a/man/Spectra.Rd +++ b/man/Spectra.Rd @@ -1142,10 +1142,10 @@ function is supposed to be more efficient than \code{unique(msLevel(object))}. Filter a \code{Spectra} object based on the spectra data. This includes subset -operations that reduce the number of spectra in the object as well as filters -that reduce the \emph{content} of the \code{Spectra} object. See section -\emph{Filter peaks data} below for functions that filter the peaks data of a -\code{Spectra}. +operations that immediately reduce the number of spectra in the object as +well as filters that reduce the \emph{content} of the \code{Spectra} object. +See section \emph{Filter peaks data} below for functions that filter the peaks +data of a \code{Spectra}. \itemize{ \item \code{[}: subsets the spectra keeping only selected elements (\code{i}). The method \strong{always} returns a \code{Spectra} object. @@ -1248,7 +1248,10 @@ Returns the filtered \code{Spectra}. Operations that filter or aggregate the mass peak data from each spectrum -without changing the number of spectra in a \code{Spectra} object. +without changing the number of spectra in a \code{Spectra} object. Also, the +actual subsetting/aggregation operation is only executed once peaks data is +accessed (through \code{peaksData()}, \code{mz()} or \code{intensity()}) or +\code{applyProcessing()} is called. \itemize{ \item \code{combinePeaks()}: combines mass peaks \strong{within each spectrum} with a difference in their m/z values that is smaller than the maximal @@ -1996,5 +1999,5 @@ Nir Shahaf Johannes Rainer -Sebastian Gibb, Johannes Rainer, Laurent Gatto +Sebastian Gibb, Johannes Rainer, Laurent Gatto, Philippine Louail } diff --git a/man/filterPeaksRanges.Rd b/man/filterPeaksRanges.Rd index 2cfa140d..db713c3b 100644 --- a/man/filterPeaksRanges.Rd +++ b/man/filterPeaksRanges.Rd @@ -26,11 +26,11 @@ using the \code{...} as \verb{ = } pairs. \verb{} can be a \code{numeric} of length 2 defining the lower and upper boundary, or a \code{numeric} two-column matrix (multi-row matrices are also supported, see further -below). \code{filterPeaksRanges(s, mz = c(200, 300))} woudl for example reduce +below). \code{filterPeaksRanges(s, mz = c(200, 300))} would for example reduce the peaks matrices of the \code{Spectra} object \code{s} to mass peaks with an m/z value between 200 and 300. \code{filterPeaksRanges()} returns the original \code{Spectra} object with the filter operation added to the processing queue. -Thus, the filter gets only applied when the peaks data gets extracted +Thus, the filter gets \strong{only} applied when the peaks data gets extracted with \code{mz()}, \code{intensity()} or \code{peaksData()}. If ranges for both spectra \strong{and} peaks variables are defined, the function evaluates first whether the spectra variable value for a spectrum is within the provided range and, @@ -53,18 +53,23 @@ of a row. The number of rows of the provided ranges (being it for spectra or peaks variables) have to match. \strong{Missing value handling}: any comparison which involves a missing value -(beingvit a spectra variable value, a peaks variable value or a value -in one of thevprovided ranges) is treated as a logical \code{FALSE}. For +(being it a spectra variable value, a peaks variable value or a value +in one of the provided ranges) is treated as a logical \code{FALSE}. For example, if the retention time of a spectrum is \code{NA} and the data is filtered using a retention time range, an empty peaks matrix is returned (for \code{keep = TRUE}, for \code{keep = FALSE} the full peaks matrix is returned). } \note{ -In contrast to other \emph{filter} functions, this function does not provide a -\code{msLevel.} parameter to apply the filter only on spectra of the specified -MS levels. In contrast, to apply no, or different, filters to spectra from -different MS levels, multi-row range matrices can be used (see examples -below). +In contrast to some other \emph{filter} functions, this function does not provide +a \code{msLevel} parameter that allows to define the MS level of spectra on which +the filter should be applied. The filter(s) will always be applied to +\strong{all} spectra (irrespectively of their MS level). Through combination of +multiple filter ranges it is however possible to apply MS level-dependent +filters (see examples below for details). + +The filter will not be applied immediately to the data but only executed when +the mass peak data is accessed (through \code{peaksData()}, \code{mz()} or +\code{intensity()}) or by calling \code{applyProcessing()}. } \examples{