docs: expand documentation on combineSpectra

- Expand the documentation for `combineSpectra()` and `combinePeaks()` (issue
  #320).

.github/workflows/check-bioc.yml

@@ -52,9 +52,9 @@ jobs:
       fail-fast: false
       matrix:
         config:
-          - { os: ubuntu-latest, r: 'devel', bioc: '3.19', cont: "bioconductor/bioconductor_docker:devel", rspm: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest" }
-          - { os: macOS-latest, r: 'next', bioc: '3.19'}
-          - { os: windows-latest, r: 'next', bioc: '3.19'}
+          - { os: ubuntu-latest, r: '4.4', bioc: '3.20', cont: "bioconductor/bioconductor_docker:devel", rspm: "https://packagemanager.rstudio.com/cran/__linux__/focal/latest" }
+          - { os: macOS-latest, r: '4.4', bioc: '3.20'}
+          - { os: windows-latest, r: '4.4', bioc: '3.20'}
     env:
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       RSPM: ${{ matrix.config.rspm }}

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Spectra
 Title: Spectra Infrastructure for Mass Spectrometry Data
-Version: 1.15.0
+Version: 1.15.1
 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

NEWS.md

@@ -1,3 +1,10 @@
+# Spectra 1.15
+
+## Changes in 1.15.1
+
+- Improve documentation for `combineSpectra()` and `combinePeaks()` [issue
+  #320](https://github.com/rformassspectrometry/Spectra/issues/320).
+
 # Spectra 1.13
 
 ## Changes in 1.13.8

R/Spectra.R

@@ -594,7 +594,7 @@ NULL
 #'   access and it is possible to *revert* the operation with the `reset()`
 #'   function (see description of `reset()` above).
 #'
-#' - `combinePeaks()`: combines mass peaks within each spectrum with a
+#' - `combinePeaks()`: combines mass peaks **within each spectrum** with a
 #'   difference in their m/z values that is smaller than the maximal
 #'   acceptable difference defined by `ppm` and `tolerance`. Parameters
 #'   `intensityFun` and `mzFun` allow to define functions to aggregate the
@@ -612,13 +612,15 @@ NULL
 #'   `reduceSpectra()` for a function to select a single *representative*
 #'   mass peak for each peak group.
 #'
-#' - `combineSpectra()`: combines 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 with `FUN`, which defaults to [combinePeaksData()]. Please
-#'   refer to the [combinePeaksData()] help page for details and options of
-#'   the actual combination of peaks across the sets of spectra and to the
-#'   package vignette for examples and alternative ways to aggregate spectra.
+#' - `combineSpectra()`: combines MS data from **sets of spectra into a
+#'   single spectrum per set** (in contrast to `combinePeaks()` or
+#'   `reduceSpectra()` that combine mass peaks **within each spectrum**).
+#'   For each spectrum group (set), spectra variables from the first spectrum
+#'   are used and the peak matrices are combined using the function specified
+#'   with `FUN`, which defaults to [combinePeaksData()]. Please refer to the
+#'   [combinePeaksData()] help page for details and options of the actual
+#'   combination of peaks across the sets of spectra and to the package
+#'   vignette for examples and alternative ways to aggregate spectra.
 #'   The sets of spectra can be specified with parameter `f`.
 #'   In addition it is possible to define, with parameter `p` if and how to
 #'   split the input data for parallel processing.

vignettes/Spectra.Rmd

@@ -412,11 +412,14 @@ affecting the total number of spectra are (in alphabetic order):
   to specify whether all conditions (`match = "all"`; the default) or if
   any of the conditions must match (`match = "any"`; all spectra for which
   values are within any of the provided ranges are retained).
+- `combineSpectra()`: allows to combine the MS data from sets of spectra into a
+  single spectrum per set. Thus, instead of filtering the data, this function
+  aggregates it.
 
 Filter functions that return the same number of spectra, but affect/subset the
 peaks data (m/z and intensity values) within each spectrum are:
 
-- `combinePeaks()`: groups peaks within each spectrum based on similarity of
+- `combinePeaks()`: groups peaks **within each spectrum** based on similarity of
   their m/z values and combines these into a single peak per peak group.
 - `deisotopeSpectra()`: deisotopes each individual spectrum keeping only the
   monoisotopic peak for peaks groups of potential isotopologues.
@@ -871,18 +874,26 @@ See also `?plotSpectra` for more plotting options and examples.
 
 The `Spectra` package provides the `combineSpectra()` function that allows to
 *aggregate* multiple spectra into a single one. The main parameters of this
-function are `f`, which defines the grouping of the spectra, and `FUN` which
-allows to define the function that performs the actual aggregation. The default
-aggregation function is `combinePeaksData()` (see `?combinePeaksData` for
-details) that combines multiple spectra into a single spectrum with all peaks
-from all input spectra (with additional paramter `peaks = "union"`), or peaks
-that are present in a certain proportion of input spectra (with parameter
-`peaks = "intersect"`; parameter `minProp` allows to define the minimum
-required proportion of spectra in which a peak needs to be present. Below we
-use this function to combine the spectra for 1-methylhistidine and caffeine
-into a single spectrum for each compound. We use the spectra variable `$name`,
-that contains the names of the compounds, to define which spectra should be
-grouped together.
+function are `f`, which defines the sets of spectra that should be combined, and
+`FUN`, which allows to define the function that performs the actual
+aggregation. The default aggregation function is `combinePeaksData()` (see
+`?combinePeaksData` for details) that combines multiple spectra into a single
+spectrum with all peaks from all input spectra (with additional paramter `peaks
+= "union"`), or peaks that are present in a certain proportion of input spectra
+(with parameter `peaks = "intersect"`; parameter `minProp` allows to define the
+minimum required proportion of spectra in which a peak needs to be present. It
+is important to mention that, by default, the function combines all mass peaks
+from all spectra with a similar m/z value into a single, representative mass
+peak aggregating all their intensities into one. To avoid the resulting
+intensity to be affected by potential noise peaks it might be advised to first
+*clean* the individual mass spectra using e.g. the `combinePeaks()` or
+`reduceSpectra()` functions that first aggregate mass peaks **within** each
+individual spectrum.
+
+In this example we below we use `combineSpectra()` to combine the spectra for
+1-methylhistidine and caffeine into a single spectrum for each compound. We use
+the spectra variable `$name`, that contains the names of the compounds, to
+define which spectra should be grouped together.
 
 ```{r}
 sps_agg <- combineSpectra(sps, f = sps$name)