diff --git a/DESCRIPTION b/DESCRIPTION index f889cc5ce..4decf6143 100644 --- a/DESCRIPTION +++ b/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, diff --git a/NAMESPACE b/NAMESPACE index 1592c843d..3b1223884 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -580,6 +580,7 @@ importFrom("MsExperiment", "sampleData<-") importFrom("MsExperiment", "sampleData") importFrom("MsExperiment", "readMsExperiment") importMethodsFrom("MsExperiment", "spectra<-") +export("plotPrecursorIons") importFrom("progress", "progress_bar") diff --git a/NEWS.md b/NEWS.md index 47eefec67..401ef7e81 100644 --- a/NEWS.md +++ b/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()` diff --git a/R/XcmsExperiment-plotting.R b/R/XcmsExperiment-plotting.R index eccea24dc..b0b72ea36 100644 --- a/R/XcmsExperiment-plotting.R +++ b/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() + } } diff --git a/R/XcmsExperiment.R b/R/XcmsExperiment.R index 1c86f0496..17f4b8343 100644 --- a/R/XcmsExperiment.R +++ b/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. #' diff --git a/man/XcmsExperiment.Rd b/man/XcmsExperiment.Rd index de7e1c35b..f76763652 100644 --- a/man/XcmsExperiment.Rd +++ b/man/XcmsExperiment.Rd @@ -580,6 +580,8 @@ peaks per file along the retention time. See \code{\link[=plotChromPeakImage]{pl details. \item \code{plotChromPeaks}: indicate identified chromatographic peaks from one sample in the RT-m/z space. See \code{\link[=plotChromPeaks]{plotChromPeaks()}} for details. +\item \code{plotPrecursorIons}: general visualization of precursor ions of +LC-MS/MS data. See \code{\link[=plotPrecursorIons]{plotPrecursorIons()}} for details. \item \code{refineChromPeaks}: \emph{refines} identified chromatographic peaks in \code{object}. See \code{\link[=refineChromPeaks]{refineChromPeaks()}} for details. } diff --git a/man/plotPrecursorIons.Rd b/man/plotPrecursorIons.Rd new file mode 100644 index 000000000..ef98eeb45 --- /dev/null +++ b/man/plotPrecursorIons.Rd @@ -0,0 +1,55 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/XcmsExperiment-plotting.R +\name{plotPrecursorIons} +\alias{plotPrecursorIons} +\title{General visualization of precursor ions of LC-MS/MS data} +\usage{ +plotPrecursorIons( + x, + pch = 21, + col = "#00000080", + bg = "#00000020", + xlab = "retention time", + ylab = "m/z", + main = character(), + ... +) +} +\arguments{ +\item{x}{\code{MsExperiment} of LC-MS/MS data.} + +\item{pch}{\code{integer(1)} defining the symbol/point type to be used to draw +points. See \code{\link[=points]{points()}} for details. Defaults to \code{pch = 21} which allows +defining the background and border color for points.} + +\item{col}{the color to be used for all data points. Defines the border +color if \code{pch = 21}.} + +\item{bg}{the background color (if \code{pch = 21}).} + +\item{xlab}{\code{character(1)} defining the x-axis label.} + +\item{ylab}{\code{character(1)} defining the y-axis label.} + +\item{main}{Optional \code{character(1)} with the title for \strong{every} plot. If +not provided (the default) the base file name will be used for each +sample.} + +\item{...}{additional parameters to be passed to the \code{plot} calls.} +} +\description{ +Simple visualization of the position of fragment spectra's precursor ion +in the MS1 retention time by m/z area. +} +\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) +} +\author{ +Johannes Rainer +} diff --git a/tests/testthat/test_XcmsExperiment-plotting.R b/tests/testthat/test_XcmsExperiment-plotting.R index b28679f81..ea4670303 100644 --- a/tests/testthat/test_XcmsExperiment-plotting.R +++ b/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) +})