feat: add new plotPrecursorIons function

- Add a new function `plotPrecursorIons()` function to provide a simple
  visualization of precursor m/z and retention times in the m/z - retention time
  area of the MS1 data of a file.

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: xcms
-Version: 4.1.12
+Version: 4.1.13
 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,5 +1,9 @@
 # xcms 4.1
 
+## Changes in version 4.1.13
+
+- Add `plotPrecursorIons()` function.
+
 ## Changes in version 4.1.12
 
 - Implementation of the `LamaParama` class and method for the `adjustRtime()`

R/XcmsExperiment-plotting.R

@@ -406,27 +406,68 @@ setMethod(
     }
 }
 
-#' @title General visualization of precursor ions of a LC-MS/MS data file
+#' @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 sampleIndex `integer(1L)` defining the sample from
+#' @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
 #'
-plotPrecursorIons <- function(x, sampleIndex = 1L, pch = 21, col = "#00000080",
+#' @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)
+plotPrecursorIons <- function(x, pch = 21, col = "#00000080",
                               bg = "#00000020", xlab = "retention time",
-                              ylab = "m/z", ...) {
-    x_sub <- x[sampleIndex]
-    rtr <- range(rtime(spectra(x_sub)))
-    mzr <- range(range(mz(spectra(x_sub))))
-    pmz <- precursorMz(spectra(x_sub))
-    prt <- rtime(spectra(x_sub)[!is.na(pmz)])
-    pint <- precursorIntensity(spectra(x_sub)[!is.na(pmz)])
-    pmz <- pmz[!is.na(pmz)]
-    mn <- basename(dataOrigin(spectra(x_sub)[1L]))
-    plot(prt, pmz, xlim = rtr, ylim = mzr, pch = pch, col = col, bg = bg,
-         xlab = xlab, ylab = ylab, main = mn, ...)
-    grid()
+                              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], ...)
+        grid()
+    }
 }

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.
 #'

tests/testthat/test_XcmsExperiment-plotting.R

@@ -51,3 +51,16 @@ test_that("plot,XcmsExperiment and .xmse_plot_xic works", {
     tmp <- filterMz(filterRt(xmse, rt = c(2550, 2800)), mz = c(342.5, 344.5))
     plot(tmp)
 })
+
+test_that("plotPrecursorIons works", {
+    expect_error(plotPrecursorIons(3), "MsExperiment")
+    fl <- system.file("TripleTOF-SWATH", "PestMix1_SWATH.mzML",
+                      package = "msdata")
+    a <- readMsExperiment(fl)
+    plotPrecursorIons(a, main = "SWATH")
+
+    fl <- system.file("TripleTOF-SWATH", "PestMix1_DDA.mzML",
+                      package = "msdata")
+    a <- readMsExperiment(fl)
+    plotPrecursorIons(a)
+})