Add new plotPrecursorIons function and address issue #742

.github/workflows/check-bioc.yml

@@ -54,8 +54,8 @@ jobs:
       matrix:
         config:
           - { os: ubuntu-latest, r: 'devel', bioc: 'devel', 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: macOS-latest, r: '4.4', bioc: 'devel'}
+          - { os: windows-latest, r: '4.4', bioc: 'devel'}
     env:
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       RSPM: ${{ matrix.config.rspm }}
@@ -141,15 +141,15 @@ jobs:
           ## required for ncdf4
           ## brew install netcdf ## Does not work as it is compiled with gcc
           ## Use pre-compiled libraries from https://mac.r-project.org/libs-4/
-          curl -O https://mac.r-project.org/libs-4/netcdf-4.7.4-darwin.17-x86_64.tar.gz
-          tar fvxzm netcdf-4.7.4-darwin.17-x86_64.tar.gz -C /
-          rm netcdf-4.7.4-darwin.17-x86_64.tar.gz
-          curl -O https://mac.r-project.org/libs-4/hdf5-1.12.0-darwin.17-x86_64.tar.gz
-          tar fvxzm hdf5-1.12.0-darwin.17-x86_64.tar.gz -C /
-          rm hdf5-1.12.0-darwin.17-x86_64.tar.gz
-          curl -O https://mac.r-project.org/libs-4/szip-2.1.1-darwin.17-x86_64.tar.gz
-          tar fvxzm szip-2.1.1-darwin.17-x86_64.tar.gz -C /
-          rm szip-2.1.1-darwin.17-x86_64.tar.gz
+          # curl -O https://mac.r-project.org/libs-4/netcdf-4.7.4-darwin.17-x86_64.tar.gz
+          # tar fvxzm netcdf-4.7.4-darwin.17-x86_64.tar.gz -C /
+          # rm netcdf-4.7.4-darwin.17-x86_64.tar.gz
+          # curl -O https://mac.r-project.org/libs-4/hdf5-1.12.0-darwin.17-x86_64.tar.gz
+          # tar fvxzm hdf5-1.12.0-darwin.17-x86_64.tar.gz -C /
+          # rm hdf5-1.12.0-darwin.17-x86_64.tar.gz
+          # curl -O https://mac.r-project.org/libs-4/szip-2.1.1-darwin.17-x86_64.tar.gz
+          # tar fvxzm szip-2.1.1-darwin.17-x86_64.tar.gz -C /
+          # rm szip-2.1.1-darwin.17-x86_64.tar.gz
 
       - name: Install Windows system dependencies
         if: runner.os == 'Windows'

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: xcms
-Version: 4.3.0
+Version: 4.3.1
 Title: LC-MS and GC-MS Data Analysis
 Description: Framework for processing and visualization of chromatographically
     separated and single-spectra mass spectral data. Imports from AIA/ANDI NetCDF,

NAMESPACE

@@ -580,6 +580,7 @@ importFrom("MsExperiment", "sampleData<-")
 importFrom("MsExperiment", "sampleData")
 importFrom("MsExperiment", "readMsExperiment")
 importMethodsFrom("MsExperiment", "spectra<-")
+export("plotPrecursorIons")
 
 importFrom("progress", "progress_bar")
 

NEWS.md

@@ -1,10 +1,20 @@
+# xcms 4.3
+
+## Changes in version 4.3.1
+
+- Support excluding samples or sample groups from defining features with
+  *PeakDensity* correspondence analysis (issue #742).
+- Add `plotPrecursorIons()` function.
+- Fix in `dropFeatureDefinitions()` that was not correctly removing additional
+  metadata from gap-filled chromatographic peaks.
+
+
 # xcms 4.1
 
 ## Changes in version 4.1.14
 
 - Fix for issue #734. XIC plot is is now working with MS2 Data.
 
-
 ## Changes in version 4.1.13
 
 - Add parameter `rtimeDifferenceThreshold` to `ObiwarpParam` allowing to

R/AllGenerics.R

@@ -1319,7 +1319,15 @@ setGeneric("group", function(object, ...) standardGeneric("group"))
 #'   representing the m/z dependent measurement error of some MS instruments).
 #'   All peaks (from the same or from different samples) with their apex
 #'   position being close on the retention time axis are grouped into a LC-MS
-#'   feature. See in addition [do_groupChromPeaks_density()] for the core API
+#'   feature. Only samples with non-missing sample group assignment (i.e. for
+#'   which the value provided with parameter `sampleGroups` is different than
+#'   `NA`) are considered and counted for the feature definition. This allows
+#'   to exclude certain samples or groups (e.g. blanks) from the feature
+#'   definition avoiding thus features with only detected peaks in these. Note
+#'   that this affects only the **definition** of **new** features.
+#'   Chromatographic peaks in these samples will still be assigned to features
+#'   which were defined based on the other samples.
+#'   See in addition [do_groupChromPeaks_density()] for the core API
 #'   function.
 #'
 #' - `NearestPeaksParam`: performs peak grouping based on the proximity of
@@ -1399,11 +1407,13 @@ setGeneric("group", function(object, ...) standardGeneric("group"))
 #'
 #' @param sampleGroups For `PeakDensityParam`: A vector of the same length than
 #'     samples defining the sample group assignments (i.e. which samples
-#'     belong to which sample
-#'     group). This parameter is mandatory for the `PeakDensityParam`
-#'     and has to be provided also if there is no sample grouping in the
-#'     experiment (in which case all samples should be assigned to the
-#'     same group).
+#'     belong to which sample group). This parameter is mandatory for
+#'     `PeakDensityParam` and has to be defined also if there is no sample
+#'     grouping in the experiment (in which case all samples should be
+#'     assigned to the same group). Samples for which a `NA` is provided will
+#'     not be considered in the feature definitions step. Providing `NA` for
+#'     all blanks in an experiment will for example avoid features to be
+#'     defined for signals (chrom peaks) present only in blank samples.
 #'
 #' @param value Replacement value for `<-` methods.
 #'

R/XcmsExperiment-plotting.R

@@ -406,3 +406,73 @@ setMethod(
         }
     }
 }
+
+#' @title General visualization of precursor ions of LC-MS/MS data
+#'
+#' @description
+#'
+#' Simple visualization of the position of fragment spectra's precursor ion
+#' in the MS1 retention time by m/z area.
+#'
+#' @param x `MsExperiment` of LC-MS/MS data.
+#'
+#' @param pch `integer(1)` defining the symbol/point type to be used to draw
+#'     points. See [points()] for details. Defaults to `pch = 21` which allows
+#'     defining the background and border color for points.
+#'
+#' @param col the color to be used for all data points. Defines the border
+#'     color if `pch = 21`.
+#'
+#' @param bg the background color (if `pch = 21`).
+#'
+#' @param xlab `character(1)` defining the x-axis label.
+#'
+#' @param ylab `character(1)` defining the y-axis label.
+#'
+#' @param main Optional `character(1)` with the title for **every** plot. If
+#'     not provided (the default) the base file name will be used for each
+#'     sample.
+#'
+#' @param ... additional parameters to be passed to the `plot` calls.
+#'
+#' @importFrom grDevices n2mfrow
+#'
+#' @export
+#'
+#' @author Johannes Rainer
+#'
+#' @md
+#'
+#' @examples
+#'
+#' ## Load a test data file with DDA LC-MS/MS data
+#' library(MsExperiment)
+#' fl <- system.file("TripleTOF-SWATH", "PestMix1_DDA.mzML", package = "msdata")
+#' pest_dda <- readMsExperiment(fl)
+#'
+#' plotPrecursorIons(pest_dda)
+#' grid()
+#'
+#' ## Subset the data object to plot the data specifically for one or
+#' ## selected file/sample:
+#' plotPrecursorIons(pest_dda[1L])
+plotPrecursorIons <- function(x, pch = 21, col = "#00000080",
+                              bg = "#00000020", xlab = "retention time",
+                              ylab = "m/z", main = character(), ...) {
+    if (!inherits(x, "MsExperiment"))
+        stop("'x' should be a 'MsExperiment' object or an object of a ",
+             "class extending it.")
+    par(mfrow = n2mfrow(length(x)))
+    for (i in seq_along(x)) {
+        x_sub <- x[i]
+        rtr <- range(rtime(spectra(x_sub)))
+        mzr <- range(range(mz(filterEmptySpectra(spectra(x_sub)))))
+        pmz <- precursorMz(spectra(x_sub))
+        prt <- rtime(spectra(x_sub)[!is.na(pmz)])
+        pmz <- pmz[!is.na(pmz)]
+        if (!length(main))
+            main <- basename(dataOrigin(spectra(x_sub)[1L]))
+        plot(prt, pmz, xlim = rtr, ylim = mzr, pch = pch, col = col, bg = bg,
+             xlab = xlab, ylab = ylab, main = main[1L], ...)
+    }
+}

R/XcmsExperiment.R

@@ -206,6 +206,9 @@
 #' - `plotChromPeaks`: indicate identified chromatographic peaks from one
 #'   sample in the RT-m/z space. See [plotChromPeaks()] for details.
 #'
+#' - `plotPrecursorIons`: general visualization of precursor ions of
+#'   LC-MS/MS data. See [plotPrecursorIons()] for details.
+#'
 #' - `refineChromPeaks`: *refines* identified chromatographic peaks in `object`.
 #'   See [refineChromPeaks()] for details.
 #'
@@ -1553,9 +1556,8 @@ setMethod(
             object@processHistory, type = .PROCSTEP.PEAK.GROUPING, num = 1L)
         object@featureDefinitions <- .empty_feature_definitions()
         if (.hasFilledPeaks(object)) {
-            object@chromPeaks <- object@chromPeaks[
-                                            !object@chromPeakData$is_filled, ,
-                                            drop = FALSE]
+            object <- .filter_chrom_peaks(
+                object, which(!.chromPeakData(object)$is_filled))
             object@processHistory <- dropProcessHistoriesList(
                 object@processHistory, type = .PROCSTEP.PEAK.FILLING)
         }

R/do_groupChromPeaks-functions.R

@@ -113,8 +113,11 @@ do_groupChromPeaks_density <- function(peaks, sampleGroups,
              paste0("'", .reqCols[!.reqCols %in% colnames(peaks)],"'",
                     collapse = ", "), " not found in 'peaks' parameter")
 
-    sampleGroups <- as.character(sampleGroups)
-    sampleGroupNames <- unique(sampleGroups)
+    ## With a `factor` we also support excluding samples/groups, i.e. samples
+    ## with an NA are not considered in the feature definition.
+    if (!is.factor(sampleGroups))
+        sampleGroups <- factor(sampleGroups)
+    sampleGroupNames <- levels(sampleGroups)
     sampleGroupTable <- table(sampleGroups)
     nSampleGroups <- length(sampleGroupTable)
 
@@ -160,15 +163,12 @@ do_groupChromPeaks_density <- function(peaks, sampleGroups,
             pb$tick()
         if (endIdx - startIdx < 0)
             next
-        resL[[i]] <- .group_peaks_density(peaks[startIdx:endIdx, , drop = FALSE],
-                                          bw = bw, densFrom = densFrom,
-                                          densTo = densTo, densN = densN,
-                                          sampleGroups = sampleGroups,
-                                          sampleGroupTable = sampleGroupTable,
-                                          minFraction = minFraction,
-                                          minSamples = minSamples,
-                                          maxFeatures = maxFeatures,
-                                          sleep = sleep)
+        resL[[i]] <- .group_peaks_density(
+            peaks[startIdx:endIdx, , drop = FALSE], bw = bw,
+            densFrom = densFrom, densTo = densTo, densN = densN,
+            sampleGroups = sampleGroups, sampleGroupTable = sampleGroupTable,
+            minFraction = minFraction, minSamples = minSamples,
+            maxFeatures = maxFeatures, sleep = sleep)
     }
     res <- do.call(rbind, resL)
     if (nrow(res)) {

R/functions-Params.R

@@ -236,9 +236,8 @@ CentWavePredIsoParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10,
 PeakDensityParam <- function(sampleGroups = numeric(), bw = 30,
                              minFraction = 0.5, minSamples = 1,
                              binSize = 0.25, ppm = 0, maxFeatures = 50) {
-    if (length(sampleGroups) == 0 | any(is.na(sampleGroups)))
-        stop("Argument 'sampleGroups' has to be defined. It should not ",
-             "contain 'NA's")
+    if (length(sampleGroups) == 0)
+        stop("Argument 'sampleGroups' has to be defined.")
     new("PeakDensityParam", sampleGroups = sampleGroups, bw = bw,
         minFraction = minFraction, minSamples = minSamples,
         binSize = binSize, ppm = ppm, maxFeatures = maxFeatures)