diff --git a/.github/workflows/check-bioc.yml b/.github/workflows/check-bioc.yml index 67c77639..1906c688 100644 --- a/.github/workflows/check-bioc.yml +++ b/.github/workflows/check-bioc.yml @@ -159,10 +159,11 @@ jobs: ## https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016675.html ## https://github.com/r-lib/remotes/issues/296 ## Ideally, all dependencies should get installed in the first pass. + install.packages("remotes") + BiocManager::install("RforMassSpectrometry/Chromatograms") install.packages("pak") pak::local_install_dev_deps(ask = FALSE) pak::local_install(depdendencies = TRUE) - BiocManager::install(c("rmarkdown", "BiocStyle")) continue-on-error: true shell: Rscript {0} diff --git a/DESCRIPTION b/DESCRIPTION index 47fae864..7c5747aa 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: xcms -Version: 4.11.1 +Version: 4.11.2 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, @@ -53,7 +53,7 @@ Imports: mzR (>= 2.25.3), methods, Biobase, - BiocGenerics, + BiocGenerics (>= 0.59.12), ProtGenerics (>= 1.37.1), lattice, MassSpecWavelet (>= 1.66.0), @@ -67,7 +67,8 @@ Imports: progress, RColorBrewer, MetaboCoreUtils (>= 1.11.2), - data.table + data.table, + Chromatograms (>= 1.3.3) Suggests: BiocStyle, caTools, @@ -94,7 +95,6 @@ URL: https://github.com/sneumann/xcms BugReports: https://github.com/sneumann/xcms/issues/new VignetteBuilder: knitr biocViews: ImmunoOncology, MassSpectrometry, Metabolomics -RoxygenNote: 7.3.3 Encoding: UTF-8 Roxygen: list(markdown=TRUE) Collate: @@ -164,3 +164,4 @@ Collate: 'writemztab.R' 'xcmsSource.R' 'zzz.R' +Config/roxygen2/version: 8.1.0 diff --git a/NAMESPACE b/NAMESPACE index f4523ad0..91468a62 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,8 +8,8 @@ importMethodsFrom("ProtGenerics", "peaks", "chromatogram", "writeMSData", "estimatePrecursorIntensity") importClassesFrom("ProtGenerics", "Param") importFrom("BiocGenerics", "updateObject", "fileName", "subset", - "dirname", "dirname<-") -## import("Biobase") + "dirname", "dirname<-") +importMethodsFrom("BiocGenerics", "group") importFrom("Biobase", "AnnotatedDataFrame") importClassesFrom("Biobase", "AnnotatedDataFrame") importMethodsFrom("Biobase", "phenoData", @@ -375,7 +375,6 @@ exportMethods("hasChromPeaks", "removeIntensity", "filterColumnsIntensityAbove", "filterColumnsKeepTop", - "plotChromatogramsOverlay", "transformIntensity", "filterChromPeaks", "filterFeatureDefinitions", @@ -385,7 +384,9 @@ exportMethods("hasChromPeaks", "chromPeakSpectra", "chromPeakChromatograms", "featureChromatograms", - "chromPeakSummary" + "chromPeakSummary", + "featureChromPeaks", + "featurePeakidx" ) ## feature grouping functions and methods. @@ -467,3 +468,10 @@ export("BlankFlag") ## HDF5 storage mode exportClasses("XcmsExperimentHdf5") +export("XcmsExperimentHdf5") + +## Chromatograms +importMethodsFrom("Chromatograms", "Chromatograms") +importClassesFrom("Chromatograms", "Chromatograms") +importMethodsFrom("Chromatograms", "plotChromatogramsOverlay") +exportMethods("plotChromatogramsOverlay") diff --git a/NEWS.md b/NEWS.md index ec9fac1a..07f62205 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,21 @@ # xcms 4.11 +## Changes in version 4.11.2 + +- Add support to return chromatographic data as a `Chromatograms` object with + the `chromatogram()` method from `MsExperiment`, `XcmsExperiment` and + `XcmsExperimentHdf5` objects. +- Add support for `Chromatograms` to the `chromPeakChromatograms()` method for + `XcmsExperiment` and `XcmsExperimentHdf5` objects. +- Add support for `Chromatograms` to the `featureChromatograms()` method for + `XcmsExperiment` and `XcmsExperimentHdf5` objects. +- Add new methods `featureChromPeaks()` and `featurePeakidx()` to access the + mapping between features and chromatographic peaks. +- `loadXcmsData()` updates parameter class definitions in the object's *process + history*. +- Fix `chromPeakData<-` for `XcmsExperiment` not supporting a `DataFrame` as + input (issue #839). + ## Changes in version 4.11.1 - `refineChromPeaks,MergeNeighboringPeakParam`: drop row names of intermediate diff --git a/R/AllGenerics.R b/R/AllGenerics.R index 5bd84214..0e325345 100644 --- a/R/AllGenerics.R +++ b/R/AllGenerics.R @@ -307,8 +307,19 @@ setGeneric("checkBack<-", function(object, value) standardGeneric("checkBack<-") #' @description #' #' Extract an ion chromatogram (EIC) for each chromatographic peak in an -#' [XcmsExperiment()] object. The result is returned as an [XChromatograms()] -#' of length equal to the number of chromatographic peaks (and one column). +#' [XcmsExperiment()] object. Parameters `expandRt` and `expandMz` allow to +#' increase the retention time and/or m/z boundaries of each chromatographic +#' peak. Parameter `return.type` allows to define the format in which the +#' chromatograms are returned: +#' +#' - `return.type = "Chromatograms"`: return the EICs as a +#' [Chromatograms::Chromatograms()] object. The ID of the chromatographic peak +#' can be accessed with `$chrom_peak_id` from the returned object. +#' - `return.type = "MChromatograms"`: return the EICs as a (single column) +#' legacy [MSnbase::MChromatograms] object. +#' - `return.type = "XChromatograms"`: return the EICs as a (single column) +#' legacy [XChromatograms()] object which contains also the information of +#' all chromatographic peaks. #' #' @param object An [XcmsExperiment()] with identified chromatographic peaks. #' @@ -332,10 +343,8 @@ setGeneric("checkBack<-", function(object, value) standardGeneric("checkBack<-") #' which chromatograms should be returned. #' #' @param return.type `character(1)` specifying the type of the returned object. -#' Can be either `return.type = "XChromatograms"` (the default) or -#' `return.type = "MChromatograms"` to return either a chromatographic -#' object with or without the identified chromatographic peaks, -#' respectively. +#' Can be either `return.type = "XChromatograms"` (the default), +#' `return.type = "MChromatograms"` or `return.type = "Chromatograms"`. #' #' @param ... currently ignored. #' @@ -351,11 +360,26 @@ setGeneric("checkBack<-", function(object, value) standardGeneric("checkBack<-") #' @examples #' #' ## Load a test data set with detected peaks -#' library(MSnbase) #' library(xcms) #' library(MsExperiment) #' faahko_sub <- loadXcmsData("faahko_sub2") #' +#' ## Extract EICs for all chromatographic peaks +#' library(Chromatograms) +#' chrs <- chromPeakChromatograms(faahko_sub, return.type = "Chromatograms") +#' chrs +#' +#' ## Get the chrom peak ID of all EICs +#' chrs$chrom_peak_id +#' +#' ## Plot the first 4 EICs +#' plotChromatograms(chrs[1:4]) +#' +#' ## Plot the first 4 EICs into the same plot +#' plotChromatogramsOverlay(chrs[1:4]) +#' +#' ## Use the legacy EIC infrastructure (MChromatograms, XChromatograms) +#' library(MSnbase) #' ## Get EICs for every detected chromatographic peak #' chrs <- chromPeakChromatograms(faahko_sub) #' chrs @@ -678,37 +702,64 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) #' #' @description #' -#' Extract ion chromatograms for features in an [XcmsExperiment] or -#' [XCMSnExp-class] object. The function returns for each feature the -#' extracted ion chromatograms (along with all associated chromatographic -#' peaks) in each sample. The chromatogram is extracted from the m/z - rt -#' region that includes **all** chromatographic peaks of a feature. By default, -#' this region is defined using the range of the chromatographic peaks' m/z -#' and retention times (with `mzmin = min`, `mzmax = max`, `rtmin = min` and -#' `rtmax = max`). For some features, and depending on the data, the m/z and -#' rt range can thus be relatively large. The boundaries of the m/z - rt -#' region can also be restricted by changing parameters `mzmin`, `mzmax`, -#' `rtmin` and `rtmax` to a different functions, such as `median`. -#' -#' By default only chromatographic peaks associated with a feature are -#' included in the returned [XChromatograms] object. For `object` being an -#' `XCMSnExp` object parameter `include` allows also to return all -#' chromatographic peaks with their apex position within the selected -#' region (`include = "apex_within"`) or any chromatographic peak overlapping -#' the m/z and retention time range (`include = "any"`). +#' `featureChromatograms()` extracts ion chromatograms for features in an +#' [XcmsExperiment] or [XCMSnExp-class] object. The function returns for each +#' feature the extracted ion chromatograms in each sample. Based on the setting +#' for parameter `return.type` the results are returned as a legacy +#' [MSnbase::MChromatograms] or [XChromatograms()] object +#' (`return.type = "MChromatograms"` or `return.type = "XChromatograms"`, the +#' default) or as a new [Chromatograms::Chromatograms()] object +#' (`return.type = "Chromatograms"`): +#' +#' - `return.type = "MChromatograms"`: the chromatograms are extracted from the +#' m/z - rt region that includes all chromatographic peaks for a feature. The +#' [featureArea()] function is used to define this region which is defined +#' using the range of the chromatographic peaks' m/z and retention times. The +#' `MChromatograms` organizes the EICs per feature, i.e., each row in the +#' returned `MChromatograms` corresponds to one feature with columns +#' containing EICs per sample. +#' +#' - `return.type = "XChromatograms"`: chromatographic data is defined as for +#' `return.type = "MChromatograms"`, but the returned EICs contain in addition +#' also the information on the individual chromatographic peaks as well as +#' the feature definitions. For `object` being an `XCMSnExp` object, +#' parameter `include` allows also to return all chromatographic peaks with +#' their apex position within the selected region (`include = "apex_within"`) +#' or any chromatographic peak overlapping the m/z and retention time range +#' (`include = "any"`). +#' +#' - `return.type = "Chromatograms"`: the EICs, defined through [featureArea()] +#' as described above, are returned as a [Chromatograms()] object which +#' organizes chromatograms sequentially in a list-like structure: first all +#' chromatograms for the first feature in all samples, then those from the +#' second feature and so on. See examples for details. +#' The feature ID is stored in the result object's `$feature_id` variable. +#' By default, the returned EICs represent the chromatograms of the +#' `featureArea()`, but with `featureArea = FALSE` each returned chromatogram +#' represents the EIC for the actual area of the individual chromatographic +#' peaks assigned to the feature (same as with [chromPeakChromatograms()]). +#' The IDs of the chromatographic peaks can then be accessed through +#' `$chrom_peak_id`. #' #' @note #' -#' The EIC data of a feature is extracted from every sample using the same -#' m/z - rt area. The EIC in a sample does thus not exactly represent the -#' signal of the actually identified chromatographic peak in that sample. -#' The [chromPeakChromatograms()] function would allow to extract the actual -#' EIC of the chromatographic peak in a specific sample. See also examples -#' below. +#' Some of the functionality available for `XChromatograms` objects is not +#' yet available for `Chromatograms`. Thus, while the newer +#' `Chromatograms`-based infrastructure is more efficient and powerful, for +#' some operations it is suggested to still use the legacy objects (such as +#' simulating a correspondence analysis through [plotChromPeakDensity()]). +#' +#' By default the EIC data of a feature is extracted from every sample using +#' the same m/z - rt area. Unless `featureArea = FALSE` is used, the EIC in a +#' sample does thus not exactly represent the signal of the actually identified +#' chromatographic peak in that sample. #' #' Parameters `include`, `filled`, `n` and `value` are only supported #' for `object` being an `XCMSnExp`. #' +#' Parameter `featureArea` is only supported for +#' `return.type = "Chromatograms"`. +#' #' When extracting EICs from only the top `n` samples it can happen that one #' or more of the features specified with `features` are dropped because they #' have no detected peak in the *top n* samples. The chance for this to happen @@ -737,6 +788,10 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) #' @param expandRt `numeric(1)` to expand the retention time range for each #' chromatographic peak by a constant value on each side. #' +#' @param featureArea For `object` being a `XcmsExperiment` and +#' `return.type = FALSE`: return EICs representing data within the +#' identified chromatographic peaks. +#' #' @param features `integer`, `character` or `logical` defining a subset of #' features for which chromatograms should be returned. Can be the index #' of the features in `featureDefinitions`, feature IDs (row names of @@ -772,9 +827,9 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) #' @param progressbar `logical(1)` defining whether a progress bar is shown. #' #' @param return.type `character(1)` defining how the result should be -#' returned. At present only `return.type = "XChromatograms"` is -#' supported and the results are thus returned as an [XChromatograms()] -#' object. +#' returned. Supported are `return.type = "XChromatograms"` (the default), +#' `return.type = "MChromatograms"` and `return.type = "Chromatograms"`. +#' See function descriptions for details. #' #' @param rtmax `function` defining how the upper boundary of the rt region #' from which the EIC is integrated should be defined. Defaults to @@ -794,8 +849,11 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) #' @param ... optional arguments to be passed along to the [chromatogram()] #' function. #' -#' @return [XChromatograms()] object. In future, depending on parameter -#' `return.type`, the data might be returned as a different object. +#' @return +#' +#' Depending on parameter `return.type`, a [MSnbase::MChromatograms], +#' [XChromatograms] or [Chromatograms::Chromatograms()] object. See function +#' description above for details. #' #' @name featureChromatograms #' @@ -825,10 +883,51 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) #' ## Get the feature definitions #' featureDefinitions(xdata) #' +#' ############################################################################# +#' ## Extracting the feature's EICs as an `Chromatograms` object +#' +#' ## Define the IDs for selected features from which to extract the data +#' fids <- rownames(featureDefinitions(xdata))[1:3] +#' chrs <- featureChromatograms(xdata, features = fids, +#' return.type = "Chromatograms") +#' chrs +#' +#' ## The data is organized by feature and sample: first all EICs for the first +#' ## feature in all samples, then those from the second etc +#' chrs$feature_id +#' +#' ## The sample information is stored in the object's `$dataOrigin` +#' basename(chrs$dataOrigin) +#' +#' ## Plot the data for the first feature +#' library(Chromatograms) +#' +#' ## Separately +#' plotChromatograms(chrs[chrs$feature_id == fids[1]]) +#' +#' ## In a single plot +#' plotChromatogramsOverlay(chrs[chrs$feature_id == fids[1]]) +#' +#' ## Extract the EICs for the individual chromatographic peaks associated to +#' ## each feature: +#' chrs <- featureChromatograms(xdata, features = fids, +#' return.type = "Chromatograms", featureArea = FALSE) +#' chrs +#' +#' ## In contrast to `featureArea = TRUE`, where one (and only one) EIC per +#' ## sample is guaranteed, for `featureArea = FALSE` there can be more than +#' ## one chromatogram per sample (or no chromatogram per sample), representing +#' ## exactly the association between identified chromatographic peaks and +#' ## features +#' chrs$feature_id +#' chrs$chrom_peak_id +#' +#' ############################################################################# +#' ## Using the legacy `MChromatogtrams`/`XChromatograms` +#' #' ## Extract ion chromatograms for the first 3 features. Parameter #' ## `features` can be either the feature IDs or feature indices. -#' chrs <- featureChromatograms(xdata, -#' features = rownames(featureDefinitions)[1:3]) +#' chrs <- featureChromatograms(xdata, features = fids) #' #' ## Plot the EIC for the first feature using different colors for each file. #' plot(chrs[1, ], col = c("red", "green", "blue")) @@ -855,10 +954,76 @@ setGeneric("featureArea", function(object, ...) standardGeneric("featureArea")) setGeneric("featureChromatograms", function(object, ...) standardGeneric("featureChromatograms")) +#' @title Feature to chromatographic peak mapping +#' +#' @description +#' +#' During the correspondence step in the preprocessing, chromatographic peaks +#' get assigned (grouped) to features. The abundances of these resulting LC-MS +#' features are supposed to represent signal from the same ion across all +#' analyzed samples. Depending on the correspondence analysis method used, +#' multiple chromatographic peaks (also eventually from the **same** sample) are +#' assigned to a feature. This mapping between features and chromatographic +#' peaks is (for [XcmsExperiment] and [XCMSnExp] object) stored in the +#' `"peakidx"` column of the [featureDefinitions()] data frame. Alternatively, +#' the mapping can be extracted from an *xcms* result object using the +#' functions: +#' +#' - `featureChromPeaks()`: returns a two-column `data.frame` with the IDs of +#' the features and the IDs of the associated chromatographic peaks. Each +#' row in this `data.frame` represents the mapping of one chromatographic +#' peak with one feature. The order of the features in the `data.frame` +#' matches the order of the features in [featureDefinitions()]. +#' +#' - `featurePeakidx()`: returns a named `list` of `integer` indices of the +#' rows in the [chromPeaks()] matrix that are assigned to a feature. The names +#' of the `list` are the feature IDs. +#' The length and order of the `list` matches the number of rows and order of +#' features in [featureDefinitions()]. +#' +#' @param object An *xcms* result object with correspondence analysis results +#' being present. +#' +#' @param msLevel Optional `integer` to restrict to features from a certain MS +#' level. +#' +#' @param ... Optional parameters. Currently ignored. +#' +#' @return See description above. +#' +#' @export +#' +#' @examples +#' +#' ## Load preprocessing results +#' library(MsExperiment) +#' xmse <- loadXcmsData() +#' +#' ## Get the mapping between features and chromatographic peaks +#' map <- featureChromPeaks(xmse) +#' +#' head(map) +#' +#' ## Column `"feature_id"` contains the IDs for the features defined in +#' ## `featureDefinitions()` +#' featureDefinitions(xmse) |> head() +#' +#' ## Column `"chrom_peak_id"` contains the IDs of the chromatographic peaks +#' chromPeaks(xmse) |> head() +#' +#' ## Alternatively, get the mapping as a `list` of `integer` indices +#' featurePeakidx(xmse) |> head() +setGeneric("featureChromPeaks", function(object, ...) + standardGeneric("featureChromPeaks")) + setGeneric("featureDefinitions", function(object, ...) standardGeneric("featureDefinitions")) setGeneric("featureDefinitions<-", function(object, value) standardGeneric("featureDefinitions<-")) +#' @rdname featureChromPeaks +setGeneric("featurePeakidx", function(object, ...) + standardGeneric("featurePeakidx")) + #' @title Extract spectra associated with features #' @@ -1428,7 +1593,6 @@ setGeneric("getXcmsRaw", function(object, ...) standardGeneric("getXcmsRaw")) setGeneric("group.density", function(object, ...) standardGeneric("group.density")) setGeneric("group.mzClust", function(object, ...) standardGeneric("group.mzClust")) setGeneric("group.nearest", function(object, ...) standardGeneric("group.nearest")) -setGeneric("group", function(object, ...) standardGeneric("group")) #' @aliases groupChromPeaks @@ -1800,8 +1964,6 @@ setGeneric("peakwidth<-", function(object, value) standardGeneric("peakwidth<-") setGeneric("plotChrom", function(object, ...) standardGeneric("plotChrom")) setGeneric("plotChromPeakDensity", function(object, ...) standardGeneric("plotChromPeakDensity")) -setGeneric("plotChromatogramsOverlay", function(object, ...) - standardGeneric("plotChromatogramsOverlay")) setGeneric("plotEIC", function(object, ...) standardGeneric("plotEIC")) setGeneric("plotPeaks", function(object, ...) standardGeneric("plotPeaks")) setGeneric("plotRaw", function(object, ...) standardGeneric("plotRaw")) diff --git a/R/MsExperiment-functions.R b/R/MsExperiment-functions.R index c636f28a..0e354db8 100644 --- a/R/MsExperiment-functions.R +++ b/R/MsExperiment-functions.R @@ -422,9 +422,14 @@ } #' This function extracts a chromatogram for the provided rt, m/z ranges, MS -#' level and isolationWindow from the `MsExperiment`. Parameter -#' `isolationWindow` ensures that, for MS2 spectra, not simply all MS2 spectra -#' are used for the chromatogram, but only those with matching +#' level and isolationWindow from the `MsExperiment` and returns it as a +#' `MSnbase::MChromatograms` object. +#' +#' **this if for backward compatibility! use `.mse_chromatograms_for_ranges()` +#' instead**. +#' +#' Parameter `isolationWindow` ensures that, for MS2 spectra, not simply all +#' MS2 spectra are used for the chromatogram, but only those with matching #' `isolationWindowTargetMz` (and hence the same set of ions). Chromatograms #' for MS1 will not need `isolationWindow`. #' @@ -449,12 +454,12 @@ #' data will be extracted! #' #' @noRd -.mse_chromatogram <- function(x, rt = matrix(nrow = 0, ncol = 2), - mz = matrix(nrow = 0, ncol = 2), - aggregationFun = "sum", msLevel = 1L, - isolationWindow = NULL, - chunkSize = 2L, progressbar = TRUE, - BPPARAM = bpparam()) { +.mse_mchromatograms_for_ranges <- function(x, rt = matrix(nrow = 0, ncol = 2), + mz = matrix(nrow = 0, ncol = 2), + aggregationFun = "sum", msLevel = 1L, + isolationWindow = NULL, + chunkSize = 2L, progressbar = TRUE, + BPPARAM = bpparam()) { if (!nrow(rt)) rt <- matrix(c(-Inf, Inf), ncol = 2) if (!nrow(mz)) @@ -519,6 +524,224 @@ res } +#' Extract `Chromatograms` for rt and m/z ranges defined with parameters +#' `rt` and `mz`. A chromatogram for each defined range will be extracted +#' from **each sample**/file in `object`. If `rt` and `mz` is omitted a TIC +#' or BPC is returned. +#' In the long run, this function should replace the +#' `.mse_mchromatograms_for_ranges()` function above. +#' +#' @param object `XcmsExperiment` object. +#' +#' @param rt two-column `numeric` `matrix` with the retention time boundaries. +#' The number of rows of `rt` and `mz` have to match. +#' +#' @param mz two-column `numeric` `matrix` with the m/z boundaries. The number +#' of rows of `rt` and `mz` have to match. +#' +#' @param aggregationFun `character(1)` defining the function to aggregate the +#' intensity values per rtime. +#' +#' @param msLevel `integer` with the MS level(s) on which the Chromatograms +#' should be generated. Should be either of length 1 or equal to the number +#' of rows of `rt`. +#' +#' @param isolationWindow optional `numeric` with the isolation window target +#' m/z of each (MS2) spectrum. Ignored for `msLevel = 1L` or if set to +#' `NULL` or `NA`. If provided, it's length needs to match the number of +#' chromatograms to extract. The value of `isolationWindow` is matched +#' to the `isolationWindowTargetMz` value of the spectra. +#' +#' @return A `Chromatograms` object with a chromatogram for each rt-m/z range +#' (defined by each row in `rt` and `mz`) in **each** sample. The +#' `Chromatograms` is ordered by ranges (i.e. first all chromatograms for +#' the first range in all files, then the second range in all files etc). +#' +#' @importMethodsFrom Chromatograms Chromatograms +#' +#' @importClassesFrom Chromatograms Chromatograms +#' +#' @noRd +.mse_chromatograms_for_ranges <- function(object, + rt = matrix(ncol = 2, nrow = 0), + mz = matrix(ncol = 2, nrow = 0), + aggregationFun = c("sum", "max"), + msLevel = 1L, + isolationWindow = NULL, ...) { + aggregationFun <- match.arg(aggregationFun) + ## Subset the chromPeaks based on msLevel, rt, and mz. + s <- filterMsLevel(spectra(object), unique(msLevel)) + if (nrow(rt)) + s <- filterRt(s, rt = range(rt)) + fb <- c("dataOrigin", "msLevel") + if (length(isolationWindow) == 1L) + isolationWindow <- rep(isolationWindow, nrow(rt)) + if (length(isolationWindow) && !is.na(isolationWindow[1L])) { + if (length(isolationWindow) != nrow(rt)) + stop("If provided, the length of 'isolationWindow' has to match ", + "the number of chromatograms to extract.", call. = FALSE) + fb <- c(fb, "isolationWindowTargetMz") + } + cd <- .chrom_data_for_ranges(rt, mz, fileNames(object), msLevel, + isolationWindowTargetMz = isolationWindow) + Chromatograms(s, chromData = cd, factorize.by = fb, + summarize.method = aggregationFun) +} + +#' Helper function to compile the `chromData` for a `Chromatograms` object. +#' The function repeats each row of `rt` and `mz` by the length of `dataOrigin`. +#' +#' @note +#' +#' No input argument checking is performed. This is expected to be done by the +#' upstream function. +#' +#' @param rt two-column `numeric` `matrix` with the rt ranges. +#' +#' @param mz two-column `numeric` `matrix` with the mz ranges. +#' +#' @param dataOrigin `character` with the **unique** file names/data origin. +#' +#' @param msLevel `integer` with the MS level for the chromatograms. Has to be +#' of length 1 or equal to `nrow(rt)`. +#' +#' @param isolationWindowTargetMz optional `numeric` of length equal to the +#' nrow of `rt`. +#' +#' @return `data.frame` for the `Chromatograms` call with columns `"rtMin"`, +#' `"rtMax"`, `"mzMin"`, `"mzMax"` and `"dataOrigin"`. If `nrow` `rt` is 0 +#' an empty `data.frame` is returned. +#' +#' @noRd +.chrom_data_for_ranges <- function(rt = matrix(nrow = 0, ncol = 2), + mz = matrix(nrow = 0, ncol = 2), + dataOrigin = character(), msLevel = 1L, + isolationWindowTargetMz = NULL) { + m <- nrow(rt) + n <- length(dataOrigin) + if (!m) + return(data.frame()) + if (length(msLevel) != m) + rep(msLevel[1L], m) + res <- data.frame(rtMin = rep(rt[, 1L], each = n), + rtMax = rep(rt[, 2L], each = n), + mzMin = rep(mz[, 1L], each = n), + mzMax = rep(mz[, 2L], each = n), + dataOrigin = rep(dataOrigin, m), + msLevel = rep(msLevel, each = n)) + if (length(isolationWindowTargetMz)) + res$isolationWindowTargetMz <- rep(isolationWindowTargetMz, each = n) + res +} + +#' Extract EICs as `Chromatograms` object based on rt/mz boundaries from +#' chromatographic peaks. The logic of the code is similar to +#' `.mse_chromatograms_for_ranges` but here we have specific rt and m/z ranges +#' **for each individual sample** (while in the former the same rt/mz range +#' is extracted from each sample). +#' +#' @param object `MsExperiment` or `XcmsExperiment` object. +#' +#' @param pks `numeric` `matrix` defining the chrom peak boundaries, i.e. the +#' `chromPeaks()`. Required columns are `"rtmin"`, `"rtmax"`, `"mzmin"`, +#' `"mzmax"` and `"sample"`. +#' +#' @param pkd `chromPeakData()` `data.frame` with mandatory column `"ms_level"`. +#' If a column `"isolationWindow"` is present it is also passed to the +#' `Chromatograms` call. +#' +#' @param aggregationFun `character(1)` defining the method to aggregate +#' intensities per retention time. This is passed to the `summarize.method` +#' parameter of `Chromatograms()`. +#' +#' @param expandRt `numeric(1)` with the value to expand the retention time +#' window on **both** sides. +#' +#' @param expandMz `numeric(1)` with the value to expand the m/z window on +#' **both** sides. +#' +#' @return `Chromatograms`, one for each chromatographic peak defined by each +#' row in `pks` (`pkd`). +#' +#' @noRd +.mse_chromatograms_for_peaks <- function(object, pks, pkd, + aggregationFun = c("max", "sum"), + expandRt = 0.0, expandMz = 0.0) { + if (!nrow(pks)) + return(Chromatograms()) + aggregationFun <- match.arg(aggregationFun) + cd <- data.frame(rtMin = pks[, "rtmin"] - expandRt, + rtMax = pks[, "rtmax"] + expandRt, + mzMin = pks[, "mzmin"] - expandMz, + mzMax = pks[, "mzmax"] + expandMz, + msLevel = pkd$ms_level, + dataOrigin = fileNames(object)[pks[, "sample"]]) + fb <- c("dataOrigin", "msLevel") + if (any(!is.na(pkd$isolationWindow))) { + cd$isolationWindowTargetMz <- pkd$isolationWindow + fb <- c(fb, "isolationWindowTargetMz") + } + s <- filterRt(filterMsLevel(spectra(object), unique(cd$msLevel)), + c(min(cd$rtMin), max(cd$rtMax))) + Chromatograms(s, chromData = cd, factorize.by = fb, + summarize.method = aggregationFun) +} + +#' Helper to extract EICs for each peak defined by `pks` and `pkd` and return +#' that as a `MSnbase::MChromatograms` object. This is for backward +#' compatibility but in future `mse_chromatograms_for_peaks()` should be used +#' instead. +#' +#' @noRd +.mse_mchromatograms_for_peaks <- function(object, pks, pkd, + aggregationFun = c("max", "sum"), + expandRt = 0.0, expandMz = 0.0) { + aggregationFun <- match.arg(aggregationFun) + pb <- progress_bar$new(format = paste0("[:bar] :current/:", + "total (:percent) in ", + ":elapsed"), + total = (length(object)), clear = FALSE) + pb$tick(0) + rownames(sampleData(object)) <- NULL # don't track sample names + res <- lapply(seq_along(object), function(z) { + idx <- which(pks[, "sample"] == z) + if (length(idx)) { + mzr <- pks[idx, c("mzmin", "mzmax"), drop = FALSE] + rtr <- pks[idx, c("rtmin", "rtmax"), drop = FALSE] + if (expandMz != 0) { + mzr[, 1] <- mzr[, 1] - expandMz + mzr[, 2] <- mzr[, 2] + expandMz + } + if (expandRt != 0) { + rtr[, 1] <- rtr[, 1] - expandRt + rtr[, 2] <- rtr[, 2] + expandRt + } + chrs <- .mse_mchromatograms_for_ranges( + object[z], rt = rtr, mz = mzr, + aggregationFun = aggregationFun, + msLevel = pkd$ms_level[idx], + isolationWindow = pkd$isolationWindow[idx], + chunkSize = 1L, progressbar = FALSE, + BPPARAM = SerialParam()) + fData(chrs)$sample_index <- z # report sample index + pb$tick() + rownames(chrs) <- rownames(pks)[idx] + rownames(fData(chrs)) <- rownames(chrs) + chrs + } else { + pb$tick() + NULL + } + }) + res <- as(do.call(c, res[lengths(res) > 0]), "MChromatograms") + pData(res)[,] <- NA # it's not from a single file. + colnames(res) <- NULL + ## re-order the result - if needed. + if (any(rownames(res) != rownames(pks))) + res <- res[match(rownames(pks), rownames(res)), 1L] + res +} + #' Split an `MsExperiment` by a spectra variable keeping sample to spectra #' mapping. #' diff --git a/R/MsExperiment.R b/R/MsExperiment.R index 2110fe18..1df9c7c0 100644 --- a/R/MsExperiment.R +++ b/R/MsExperiment.R @@ -100,7 +100,9 @@ setMethod( function(object, rt = matrix(nrow = 0, ncol = 2), mz = matrix(nrow = 0, ncol = 2), aggregationFun = "sum", msLevel = 1L, isolationWindowTargetMz = NULL, chunkSize = 2L, - return.type = "MChromatograms", BPPARAM = bpparam()) { + return.type = c("MChromatograms", "Chromatograms"), + BPPARAM = bpparam()) { + return.type <- match.arg(return.type) if (!is.matrix(rt)) rt <- matrix(rt, ncol = 2L) if (!is.matrix(mz)) @@ -109,10 +111,15 @@ setMethod( rt <- cbind(rep(-Inf, nrow(mz)), rep(Inf, nrow(mz))) if (nrow(rt) && !nrow(mz)) mz <- cbind(rep(-Inf, nrow(rt)), rep(Inf, nrow(rt))) - .mse_chromatogram( - object, rt = rt, mz = mz, aggregationFun = aggregationFun, - msLevel = msLevel, isolationWindow = isolationWindowTargetMz, - chunkSize = chunkSize, BPPARAM = BPPARAM) + switch(return.type, + MChromatograms = .mse_mchromatograms_for_ranges( + object, rt = rt, mz = mz, aggregationFun = aggregationFun, + msLevel = msLevel, isolationWindow = isolationWindowTargetMz, + chunkSize = chunkSize, BPPARAM = BPPARAM), + Chromatograms = .mse_chromatograms_for_ranges( + object, rt = rt, mz = mz, aggregationFun = aggregationFun, + msLevel = msLevel, isolationWindow = isolationWindowTargetMz) + ) }) #' @rdname estimatePrecursorIntensity diff --git a/R/XcmsExperiment-functions.R b/R/XcmsExperiment-functions.R index 4c467078..585b73fa 100644 --- a/R/XcmsExperiment-functions.R +++ b/R/XcmsExperiment-functions.R @@ -974,7 +974,7 @@ chunkSize, chromPeaks, return.type, BPPARAM) { message("Extracting chromatographic data") - chrs <- as(.mse_chromatogram( + chrs <- as(.mse_mchromatograms_for_ranges( as(object, "MsExperiment"), rt = rt, mz = mz, aggregationFun = aggregationFun, msLevel = msLevel, isolationWindow = isolationWindow, chunkSize = chunkSize, @@ -1232,7 +1232,7 @@ #' @noRd .chromPeakData <- function(object, msLevel = integer(), columns = character()) { if (is(object, "XcmsExperimentHdf5")) - return(chromPeakData(object, msLevel = msLevel, + return(chromPeakData(object, msLevel = msLevel, columns = columns, return.type = "data.frame")) if (length(columns)) { if (!all(columns %in% colnames(object@chromPeakData))) @@ -1252,12 +1252,16 @@ #' filtering from either a `XcmsExperiment` or `XCMSnExp` object #' #' @noRd -.chromPeaks <- function(object) { +.chromPeaks <- function(object, columns = character()) { if (inherits(object, "XcmsExperiment")) { - if (is(object, "XcmsExperimentHdf5")) - chromPeaks(object) - else - object@chromPeaks + if (is(object, "XcmsExperimentHdf5")) { + chromPeaks(object, columns = columns) + } else { + if (length(columns)) + object@chromPeaks[, columns, drop = FALSE] + else + object@chromPeaks + } } else chromPeaks(object@msFeatureData) } @@ -1402,3 +1406,174 @@ XcmsExperiment <- function() { validObject(n) n } + +#' Extract `Chromatograms` for features. +#' +#' Called in `featureChromatograms,XcmsExperiment`. +#' +#' @param featureArea `logical(1)` whether each chromatogram should represent +#' the signal found in the *feature area* (`featureArea = TRUE`, the +#' default) or the actual EIC of the assigned chromatographic peak +#' (`featureArea = FALSE`). +#' +#' For all other parameters see `featureChromatograms,XcmsExperiment`. +#' +#' @return `Chromatograms` object with additional variables `"feature_id"` and +#' for `featureArea = FALSE` also `"chrom_peak_id"`. +#' +#' @noRd +.xmse_chromatograms_for_features <- function(x, expandRt = 0.0, expandMz = 0.0, + aggregationFun = "max", + features = character(), + mzmin = min, mzmax = max, + rtmin = min, rtmax = max, + featureArea = TRUE) { + if (featureArea) { + area <- featureArea(x, mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, + rtmax = rtmax, features = features) + if (expandRt != 0) { + area[, "rtmin"] <- area[, "rtmin"] - expandRt + area[, "rtmax"] <- area[, "rtmax"] + expandRt + } + if (expandMz != 0) { + area[, "mzmin"] <- area[, "mzmin"] - expandMz + area[, "mzmax"] <- area[, "mzmax"] + expandMz + } + fts <- featureDefinitions(x)[rownames(area), , drop = FALSE] + chrs <- .mse_chromatograms_for_ranges( + as(x, "MsExperiment"), + rt = area[, c("rtmin", "rtmax"), drop = FALSE], + mz = area[, c("mzmin", "mzmax"), drop = FALSE], + aggregationFun = aggregationFun, msLevel = fts$ms_level) + chrs$feature_id <- rep(rownames(area), each = length(fileNames(x))) + } else { + pidx <- featurePeakidx(x) + if (!length(features)) + features <- names(pidx) + else if (!all(features %in% names(pidx))) + stop("One or more of the provided feature IDs in 'features' can", + " not be found", call. = FALSE) + pidx <- pidx[features] + ls <- lengths(pidx) + pidx <- unlist(pidx, use.names = FALSE) + pks <- .chromPeaks( + x, columns = c("rtmin", "rtmax", "mzmin", + "mzmax", "sample"))[pidx, , drop = FALSE] + pkd <- chromPeakData(x, return.type = "data.frame")[pidx, ,drop = FALSE] + chrs <- .mse_chromatograms_for_peaks( + as(x, "MsExperiment"), pks = pks, pkd = pkd, + aggregationFun = aggregationFun, + expandRt = expandRt, expandMz = expandMz) + chrs$feature_id <- rep(features, ls) + chrs$chrom_peak_id <- rownames(pks) + } + chrs +} + +#' Extract chromatograms for features returned as a `MChromatograms`. +#' +#' Called in `featureChromatograms,XcmsExperiment` and +#' `.xmse_xchromatograms_for_features()`. +#' +#' For all parameters see `featureChromatograms,XcmsExperiment`. +#' +#' @noRd +.xmse_mchromatograms_for_features <- function(x, expandRt = 0.0, expandMz = 0.0, + aggregationFun = "max", + features = character(), + mzmin = min, mzmax = max, + rtmin = min, rtmax = max, + chunkSize = 2L, ..., + progressbar = TRUE, + BPPARAM = bpparam()) { + area <- featureArea(x, mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, + rtmax = rtmax, features = features) + if (expandRt != 0) { + area[, "rtmin"] <- area[, "rtmin"] - expandRt + area[, "rtmax"] <- area[, "rtmax"] + expandRt + } + if (expandMz != 0) { + area[, "mzmin"] <- area[, "mzmin"] - expandMz + area[, "mzmax"] <- area[, "mzmax"] + expandMz + } + fts <- featureDefinitions(x)[rownames(area), , drop = FALSE] + chrs <- .mse_mchromatograms_for_ranges( + as(x, "MsExperiment"), rt = area[, c("rtmin", "rtmax"), drop = FALSE], + mz = area[, c("mzmin", "mzmax"), drop = FALSE], + aggregationFun = aggregationFun, msLevel = fts$ms_level, + chunkSize = chunkSize, progressbar = progressbar, BPPARAM = BPPARAM) + chrs@featureData$feature_id <- rownames(area) + chrs +} + +#' Extract chromatograms for features returned as a `XChromatograms`. +#' +#' Called in `featureChromatograms,XcmsExperiment`. +#' +#' For all parameters see `featureChromatograms,XcmsExperiment`. +#' +#' @noRd +.xmse_xchromatograms_for_features <- function(x, expandRt = 0.0, expandMz = 0.0, + aggregationFun = "max", + features = character(), + mzmin = min, mzmax = max, + rtmin = min, rtmax = max, + chunkSize = 2L, ..., + progressbar = TRUE, + BPPARAM = bpparam()) { + chrs <- as(.xmse_mchromatograms_for_features( + x, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, mzmin = mzmin, + mzmax = mzmax, rtmin = rtmin, rtmax = rtmax, chunkSize = chunkSize, + progressbar = progressbar, BPPARAM = BPPARAM), "XChromatograms") + ## Populate with chrom peaks. + fts <- featureDefinitions(x)[fData(chrs)$feature_id, , drop = FALSE] + nf <- nrow(fts) + js <- seq_len(ncol(chrs)) + pks_empty <- .chromPeaks(x)[integer(), , drop = FALSE] + pkd_empty <- as(.chromPeakData(x)[integer(), , drop = FALSE], "DataFrame") + tmp <- chrs@.Data + slot(chrs, ".Data") <- matrix(nrow = nrow(tmp), ncol = ncol(tmp)) + if (progressbar) { + message("Processing chromatographic peaks for features") + pb <- progress_bar$new(format = paste0("[:bar] :current/:", + "total (:percent) in ", + ":elapsed"), + total = nf + 1L, clear = FALSE) + } + for (i in seq_len(nf)) { + idx <- fts$peakidx[[i]] + smpl <- .chromPeaks(x)[idx, "sample"] + for (j in js) { + keep <- smpl == j + tmp_i <- tmp[i, j][[1L]] + if (any(keep)) { + slot(tmp_i, "chromPeaks", check = FALSE) <- + .chromPeaks(x)[idx[keep], , drop = FALSE] + slot(tmp_i, "chromPeakData", + check = FALSE) <- as( + x@chromPeakData[idx[keep], , drop = FALSE], + "DataFrame") + } else { + slot(tmp_i, "chromPeaks", check = FALSE) <- pks_empty + slot(tmp_i, "chromPeakData", check = FALSE) <- pkd_empty + } + tmp[i, j][[1L]] <- tmp_i + } + if (progressbar) + pb$tick() + } + slot(chrs, ".Data", check = FALSE) <- tmp + ## Each row is a SINGLE feature, thus we can use the "row" column to + ## match chrom peaks to features. + fts$row <- seq_len(nf) + pkrow <- unname(chromPeaks(chrs)[, c("row")]) + fts$peakidx <- unname(split(seq_along(pkrow), pkrow)) + colnames(chrs) <- basename(fileNames(x)) + rownames(chrs@phenoData) <- colnames(chrs) + slot(chrs, "featureDefinitions", check = FALSE) <- DataFrame(fts) + slot(chrs, ".processHistory", check = FALSE) <- x@processHistory + if (progressbar) + pb$tick() + chrs +} diff --git a/R/XcmsExperiment.R b/R/XcmsExperiment.R index 90778146..fb2cddc7 100644 --- a/R/XcmsExperiment.R +++ b/R/XcmsExperiment.R @@ -2,6 +2,9 @@ #' #' @aliases XcmsExperiment-class filterChromPeaks #' @aliases featureArea quantify +#' @aliases coerce,XcmsExperiment,xcmsSet-method +#' @aliases coerce,XcmsExperiment,XCMSnExp-method +#' @aliases coerce,XCMSnExp,XcmsExperiment-method #' #' @description #' @@ -129,29 +132,33 @@ #' extract the data from (to e.g. for extracted ion chromatograms EICs). #' Both parameters are expected to be numerical two-column matrices with #' the first column defining the lower and the second the upper margin. -#' Each row can define a separate m/z - retention time region. Currently -#' the function returns a [MSnbase::MChromatograms()] object for `object` -#' being a `MsExperiment` or, for `object` being an `XcmsExperiment`, -#' either a `MChromatograms` or [XChromatograms()] depending on parameter -#' `return.type` (can be either `"MChromatograms"` or `"XChromatograms"`). -#' For the latter also chromatographic peaks detected within the provided -#' m/z and retention times are returned. Parameter `chromPeaks` allows +#' Each row can define a separate m/z - retention time region. +#' +#' The chromatographic data can be returned either as an +#' [MSnbase::MChromatograms] object (parameter +#' `return.type = "MChromatograms"`, the default) or as the newer +#' [Chromatograms::Chromatograms()] container +#' (`return.type = "Chromatograms"`). If `object` is an *xcms* result object +#' (`XcmsExperiment`), the default is to return a [XChromatograms()] object +#' that contains also chromatographic peak and feature information. For +#' `XChromatograms` return type, the `chromPeaks` parameter allows #' to specify which chromatographic peaks should be reported. See #' documentation on the `chromPeaks` parameter for more information. #' If the `XcmsExperiment` contains correspondence results, also the #' associated feature definitions will be included in the returned -#' `XChromatograms`. By default the function returns chromatograms from MS1 -#' data, but by setting parameter `msLevel = 2L` it is possible to e.g. -#' extract also MS2 chromatograms. By default, with parameter -#' `isolationWindowTargetMz = NULL` or `isolationWindowTargetMz = NA_real_`, -#' data from **all** MS2 spectra will be considered in the chromatogram -#' extraction. If MS2 data was generated within different m/z isolation -#' windows (such as e.g. with Scies SWATH data), the parameter -#' `isolationWindowTargetMz` should be used to ensure signal is only extracted -#' from the respective isolation window. The `isolationWindowTargetMz()` -#' function on the `Spectra` object can be used to inspect/list available -#' isolation windows of a data set. See also the xcms *LC-MS/MS vignette* for -#' examples and details. +#' `XChromatograms`. +#' +#' By default the function returns chromatograms from MS level 1, but by +#' setting parameter `msLevel = 2L` it is possible to extract MS2 +#' chromatograms. By default, with parameter `isolationWindowTargetMz = NULL` +#' or `isolationWindowTargetMz = NA_real_`, data from **all** MS2 spectra +#' will be considered in the chromatogram extraction. If MS2 data was +#' generated within different m/z isolation windows (such as e.g. with +#' Sciex SWATH data), the parameter `isolationWindowTargetMz` should be used +#' to ensure signal is only extracted from the specified isolation window. +#' The [Spectra::isolationWindowTargetMz()] function on the `Spectra` object +#' can be used to inspect/list available isolation windows of a data set. +#' See also the xcms *LC-MS/MS vignette* for examples and details. #' #' - `chromPeaks()`: returns a `numeric` matrix with the identified #' chromatographic peaks. Each row represents a chromatographic peak @@ -291,6 +298,9 @@ #' - `featureChromatograms()`: extract ion chromatograms (EICs) for each #' feature in `object`. See [featureChromatograms()] for more details. #' +#' - `featureChromPeaks()`: get the mapping between features and chromatographic +#' peaks. See [featureChromPeaks()] for details. +#' #' - `featureDefinitions()`: returns a `data.frame` with feature definitions or #' an empty `data.frame` if no correspondence analysis results are present. #' Parameters `msLevel`, `mz`, `ppm` and `rt` allow to define subsets of @@ -298,6 +308,10 @@ #' defining how these parameters should be used to subset the returned #' `data.frame`. See parameter descriptions for details. #' +#' - `featurePeakidx()`: get the indices of chromatographic peaks in the +#' `chromPeaks()` matrix assigned to each feature. See [featurePeakidx()] for +#' details. +#' #' - `featureSpectra()`: returns a [Spectra::Spectra()] or `List` of `Spectra` #' with (MS1 or MS2) spectra associated to each feature's chromatographic #' peaks. See [featureSpectra()] for more details and available parameters. @@ -577,8 +591,12 @@ #' @param return.type For `chromPeakData()`: `character(1)` defining the #' class of the returned object. Can be either `"DataFrame"` (the default) #' or `"data.frame"`. For `chromatogram()`: `character(1)` defining the -#' type of the returned object. Currently only -#' `return.type = "MChromatograms"` is supported. +#' type of the returned object. For `MsExperiment` objects +#' `return.type = "MChromatograms"` (the default) and +#' `return.type = "Chromatograms"` allows to return a +#' [MSnbase::MChromatograms] or a [Chromatograms::Chromatograms()] object, +#' for `XcmsExperiment` also `return.type = "XChromatogram"` is supported +#' which returns the chromatographic data as a [XChromatograms] object. #' #' @param rt For `chromPeaks()` and `featureDefinitions()`: `numeric(2)` #' defining the retention time range for which chromatographic peaks @@ -710,6 +728,26 @@ #' ## Plot the EICs for the second defined region #' plot(chrs[2, ]) #' +#' ## Extract chromatographic data for the first two chromatographic peaks +#' ## as the new `Chromatograms` object. +#' chrs <- chromatogram(xmse, +#' mz = chromPeaks(xmse)[1:2, c("mzmin", "mzmax")], +#' rt = chromPeaks(xmse)[1:2, c("rtmin", "rtmax")], +#' return.type = "Chromatograms") +#' chrs +#' +#' ## Get the intensity values from each chromatogram +#' intensity(chrs) +#' +#' ## Plot all EICs into a single plot +#' Chromatograms::plotChromatogramsOverlay(chrs) +#' +#' ## Plot the first EIC on the 3 files +#' Chromatograms::plotChromatogramsOverlay(chrs[1:3]) +#' +#' ## Plot the second EIC on the 3 files +#' Chromatograms::plotChromatogramsOverlay(chrs[4:6]) +#' #' ## Subsetting the data to the results (and data) for the second sample #' a <- xmse[2] #' nrow(chromPeaks(xmse)) @@ -818,6 +856,8 @@ setMethod("show", "XcmsExperiment", function(object) { }) #' @rdname XcmsExperiment +#' +#' @export c.XcmsExperiment <- function(...) { l <- list(...) if (length(l) == 1L) @@ -1086,7 +1126,7 @@ setMethod( #' @rdname XcmsExperiment setReplaceMethod("chromPeakData", "XcmsExperiment", function(object, value) { - object@chromPeakData <- value + object@chromPeakData <- as.data.frame(value) object }) @@ -1658,6 +1698,26 @@ setMethod( ppm = ppm, type = type) }) +#' @rdname featureChromPeaks +setMethod("featurePeakidx", "XcmsResult", function(object, + msLevel = integer()) { + fd <- featureDefinitions(object, msLevel = msLevel) + res <- fd$peakidx + names(res) <- rownames(fd) + res +}) + +#' @rdname featureChromPeaks +setMethod("featureChromPeaks", "XcmsResult", function(object, + msLevel = integer()) { + pidx <- featurePeakidx(object, msLevel = msLevel) + data.frame( + feature_id = rep(rownames(featureDefinitions( + object, msLevel = msLevel)), lengths(pidx)), + chrom_peak_id = rownames(chromPeaks( + object, msLevel = msLevel))[unlist(pidx)]) +}) + #' @rdname XcmsExperiment setMethod( "dropFeatureDefinitions", "XcmsExperiment", @@ -1714,7 +1774,8 @@ setMethod( "chromPeakChromatograms", "XcmsExperiment", function(object, expandRt = 0, expandMz = 0, aggregationFun = "max", peaks = character(), - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", + "Chromatograms"), ..., progressbar = TRUE) { return.type <- match.arg(return.type) if (!hasChromPeaks(object)) @@ -1727,157 +1788,84 @@ setMethod( "vector with the IDs (row names) of the ", "chromatographic peaks.") if (!is.character(peaks)) - stop(msg) + stop(msg, call. = FALSE) if (!all(peaks %in% rownames(pks))) - stop("'peaks' don't match row names of 'chromPeaks'. ", msg) + stop("'peaks' don't match row names of 'chromPeaks'. ", msg, + call. = FALSE) pks <- pks[peaks, , drop = FALSE] pkd <- pkd[peaks, ] } - pb <- progress_bar$new(format = paste0("[:bar] :current/:", - "total (:percent) in ", - ":elapsed"), - total = (length(object) + 1), clear = FALSE) - pb$tick(0) if (hasAdjustedRtime(object)) object <- applyAdjustedRtime(object) - ph <- object@processHistory - object <- as(object, "MsExperiment") - rownames(sampleData(object)) <- NULL # don't track sample names - res <- lapply(seq_along(object), function(z) { - idx <- which(pks[, "sample"] == z) - if (length(idx)) { - mzr <- pks[idx, c("mzmin", "mzmax"), drop = FALSE] - rtr <- pks[idx, c("rtmin", "rtmax"), drop = FALSE] - if (expandMz != 0) { - mzr[, 1] <- mzr[, 1] - expandMz - mzr[, 2] <- mzr[, 2] + expandMz - } - if (expandRt != 0) { - rtr[, 1] <- rtr[, 1] - expandRt - rtr[, 2] <- rtr[, 2] + expandRt - } - chrs <- .mse_chromatogram( - object[z], rt = rtr, mz = mzr, - aggregationFun = aggregationFun, - msLevel = pkd$ms_level[idx], - isolationWindow = pkd$isolationWindow[idx], - chunkSize = 1L, progressbar = FALSE, - BPPARAM = SerialParam()) - fData(chrs)$sample_index <- z # report sample index - pb$tick() - rownames(chrs) <- rownames(pks)[idx] - rownames(fData(chrs)) <- rownames(chrs) - chrs - } else { - pb$tick() - NULL - } - }) - res <- as(do.call(c, res[lengths(res) > 0]), return.type) - pData(res)[,] <- NA # it's not from a single file. - colnames(res) <- NULL - ## re-order the result - if needed. - if (any(rownames(res) != rownames(pks))) - res <- res[match(rownames(pks), rownames(res)), 1L] - if (return.type == "XChromatograms") { - idx <- seq_along(res) - pks <- split.data.frame(pks, idx) - pkd <- split.data.frame(pkd, idx) - mat <- res@.Data - slot(res, ".Data", check = FALSE) <- matrix(ncol = ncol(res), - nrow = nrow(res)) - for (i in seq_along(res)) { - tmp <- mat[i, 1L][[1L]] - slot(tmp, "chromPeaks", check = FALSE) <- pks[[i]] - slot(tmp, "chromPeakData", check = FALSE) <- - as(pkd[[i]], "DataFrame") - mat[i, 1L][[1L]] <- tmp - } - slot(res, ".Data", check = FALSE) <- mat - slot(res, ".processHistory", check = FALSE) <- ph - } - pb$tick() - res + switch(return.type, + ## Chromatograms + Chromatograms = { + res <- .mse_chromatograms_for_peaks( + object, pks, pkd, aggregationFun = aggregationFun, + expandRt = expandRt, expandMz = expandMz) + res$chrom_peak_id <- rownames(pks) + res + }, + ## MSnbase::MChromatograms + MChromatograms = .mse_mchromatograms_for_peaks( + as(object, "MsExperiment"), pks, pkd, aggregationFun, + expandRt = expandRt, expandMz = expandMz), + ## xcms::XChromatograms: MChromatograms + chrom peaks. + XChromatograms = { + res <- .mse_mchromatograms_for_peaks( + as(object, "MsExperiment"), pks, pkd, aggregationFun, + expandRt = expandRt, expandMz = expandMz) + res <- as(res, "XChromatograms") + idx <- seq_along(res) + pks <- split.data.frame(pks, idx) + pkd <- split.data.frame(pkd, idx) + mat <- res@.Data + slot(res, ".Data", check = FALSE) <- matrix(ncol = ncol(res), + nrow = nrow(res)) + for (i in seq_along(res)) { + tmp <- mat[i, 1L][[1L]] + slot(tmp, "chromPeaks", check = FALSE) <- pks[[i]] + slot(tmp, "chromPeakData", check = FALSE) <- + as(pkd[[i]], "DataFrame") + mat[i, 1L][[1L]] <- tmp + } + slot(res, ".Data", check = FALSE) <- mat + slot(res, ".processHistory") <- object@processHistory + res + }) }) #' @rdname featureChromatograms setMethod( "featureChromatograms", "XcmsExperiment", - function(object, expandRt = 0, expandMz = 0, aggregationFun = "max", - features = character(), return.type = "XChromatograms", + function(object, expandRt = 0.0, expandMz = 0.0, aggregationFun = "max", + features = character(), + return.type = c("XChromatograms","MChromatograms","Chromatograms"), chunkSize = 2L, mzmin = min, mzmax = max, rtmin = min, - rtmax = max, ..., progressbar = TRUE, BPPARAM = bpparam()) { + rtmax = max, featureArea = TRUE, ..., + progressbar = TRUE, BPPARAM = bpparam()) { return.type <- match.arg(return.type) if (hasAdjustedRtime(object)) object <- applyAdjustedRtime(object) - area <- featureArea(object, mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, - rtmax = rtmax, features = features) - if (expandRt != 0) { - area[, "rtmin"] <- area[, "rtmin"] - expandRt - area[, "rtmax"] <- area[, "rtmax"] + expandRt - } - if (expandMz != 0) { - area[, "mzmin"] <- area[, "mzmin"] - expandMz - area[, "mzmax"] <- area[, "mzmax"] + expandMz - } - fts <- featureDefinitions(object)[rownames(area), ] - chrs <- as(.mse_chromatogram( - as(object, "MsExperiment"), - rt = area[, c("rtmin", "rtmax"), drop = FALSE], - mz = area[, c("mzmin", "mzmax"), drop = FALSE], - aggregationFun = aggregationFun, msLevel = fts$ms_level, - chunkSize = chunkSize, progressbar = progressbar, - BPPARAM = BPPARAM), "XChromatograms") - ## Populate with chrom peaks. - nf <- nrow(fts) - js <- seq_len(ncol(chrs)) - pks_empty <- .chromPeaks(object)[integer(), , drop = FALSE] - pkd_empty <- as(.chromPeakData(object)[integer(), , drop = FALSE], - "DataFrame") - tmp <- chrs@.Data - slot(chrs, ".Data") <- matrix(nrow = nrow(tmp), ncol = ncol(tmp)) - if (progressbar) { - message("Processing chromatographic peaks for features") - pb <- progress_bar$new(format = paste0("[:bar] :current/:", - "total (:percent) in ", - ":elapsed"), - total = nf + 1L, clear = FALSE) - } - for (i in seq_len(nf)) { - idx <- fts$peakidx[[i]] - smpl <- .chromPeaks(object)[idx, "sample"] - for (j in js) { - keep <- smpl == j - tmp_i <- tmp[i, j][[1L]] - if (any(keep)) { - slot(tmp_i, "chromPeaks", check = FALSE) <- - .chromPeaks(object)[idx[keep], , drop = FALSE] - slot(tmp_i, "chromPeakData", - check = FALSE) <- as( - object@chromPeakData[idx[keep], , drop = FALSE], - "DataFrame") - } else { - slot(tmp_i, "chromPeaks", check = FALSE) <- pks_empty - slot(tmp_i, "chromPeakData", check = FALSE) <- pkd_empty - } - tmp[i, j][[1L]] <- tmp_i - } - if (progressbar) - pb$tick() - } - slot(chrs, ".Data", check = FALSE) <- tmp - ## Each row is a SINGLE feature, thus we can use the "row" column to - ## match chrom peaks to features. - fts$row <- seq_len(nf) - pkrow <- unname(chromPeaks(chrs)[, c("row")]) - fts$peakidx <- unname(split(seq_along(pkrow), pkrow)) - colnames(chrs) <- basename(fileNames(object)) - rownames(chrs@phenoData) <- colnames(chrs) - slot(chrs, "featureDefinitions", check = FALSE) <- DataFrame(fts) - slot(chrs, ".processHistory", check = FALSE) <- object@processHistory - if (progressbar) - pb$tick() - chrs + switch(return.type, + Chromatograms = .xmse_chromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, + rtmax = rtmax, featureArea = featureArea), + MChromatograms = .xmse_mchromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + chunkSize = chunkSize, mzmin = mzmin, mzmax = mzmax, + rtmin = rtmin, rtmax = rtmax, progressbar = progressbar, + BPPARAM = BPPARAM), + XChromatograms = .xmse_xchromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + chunkSize = chunkSize, mzmin = mzmin, mzmax = mzmax, + rtmin = rtmin, rtmax = rtmax, progressbar = progressbar, + BPPARAM = BPPARAM) + ) }) #' @rdname XcmsExperiment @@ -2108,7 +2096,8 @@ setMethod( function(object, rt = matrix(nrow = 0, ncol = 2), mz = matrix(nrow = 0, ncol = 2), aggregationFun = "sum", msLevel = 1L, chunkSize = 2L, isolationWindowTargetMz = NULL, - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", + "Chromatograms"), include = character(), chromPeaks = c("apex_within", "any", "none"), BPPARAM = bpparam()) { @@ -2127,12 +2116,22 @@ setMethod( chromPeaks <- match.arg(chromPeaks) if (hasAdjustedRtime(object)) object <- applyAdjustedRtime(object) - .xmse_extract_chromatograms_old( - object, rt = rt, mz = mz, aggregationFun = aggregationFun, - msLevel = msLevel, isolationWindow = isolationWindowTargetMz, - chunkSize = chunkSize, chromPeaks = chromPeaks, - return.type = return.type, BPPARAM = BPPARAM) - }) + switch(return.type, + MChromatograms = .mse_mchromatograms_for_ranges( + as(object, "MsExperiment"), rt = rt, mz = mz, + aggregationFun = aggregationFun, msLevel = msLevel, + isolationWindow = isolationWindowTargetMz, + chunkSize = chunkSize, BPPARAM = BPPARAM), + XChromatograms = .xmse_extract_chromatograms_old( + object, rt = rt, mz = mz, aggregationFun = aggregationFun, + msLevel = msLevel, isolationWindow = isolationWindowTargetMz, + chunkSize = chunkSize, chromPeaks = chromPeaks, + return.type = return.type, BPPARAM = BPPARAM), + Chromatograms = .mse_chromatograms_for_ranges( + object, rt = rt, mz = mz, aggregationFun = aggregationFun, + msLevel = msLevel, isolationWindow = isolationWindowTargetMz) + ) + }) #' @rdname XcmsExperiment setMethod("processHistory", "XcmsExperiment", function(object, type) { diff --git a/R/XcmsExperimentHdf5-functions.R b/R/XcmsExperimentHdf5-functions.R index 7617f84c..3ab118d3 100644 --- a/R/XcmsExperimentHdf5-functions.R +++ b/R/XcmsExperimentHdf5-functions.R @@ -42,6 +42,11 @@ toXcmsExperiment <- function(object, ...) { .h5_to_xcms_experiment(object) } +#' @rdname XcmsExperimentHdf5 +XcmsExperimentHdf5 <- function() { + new("XcmsExperimentHdf5") +} + #' Coerce from XcmsExperimentHdf5 to XcmsExperiment #' #' @noRd @@ -499,6 +504,7 @@ toXcmsExperiment <- function(object, ...) { rt = numeric(), mz = numeric(), ppm = 0, type = "any", by_sample = TRUE) { if (length(columns)) { + columns <- columns[columns != "sample"] # not stored in HDF5 ## Get column names, convert column names to indices. cn <- .h5_chrom_peaks_colnames(x, msLevel = msLevel) idx_columns <- match(columns, cn) @@ -1104,7 +1110,7 @@ toXcmsExperiment <- function(object, ...) { return.type = "XChromatograms", BPPARAM = bpparam()) { message("Extracting chromatographic data") - chr <- as(.mse_chromatogram( + chr <- as(.mse_mchromatograms_for_ranges( as(x, "MsExperiment"), rt = rt, mz = mz, msLevel = ms_level, aggregationFun = aggregationFun, isolationWindow = isolationWindow, chunkSize = chunkSize, BPPARAM = BPPARAM), return.type) @@ -1186,6 +1192,82 @@ toXcmsExperiment <- function(object, ...) { chr } +#' Same concept as `.xmse_xchromatograms_for_features` in +#' *XcmsExperiment-functions.R* but using a different logic to extract +#' chromatographic peaks associated to the features (which is specific for the +#' `XcmsExperimentHdf5`). +#' +#' @noRd +.h5_xchromatograms_for_features <- function(x, expandRt = 0.0, expandMz = 0.0, + aggregationFun = "max", + features = character(), + mzmin = min, mzmax = max, + rtmin = min, rtmax = max, + chunkSize = 2L, ..., + progressbar = TRUE, + BPPARAM = bpparam()) { + chrs <- as(.xmse_mchromatograms_for_features( + x, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, mzmin = mzmin, + mzmax = mzmax, rtmin = rtmin, rtmax = rtmax, chunkSize = chunkSize, + progressbar = progressbar, BPPARAM = BPPARAM), "XChromatograms") + ## Populate with chrom peaks. + fts <- featureDefinitions(x)[fData(chrs)$feature_id, , drop = FALSE] + nf <- nrow(fts) + js <- seq_len(ncol(chrs)) + msl <- unique(fts$ms_level) + chr_mat <- chrs@.Data + slot(chrs, ".Data", check = FALSE) <- matrix( + nrow = nrow(chr_mat), ncol = ncol(chr_mat)) # clean memory + if (progressbar) { + message("Processing chromatographic peaks for features") + pb <- progress_bar$new(format = paste0("[:bar] :current/:", + "total (:percent) in ", + ":elapsed"), + total = length(js) + 1L, clear = FALSE) + } + for (j in js) { + for (ms in msl) { + fmap <- .h5_read_data( + x@hdf5_file, x@sample_id[j], + "feature_to_chrom_peaks", ms)[[1L]] + cp <- .h5_read_data( + x@hdf5_file, x@sample_id[j], "chrom_peaks", + ms, read_colnames = TRUE, read_rownames = TRUE)[[1L]] + cpd <- .h5_read_data( + x@hdf5_file, x@sample_id[j], "chrom_peak_data", + ms, read_colnames = TRUE, read_rownames = TRUE)[[1L]] + cpd$ms_level <- ms + cp_idx <- split(fmap[, 2L], fmap[, 1L]) + ft_idx <- which(fts$ms_level == ms) + for (i in seq_along(ft_idx)) { + slot(chr_mat[ft_idx[i], j][[1L]], + "chromPeaks", check = FALSE) <- + cp[cp_idx[[as.character(i)]], , drop = FALSE] + slot(chr_mat[ft_idx[i], j][[1L]], + "chromPeakData", check = FALSE) <- + as(cpd[cp_idx[[as.character(i)]], , drop = FALSE], + "DataFrame") + } + } + if (progressbar) + pb$tick() + } + slot(chrs, ".Data", check = FALSE) <- chr_mat + ## Each row is a SINGLE feature, thus we can use the "row" column to + ## match chrom peaks to features. + fts$row <- seq_len(nf) + pkrow <- unname(chromPeaks(chrs)[, c("row")]) + fts$peakidx <- unname(split(seq_along(pkrow), pkrow)) + colnames(chrs) <- basename(fileNames(x)) + rownames(chrs@phenoData) <- colnames(chrs) + slot(chrs, "featureDefinitions", check = FALSE) <- DataFrame(fts) + slot(chrs, ".processHistory", check = FALSE) <- x@processHistory + if (progressbar) + pb$tick() + chrs +} + ################################################################################ ## ## HDF5 FUNCTIONALITY @@ -1436,8 +1518,8 @@ toXcmsExperiment <- function(object, ...) { .h5_read_data <- function(h5_file = character(), id = character(), name = c("chrom_peaks", "chrom_peak_data", - "feature_definitions", - "feature_to_chrom_peaks"), + "feature_definitions", + "feature_to_chrom_peaks"), ms_level = integer(), read_colnames = FALSE, read_rownames = FALSE, diff --git a/R/XcmsExperimentHdf5.R b/R/XcmsExperimentHdf5.R index 4df65baf..f9a68950 100644 --- a/R/XcmsExperimentHdf5.R +++ b/R/XcmsExperimentHdf5.R @@ -119,12 +119,17 @@ #' #' @section Correspondence analysis results: #' +#' - `featureChromPeaks()`: get the mapping between features and +#' chromatographic peaks. See [featureChromPeaks()] for details. +#' #' - `featureDefinitions()`: similarly to `featureDefinitions()` for #' [XcmsExperiment] objects, this method returns a `data.frame` with the #' characteristics for the defined LC-MS features. The function for #' `XcmsExperimentHdf5` does however **not** return the `"peakidx"` column -#' with the indices of the chromatographic peaks per feature. Also, the -#' columns are returned in alphabetic order. +#' with the indices of the chromatographic peaks per feature. This +#' information can be extracted with the [featurePeakidx()] function. +#' Note: the columns of the data frame returned by `featureDefinitions()` are +#' in alphabetic order. #' #' - `featureValues()`: for parameter `value`, the option `value = "index"` #' (i.e. returning the index of the chromatographic peaks within the @@ -1099,6 +1104,41 @@ setMethod( ppm = ppm, type = type) }) +#' @rdname featureChromPeaks +setMethod("featureChromPeaks", "XcmsExperimentHdf5", + function(object, msLevel = integer()) { + if (!length(msLevel)) + msLevel <- object@features_ms_level + if (length(m <- msLevel[!msLevel %in% object@features_ms_level])) + stop("No features available for MS level(s) ", + paste0(m, collapse = ", "), call. = FALSE) + map <- do.call(rbind, lapply(msLevel, function(m) { + tmp <- .h5_read_data(object@hdf5_file, object@sample_id, + "feature_to_chrom_peak", + rep(m, length(object@sample_id))) + fid <- .h5_feature_definitions_rownames(object, m)[[1L]] + cid <- .h5_chrom_peaks_rownames(object, m) + do.call(rbind, mapply(tmp, cid, FUN = function(a, b) { + cbind(fid[a[, 1L]], b[a[, 2L]]) + })) + })) + colnames(map) <- c("feature_id", "chrom_peak_id") + fids <- unlist(.h5_feature_definitions_rownames(object, msLevel)) + as.data.frame( + map[order(match(map[, "feature_id"], fids)), , drop = FALSE]) + }) + +#' @rdname featureChromPeaks +setMethod("featurePeakidx", "XcmsExperimentHdf5", function(object, + msLevel = integer()){ + if (!length(msLevel)) + msLevel <- object@features_ms_level + map <- featureChromPeaks(object, msLevel) + pids <- unlist(.h5_chrom_peaks_rownames(object, msLevel), use.names = FALSE) + split(match(map$chrom_peak_id, pids), + factor(map$feature_id, levels = unique(map$feature_id))) +}) + #' @rdname hidden_aliases setMethod( "featureValues", "XcmsExperimentHdf5", @@ -1245,7 +1285,8 @@ setMethod( function(object, rt = matrix(nrow = 0, ncol = 2), mz = matrix(nrow = 0, ncol = 2), aggregationFun = "sum", msLevel = 1L, chunkSize = 2L, isolationWindowTargetMz = NULL, - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", + "Chromatograms"), include = character(), chromPeaks = c("apex_within", "any", "none"), BPPARAM = bpparam()) { @@ -1266,12 +1307,23 @@ setMethod( chromPeaks <- "none" if (hasAdjustedRtime(object)) object <- applyAdjustedRtime(object) - .h5_x_chromatograms( - object, ms_level = msLevel, chromPeaks = chromPeaks, - mz = mz, rt = rt, aggregationFun = aggregationFun, - chunkSize = chunkSize, return.type = return.type, - isolationWindow = isolationWindowTargetMz, - BPPARAM = BPPARAM) + switch(return.type, + MChromatograms = .h5_x_chromatograms( + object, ms_level = msLevel, chromPeaks = chromPeaks, + mz = mz, rt = rt, aggregationFun = aggregationFun, + chunkSize = chunkSize, return.type = return.type, + isolationWindow = isolationWindowTargetMz, + BPPARAM = BPPARAM), + XChromatograms = .h5_x_chromatograms( + object, ms_level = msLevel, chromPeaks = chromPeaks, + mz = mz, rt = rt, aggregationFun = aggregationFun, + chunkSize = chunkSize, return.type = return.type, + isolationWindow = isolationWindowTargetMz, + BPPARAM = BPPARAM), + Chromatograms = .mse_chromatograms_for_ranges( + object, rt = rt, mz = mz, aggregationFun = aggregationFun, + msLevel = msLevel, isolationWindow = isolationWindowTargetMz) + ) }) #' @rdname hidden_aliases @@ -1398,84 +1450,33 @@ setMethod( setMethod( "featureChromatograms", "XcmsExperimentHdf5", function(object, expandRt = 0, expandMz = 0, aggregationFun = "max", - features = character(), return.type = "XChromatograms", + features = character(), + return.type = c("XChromatograms","MChromatograms","Chromatograms"), chunkSize = 2L, mzmin = min, mzmax = max, rtmin = min, - rtmax = max, ..., progressbar = TRUE, BPPARAM = bpparam()) { + rtmax = max, featureArea = TRUE, ..., + progressbar = TRUE, BPPARAM = bpparam()) { return.type <- match.arg(return.type) if (hasAdjustedRtime(object)) object <- applyAdjustedRtime(object) - area <- featureArea(object, mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, - rtmax = rtmax, features = features) - if (expandRt != 0) { - area[, "rtmin"] <- area[, "rtmin"] - expandRt - area[, "rtmax"] <- area[, "rtmax"] + expandRt - } - if (expandMz != 0) { - area[, "mzmin"] <- area[, "mzmin"] - expandMz - area[, "mzmax"] <- area[, "mzmax"] + expandMz - } - fts <- featureDefinitions(object)[rownames(area), ] - chrs <- as(.mse_chromatogram( - as(object, "MsExperiment"), - rt = area[, c("rtmin", "rtmax"), drop = FALSE], - mz = area[, c("mzmin", "mzmax"), drop = FALSE], - aggregationFun = aggregationFun, msLevel = fts$ms_level, - chunkSize = chunkSize, progressbar = progressbar, - BPPARAM = BPPARAM), "XChromatograms") - ## Populate with chrom peaks. - nf <- nrow(fts) - js <- seq_len(ncol(chrs)) - msl <- unique(fts$ms_level) - chr_mat <- chrs@.Data - slot(chrs, ".Data", check = FALSE) <- matrix( - nrow = nrow(chr_mat), ncol = ncol(chr_mat)) # clean memory - if (progressbar) { - message("Processing chromatographic peaks for features") - pb <- progress_bar$new(format = paste0("[:bar] :current/:", - "total (:percent) in ", - ":elapsed"), - total = length(js) + 1L, clear = FALSE) - } - for (j in js) { - for (ms in msl) { - fmap <- .h5_read_data( - object@hdf5_file, object@sample_id[j], - "feature_to_chrom_peaks", ms)[[1L]] - cp <- .h5_read_data( - object@hdf5_file, object@sample_id[j], "chrom_peaks", - ms, read_colnames = TRUE, read_rownames = TRUE)[[1L]] - cpd <- .h5_read_data( - object@hdf5_file, object@sample_id[j], "chrom_peak_data", - ms, read_colnames = TRUE, read_rownames = TRUE)[[1L]] - cpd$ms_level <- ms - cp_idx <- split(fmap[, 2L], fmap[, 1L]) - ft_idx <- which(fts$ms_level == ms) - for (i in seq_along(ft_idx)) { - slot(chr_mat[ft_idx[i], j][[1L]], - "chromPeaks", check = FALSE) <- - cp[cp_idx[[as.character(i)]], , drop = FALSE] - slot(chr_mat[ft_idx[i], j][[1L]], - "chromPeakData", check = FALSE) <- - as(cpd[cp_idx[[as.character(i)]], , drop = FALSE], - "DataFrame") - } - } - if (progressbar) - pb$tick() - } - slot(chrs, ".Data", check = FALSE) <- chr_mat - ## Each row is a SINGLE feature, thus we can use the "row" column to - ## match chrom peaks to features. - fts$row <- seq_len(nf) - pkrow <- unname(chromPeaks(chrs)[, c("row")]) - fts$peakidx <- unname(split(seq_along(pkrow), pkrow)) - colnames(chrs) <- basename(fileNames(object)) - rownames(chrs@phenoData) <- colnames(chrs) - slot(chrs, "featureDefinitions", check = FALSE) <- DataFrame(fts) - slot(chrs, ".processHistory", check = FALSE) <- object@processHistory - if (progressbar) - pb$tick() - chrs + switch(return.type, + Chromatograms = .xmse_chromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + mzmin = mzmin, mzmax = mzmax, rtmin = rtmin, + rtmax = rtmax, featureArea = featureArea), + MChromatograms = .xmse_mchromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + chunkSize = chunkSize, mzmin = mzmin, mzmax = mzmax, + rtmin = rtmin, rtmax = rtmax, progressbar = progressbar, + BPPARAM = BPPARAM), + XChromatograms = .h5_xchromatograms_for_features( + object, expandRt = expandRt, expandMz = expandMz, + aggregationFun = aggregationFun, features = features, + chunkSize = chunkSize, mzmin = mzmin, mzmax = mzmax, + rtmin = rtmin, rtmax = rtmax, progressbar = progressbar, + BPPARAM = BPPARAM) + ) }) #' Helper method to update the retention times of the chrom peaks matrix diff --git a/R/functions-XCMSnExp.R b/R/functions-XCMSnExp.R index 544c121a..f2299a38 100644 --- a/R/functions-XCMSnExp.R +++ b/R/functions-XCMSnExp.R @@ -1713,7 +1713,8 @@ setMethod("hasFilledChromPeaks", "XCMSnExp", function(object) { #' @param x `matrix` with columns `"mzmin"` and `"mzmax"` or `"rtmin"` and #' `"rtmax"`. #' -#' @param min_col +#' @param min_col `character(1)` with the name of the column with the lower +#' range (e.g. `"mzmin"` or `"rtmin"`). #' #' @param max_col `character(1)` with the name of the column with the upper #' range (e.g. `"mzmax"` or `"rtmax"`). diff --git a/R/functions-imputation.R b/R/functions-imputation.R index 3475db21..85ef5349 100644 --- a/R/functions-imputation.R +++ b/R/functions-imputation.R @@ -26,7 +26,7 @@ #' library(faahKO) #' data("faahko") #' -#' xset <- group(faahko) +#' xset <- xcms::group(faahko) #' mat <- groupval(xset, value = "into") #' #' mat_imp <- imputeRowMin(mat) @@ -115,7 +115,7 @@ imputeRowMin <- function(x, min_fraction = 1/2) { #' library(MSnbase) #' data("faahko") #' -#' xset <- group(faahko) +#' xset <- xcms::group(faahko) #' mat <- groupval(xset, value = "into") #' #' ## Estimate the relationship between row sd and mean. The standard deviation diff --git a/R/loadXcmsData.R b/R/loadXcmsData.R index 1b5c8588..5d7932cd 100644 --- a/R/loadXcmsData.R +++ b/R/loadXcmsData.R @@ -56,6 +56,10 @@ loadXcmsData <- function(x = c("xmse", "xdata", "faahko_sub", "faahko_sub2")) { dirname(obj) <- c( rep(system.file("cdf", "KO", package = "faahKO"), 4), rep(system.file("cdf", "WT", package = "faahKO"), 4)) + obj@.processHistory <- lapply(obj@.processHistory, function(z) { + z@param <- updateObject(z@param) + z + }) obj }, "xmse" = { @@ -68,10 +72,18 @@ loadXcmsData <- function(x = c("xmse", "xdata", "faahko_sub", "faahko_sub2")) { if (anyNA(idx)) stop("Some of the original data files not found") obj@spectra$dataStorage <- fls[idx] + obj@processHistory <- lapply(obj@processHistory, function(z) { + z@param <- updateObject(z@param) + z + }) obj }, "faahko_sub" = { dirname(obj) <- system.file("cdf/KO", package = "faahKO") + obj@.processHistory <- lapply(obj@.processHistory, function(z) { + z@param <- updateObject(z@param) + z + }) obj }, "faahko_sub2" = { @@ -84,6 +96,10 @@ loadXcmsData <- function(x = c("xmse", "xdata", "faahko_sub", "faahko_sub2")) { if (anyNA(idx)) stop("Some of the original data files not found") obj@spectra$dataStorage <- fls[idx] + obj@processHistory <- lapply(obj@processHistory, function(z) { + z@param <- updateObject(z@param) + z + }) obj }) } diff --git a/R/methods-XCMSnExp.R b/R/methods-XCMSnExp.R index 23294a48..87c825de 100644 --- a/R/methods-XCMSnExp.R +++ b/R/methods-XCMSnExp.R @@ -1510,6 +1510,14 @@ setMethod("smooth", "XCMSnExp", function(x, method = c("SavitzkyGolay", #' @aliases setAs #' +#' @aliases coerce,XCMSnExp,xcmsSet-method +#' +#' @param from Original object. +#' +#' @param to `character(1)` defining the object to cast to. +#' +#' @param strict Ignored. +#' #' @rdname XCMSnExp-class #' #' @name XCMSnExp-class @@ -1517,6 +1525,12 @@ setAs(from = "XCMSnExp", to = "xcmsSet", def = .XCMSnExp2xcmsSet) #' @rdname XcmsExperiment #' +#' @param from Original object. +#' +#' @param to `character(1)` defining the object to cast to. +#' +#' @param strict Ignored. +#' #' @name XcmsExperiment setAs(from = "XcmsExperiment", to = "xcmsSet", def = .XCMSnExp2xcmsSet) @@ -3066,6 +3080,8 @@ setMethod("split", "XCMSnExp", function(x, f, #' @md #' #' @rdname XCMSnExp-class +#' +#' @export c.XCMSnExp <- function(...) { .concatenate_XCMSnExp(...) } diff --git a/R/methods-xcmsSet.R b/R/methods-xcmsSet.R index b38809a3..4e6ba88e 100644 --- a/R/methods-xcmsSet.R +++ b/R/methods-xcmsSet.R @@ -1169,7 +1169,7 @@ setMethod("fillPeaks.chrom", "xcmsSet", function(object, nSlaves = 0, if (FALSE) { library(xcms) library(faahKO) - object <- group(faahko) + object <- xcms::group(faahko) gf <- fillPeaks(object) pkgEnv = getNamespace("xcms") attach(pkgEnv) diff --git a/R/plotQC.R b/R/plotQC.R index dbc1adee..5d3b1920 100644 --- a/R/plotQC.R +++ b/R/plotQC.R @@ -36,7 +36,7 @@ #' #' @examples #' library(faahKO) -#' xsg <- group(faahko) +#' xsg <- xcms::group(faahko) #' #' plotQC(xsg, what="mzdevhist") #' plotQC(xsg, what="rtdevhist") diff --git a/R/writemztab.R b/R/writemztab.R index 8aa294b9..54bc93ba 100644 --- a/R/writemztab.R +++ b/R/writemztab.R @@ -167,7 +167,7 @@ if (FALSE) { library(faahKO) if(! exists("xs")) { - xs <- group(faahko) + xs <- xcms::group(faahko) } mzt <- data.frame(character(0)) diff --git a/longtests/testthat.R b/longtests/testthat.R index f7053a09..73296d63 100644 --- a/longtests/testthat.R +++ b/longtests/testthat.R @@ -27,7 +27,7 @@ faahko_xod <- findChromPeaks( faahko_xs <- xcmsSet(faahko_3_files, profparam = list(step = 0), method = "centWave", noise = 10000, snthresh = 40, prefilter = c(3, 10000)) -faahko_xsg <- group(faahko_xs) +faahko_xsg <- xcms::group(faahko_xs) ## Doing also the retention time correction etc od_x <- faahko_od mzr <- matrix(c(335, 335, 344, 344), ncol = 2, byrow = TRUE) @@ -43,9 +43,9 @@ xod_chr <- findChromPeaks(filterMz(filterRt(od_x, rt = c(2500, 3500)), mz = c(334.9, 344.1)), param = CentWaveParam()) -faahko_grouped_filled <- fillPeaks(group(faahko)) +faahko_grouped_filled <- fillPeaks(xcms::group(faahko)) faahko_grouped_retcor_filled <- - fillPeaks(group(retcor(group(updateObject(faahko))))) + fillPeaks(xcms::group(retcor(xcms::group(updateObject(faahko))))) ## Direct injection data: fticr <- readMSData(fticrf[1:2], msLevel. = 1, mode = "onDisk") diff --git a/longtests/testthat/test_do_adjustRtime-functions.R b/longtests/testthat/test_do_adjustRtime-functions.R index b5b6d428..32207bc3 100644 --- a/longtests/testthat/test_do_adjustRtime-functions.R +++ b/longtests/testthat/test_do_adjustRtime-functions.R @@ -17,7 +17,7 @@ test_that("getPeakGroupsRtMatrix works", { test_that("do_adjustRtime_peakGroups works", { xs <- faahko - xsg <- group(xs) + xsg <- xcms::group(xs) misSamp <- 1 xsa <- retcor(xsg, method = "peakgroups", missing = misSamp) minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) @@ -98,7 +98,7 @@ test_that("do_adjustRtime_peakGroups works", { test_that("applyRtAdjustment works", { xs <- faahko ## group em. - xsg <- group(xs) + xsg <- xcms::group(xs) ## align em. xsa <- retcor(xsg, method = "peakgroups") pksAdj <- .applyRtAdjToChromPeaks(peaks(xsg), diff --git a/longtests/testthat/test_do_groupChromPeaks-functions.R b/longtests/testthat/test_do_groupChromPeaks-functions.R index 04b5a665..7140f107 100644 --- a/longtests/testthat/test_do_groupChromPeaks-functions.R +++ b/longtests/testthat/test_do_groupChromPeaks-functions.R @@ -7,7 +7,7 @@ test_that("do_groupPeaks_mzClust works", { minFraction = 0, absMz = 2) expect_true(nrow(res$featureDefinitions) > nrow(res_2$featureDefinitions)) - res_x <- group(fticr_xs, method = "mzClust") + res_x <- xcms::group(fticr_xs, method = "mzClust") expect_equal(res_x@groups, res$featureDefinitions) expect_equal(res_x@groupidx, res$peakIndex) }) @@ -24,6 +24,6 @@ test_that("do_groupChromPeaks_nearest works", { res <- do_groupChromPeaks_nearest(features, sampleGroups) res_2 <- do_groupChromPeaks_nearest(features, sampleGroups, absRt = 3) expect_true(nrow(res$featureDefinitions) < nrow(res_2$featureDefinitions)) - res_x <- group(xs, method = "nearest") + res_x <- xcms::group(xs, method = "nearest") expect_equal(res_x@groups, res$featureDefinitions) }) diff --git a/longtests/testthat/test_methods-XCMSnExp.R b/longtests/testthat/test_methods-XCMSnExp.R index 34b0e4ff..b81b3b9c 100644 --- a/longtests/testthat/test_methods-XCMSnExp.R +++ b/longtests/testthat/test_methods-XCMSnExp.R @@ -19,7 +19,7 @@ test_that("XCMSnExp, XCMSnExp works", { test_that("featureValues,XCMSnExp works", { fdp <- PeakDensityParam(sampleGroups = faahko_xs$class) od_x <- groupChromPeaks(xod_x, param = fdp) - xs <- group(faahko_xs, method = "density") + xs <- xcms::group(faahko_xs, method = "density") fvs <- featureValues(od_x, value = "into") expect_equal(rownames(fvs), rownames(featureDefinitions(od_x))) rownames(fvs) <- NULL @@ -121,7 +121,7 @@ test_that("adjustRtime,peakGroups works", { xod <- faahko_xod xs <- faahko_xs ## Group these - xsg <- group(xs) + xsg <- xcms::group(xs) xodg <- groupChromPeaks(xod, param = PeakDensityParam(sampleGroups = xs$class)) pks <- chromPeaks(xodg) @@ -188,7 +188,7 @@ test_that("adjustRtime,peakGroups works", { type = .PROCSTEP.PEAK.GROUPING)) == 2) expect_true(hasAdjustedRtime(xodrg)) expect_true(hasFeatures(xodrg)) - xsrg <- group(xsr) + xsrg <- xcms::group(xsr) expect_equal(xsrg@groupidx, featureDefinitions(xodrg)$peakidx) ## Mod settings: @@ -268,7 +268,7 @@ test_that("featureValues,XCMSnExp works as with groupval", { p <- PeakDensityParam(sampleGroups = xs$class) od_x <- groupChromPeaks(od_x, param = p) - xs <- group(xs, method = "density") + xs <- xcms::group(xs, method = "density") expect_equal(unname(groupval(xs, value = "into")), unname(featureValues(od_x, value = "into"))) @@ -287,7 +287,7 @@ test_that("groupChromPeaks,XCMSnExp,PeakDensityParam works", { fdp <- PeakDensityParam(sampleGroups = xs$class) od_x <- groupChromPeaks(od_x, param = fdp) - xs <- group(xs, method = "density") + xs <- xcms::group(xs, method = "density") expect_equal(xs@groupidx, featureDefinitions(od_x)$peakidx) fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, !(colnames(fg) %in% c("peakidx", "ms_level"))]) @@ -302,7 +302,7 @@ test_that("groupChromPeaks,XCMSnExp,PeakDensityParam works", { fdp2 <- PeakDensityParam(sampleGroups = xs$class, binSize = 2, minFraction = 0.8) od_x <- groupChromPeaks(od_x, param = fdp2) - xs <- group(xs, method = "density", minfrac = 0.8, mzwid = 2) + xs <- xcms::group(xs, method = "density", minfrac = 0.8, mzwid = 2) expect_equal(xs@groupidx, featureDefinitions(od_x)$peakidx) fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, !(colnames(fg) %in% c("peakidx", "ms_level"))]) @@ -337,7 +337,7 @@ test_that("groupChromPeaks,XCMSnExp,PeakDensityParam works", { test_that("groupPeaks,XCMSnExp,MzClustParam works", { p <- MzClustParam(sampleGroups = sampclass(fticr_xs)) fticr_xod2 <- groupChromPeaks(fticr_xod, param = p) - fticr_xs2 <- group(fticr_xs, method = "mzClust") + fticr_xs2 <- xcms::group(fticr_xs, method = "mzClust") expect_equal(fticr_xs2@groupidx, featureDefinitions(fticr_xod2)$peakidx) fg <- featureDefinitions(fticr_xod2) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) @@ -352,7 +352,7 @@ test_that("groupPeaks,XCMSnExp,MzClustParam works", { p2 <- MzClustParam(sampleGroups = fticr_xs$class, absMz = 1, minFraction = 0.8) fticr_xod2 <- groupChromPeaks(fticr_xod, param = p2) - fticr_xs2 <- group(fticr_xs, method = "mzClust", minfrac = 0.8, mzabs = 1) + fticr_xs2 <- xcms::group(fticr_xs, method = "mzClust", minfrac = 0.8, mzabs = 1) expect_equal(fticr_xs2@groupidx, featureDefinitions(fticr_xod2)$peakidx) fg <- featureDefinitions(fticr_xod2) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) @@ -371,7 +371,7 @@ test_that("groupChromPeaks,XCMSnExp,NearestPeaksParam works", { xs <- faahko_xs p <- NearestPeaksParam(sampleGroups = xs$class) od_x <- groupChromPeaks(od_x, param = p) - xs <- group(xs, method = "nearest") + xs <- xcms::group(xs, method = "nearest") expect_equal(xs@groupidx, featureDefinitions(od_x)$peakidx) fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, !(colnames(fg) %in% c("peakidx", "ms_level"))]) @@ -384,7 +384,7 @@ test_that("groupChromPeaks,XCMSnExp,NearestPeaksParam works", { .featureIDs(nrow(featureDefinitions(od_x)))) fdp2 <- NearestPeaksParam(sampleGroups = xs$class, kNN = 3) od_x <- groupChromPeaks(od_x, param = fdp2) - xs <- group(xs, method = "nearest", kNN = 3) + xs <- xcms::group(xs, method = "nearest", kNN = 3) expect_equal(xs@groupidx, featureDefinitions(od_x)$peakidx) fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, !(colnames(fg) %in% c("peakidx", "ms_level"))]) @@ -422,7 +422,7 @@ test_that("fillChromPeaks,XCMSnExp with MSW works", { expect_true(!any(is.na(featureValues(res)))) ## 1) Compare with what I get for xcmsSet. tmp_x <- fticr_xs - tmp_x <- group(tmp_x, method = "mzClust") + tmp_x <- xcms::group(tmp_x, method = "mzClust") tmp_x <- fillPeaks(tmp_x, method = "MSW") ## Compare expect_equal(unname(groupval(tmp_x)), diff --git a/longtests/testthat/test_old_absentPresent.R b/longtests/testthat/test_old_absentPresent.R index aafa9794..04cd9765 100644 --- a/longtests/testthat/test_old_absentPresent.R +++ b/longtests/testthat/test_old_absentPresent.R @@ -1,5 +1,5 @@ test_that("present absent sum works", { - xsg <- group(faahko) + xsg <- xcms::group(faahko) a <- length(which(absent(xsg, class="WT", minfrac=0))) expect_equal(a, 407) p <- length(which(absent(xsg, class="KO", minfrac=0))) diff --git a/longtests/testthat/test_old_functions-xcmsSet.R b/longtests/testthat/test_old_functions-xcmsSet.R index fc83187a..9a8eb19f 100644 --- a/longtests/testthat/test_old_functions-xcmsSet.R +++ b/longtests/testthat/test_old_functions-xcmsSet.R @@ -66,7 +66,7 @@ test_that("phenoDataFromPaths and others don't fail", { ## https://stat.ethz.ch/pipermail/r-devel/2008-April/049184.html xs <- xcms::`phenoData<-`(xs, pd) - xsg <- group(xs) + xsg <- xmcs::group(xs) pd <- phenoDataFromPaths(files) xs <- faahko @@ -74,7 +74,7 @@ test_that("phenoDataFromPaths and others don't fail", { ##xcms::phenoData(xs) <- pd ## https://stat.ethz.ch/pipermail/r-devel/2008-April/049184.html xs <- xcms::`phenoData<-`(xs, pd) - xs <- group(xs) + xs <- xcms::group(xs) ## Setting the filepaths again; otherwise we will have problem finding these ## files ... obviously. filepaths(xs) <- files diff --git a/longtests/testthat/test_old_methods-IO.R b/longtests/testthat/test_old_methods-IO.R index 61fc7f4f..26fc88af 100644 --- a/longtests/testthat/test_old_methods-IO.R +++ b/longtests/testthat/test_old_methods-IO.R @@ -9,10 +9,9 @@ test_that("write.cdf,xcmsRaw works", { }) test_that("write.mzQuantML,xcmsSet works", { - xsg <- group(faahko) + xsg <- xcms::group(faahko) mzqFile <- paste(tempdir(), "faahKO.mzq.xml", sep="/") write.mzQuantML(xsg, mzqFile) v <- verify.mzQuantML(filename=mzqFile) - expect_true(v$status == "0") + expect_true(v$status == "0") }) - diff --git a/longtests/testthat/test_old_methods-xcmsSet.R b/longtests/testthat/test_old_methods-xcmsSet.R index 2c15ec98..7bdd757e 100644 --- a/longtests/testthat/test_old_methods-xcmsSet.R +++ b/longtests/testthat/test_old_methods-xcmsSet.R @@ -1,5 +1,5 @@ test_that("diffreport etc works", { - g <- group(faahko) + g <- xcms::group(faahko) f <- fillPeaks(g) d <- diffreport(f) ## Fake xcmsSet with 1 sample in class 1 @@ -24,15 +24,15 @@ test_that("findPeaks.MSW works", { }) test_that("fillPeaks,xcmsSet and filled flag works", { - xsg <- group(faahko) + xsg <- xcms::group(faahko) xsgf <- fillPeaks(xsg, method = "chrom") expect_equal(nrow(peaks(xsg)) + length(xsgf@filled), nrow(peaks(xsgf))) }) test_that("fillPeaks,xcmsSet columns works", { - xsg <- group(faahko) - xsg <- group(faahko_xs) + xsg <- xcms::group(faahko) + xsg <- xcms::group(faahko_xs) peaks(xsg) <- cbind(peaks(xsg), anotherColumn=4711) oldCnames <- colnames(peaks(xsg)) @@ -48,10 +48,10 @@ test_that("fillPeaks,xcmsSet columns works", { expect_equal(oldDims, newDims) ## Case where only some samples have NA values - xsg <- group(faahko_xs, minfrac=1) + xsg <- xcms::group(faahko_xs, minfrac=1) xsgf <- fillPeaks(xsg) # parallel disabled: , nSlaves=2) sampclass(xsgf) <- c(rep("KO", 1), rep("WT", 2)) - xsgf <- group(xsgf, minfrac=1) + xsgf <- xcms::group(xsgf, minfrac=1) xsgf <- fillPeaks(xsgf) # parallel disabled: , nSlaves=2) }) @@ -150,7 +150,7 @@ test_that("getXcmsRaw,xcmsSet works, issue #44", { xsetRaw <- xsetRaw[, 1:2] ## First sample is reference, i.e. no rt adjustment performed - xs <- retcor(group(xsetRaw), method = "obiwarp", center = 1) + xs <- retcor(xcms::group(xsetRaw), method = "obiwarp", center = 1) ## Second is corrected, first is center: expect_identical(xs@rt$raw[[1]], xs@rt$corrected[[1]]) expect_true(!all(xs@rt$raw[[2]] == xs@rt$corrected[[2]])) @@ -171,13 +171,13 @@ test_that("group,GroupDensity doesn't fail with OnePeak", { xs <- faahko p <- peaks(xs) peaks(xs) <- p[1, , drop = FALSE] - g <- group(xs, minsamp = 1, minfrac = 0.001, method = "density") + g <- xcms::group(xs, minsamp = 1, minfrac = 0.001, method = "density") }) test_that("group,xcmsSet Nearest works", { xs <- faahko p <- peaks(xs) - g <- group(xs, method="nearest") + g <- xcms::group(xs, method="nearest") expect_equal(range(unlist(g@groupidx))[1], 1) }) @@ -196,25 +196,25 @@ test_that("sampclass,xcmsSet works", { library(faahKO) xset <- faahko ## grouping the peaks - xset <- group(xset, method="density") + xset <- xcms::group(xset, method="density") ## reversing the order of the classes. xset.revorder <- xset sampclass(xset.revorder) <- c(rep("WT", 6), rep("KO", 6)) - xset.revorder <- group(xset.revorder, method="density") + xset.revorder <- xcms::group(xset.revorder, method="density") ## check if we get what we want: expect_equal(groups(xset)[, "KO"], groups(xset.revorder)[, "WT"]) ## repeat that but submitting already a factor xset.revorder.f <- xset sampclass(xset.revorder.f) <- factor(c(rep("WT", 6), rep("KO", 6))) - xset.revorder.f <- group(xset.revorder.f, method="density") + xset.revorder.f <- xcms::group(xset.revorder.f, method="density") expect_equal(groups(xset)[, "KO"], groups(xset.revorder.f)[, "WT"]) ## next: pheno data contains a column class with a factor. pd <- data.frame(class=factor(c(rep("WT", 6), rep("KO", 6)))) xset.pheno <- xset phenoData(xset.pheno) <- pd - xset.pheno <- group(xset.pheno, method="density") + xset.pheno <- xcms::group(xset.pheno, method="density") expect_equal(groups(xset)[, "KO"], groups(xset.pheno)[, "WT"]) ## next checking what happens if we submit a multi-column data.frame @@ -290,9 +290,9 @@ test_that("[,xcmsSet works", { ## performing a grouping, retention time correction and second grouping ##data(faahko, package="faahKO") - xset <- group(faahko, method="density") + xset <- xcms::group(faahko, method="density") xset <- retcor(xset, method="loess", family="symmetric") - xset <- group(xset) + xset <- xcms::group(xset) ##xset <- fillPeaks(xset) xsub <- xset[, idx] .compare(xset, xsub, idx) @@ -354,7 +354,7 @@ test_that("sampclass,xcmsSet works with unused groups", { levels(classes) <- c(levels(classes), "Leftover") xs <- faahko sampclass(xs) <- classes - xsg <- group(xs) + xsg <- xcms::group(xs) expect_equal(sampclass(xs), sampclass(xsg)) }) diff --git a/man/BlankFlag.Rd b/man/BlankFlag.Rd index 2434133b..78b73ac1 100644 --- a/man/BlankFlag.Rd +++ b/man/BlankFlag.Rd @@ -73,10 +73,10 @@ means that an extra column will be created in \code{featureDefinitions} or feature. } \seealso{ -Other Filter features in xcms: -\code{\link{DratioFilter}}, -\code{\link{PercentMissingFilter}}, -\code{\link{RsdFilter}} +Other Filter features in xcms: +\code{\link[=DratioFilter]{DratioFilter()}}, +\code{\link[=PercentMissingFilter]{PercentMissingFilter()}}, +\code{\link[=RsdFilter]{RsdFilter()}} } \author{ Philippine Louail diff --git a/man/DratioFilter.Rd b/man/DratioFilter.Rd index bb766873..d8096594 100644 --- a/man/DratioFilter.Rd +++ b/man/DratioFilter.Rd @@ -78,10 +78,10 @@ doi: \href{https://doi.org/10.1007/s11306-018-1367-3}{10.1007/s11306-018-1367-3} Epub 2018 May 18. PMID: 29805336; PMCID: PMC5960010. } \seealso{ -Other Filter features in xcms: -\code{\link{BlankFlag}}, -\code{\link{PercentMissingFilter}}, -\code{\link{RsdFilter}} +Other Filter features in xcms: +\code{\link[=BlankFlag]{BlankFlag()}}, +\code{\link[=PercentMissingFilter]{PercentMissingFilter()}}, +\code{\link[=RsdFilter]{RsdFilter()}} } \author{ Philippine Louail diff --git a/man/LamaParama.Rd b/man/LamaParama.Rd index 9e8c2757..8d1d88ba 100644 --- a/man/LamaParama.Rd +++ b/man/LamaParama.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/XcmsExperiment.R, R/do_adjustRtime-functions.R, -% R/functions-Params.R, R/methods-Params.R +% Please edit documentation in R/XcmsExperiment.R, +% R/do_adjustRtime-functions.R, R/functions-Params.R, R/methods-Params.R \name{adjustRtime,XcmsExperiment,LamaParama-method} \alias{adjustRtime,XcmsExperiment,LamaParama-method} \alias{LamaParama} @@ -49,7 +49,7 @@ LamaParama( adjustment using the \code{\link[=adjustRtime]{adjustRtime()}} function.} \item{BPPARAM}{For \code{matchLamasChromPeaks()}: parallel processing setup. -Defaults to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for +Defaults to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} \item{...}{For \code{plot()}: extra parameters to be passed to the function.} diff --git a/man/PercentMissingFilter.Rd b/man/PercentMissingFilter.Rd index cf7aa78f..2695826e 100644 --- a/man/PercentMissingFilter.Rd +++ b/man/PercentMissingFilter.Rd @@ -58,10 +58,10 @@ features for which the proportion of missing values is below (\code{<=}) the threshold in at least one sample group will be retained). } \seealso{ -Other Filter features in xcms: -\code{\link{BlankFlag}}, -\code{\link{DratioFilter}}, -\code{\link{RsdFilter}} +Other Filter features in xcms: +\code{\link[=BlankFlag]{BlankFlag()}}, +\code{\link[=DratioFilter]{DratioFilter()}}, +\code{\link[=RsdFilter]{RsdFilter()}} } \author{ Philippine Louail diff --git a/man/RsdFilter.Rd b/man/RsdFilter.Rd index 3e875cd7..2328333e 100644 --- a/man/RsdFilter.Rd +++ b/man/RsdFilter.Rd @@ -64,10 +64,10 @@ log scale should be first transformed to natural scale before calculating the RSD. } \seealso{ -Other Filter features in xcms: -\code{\link{BlankFlag}}, -\code{\link{DratioFilter}}, -\code{\link{PercentMissingFilter}} +Other Filter features in xcms: +\code{\link[=BlankFlag]{BlankFlag()}}, +\code{\link[=DratioFilter]{DratioFilter()}}, +\code{\link[=PercentMissingFilter]{PercentMissingFilter()}} } \author{ Philippine Louail diff --git a/man/XCMSnExp-class.Rd b/man/XCMSnExp-class.Rd index 3d1921b6..16f709c4 100644 --- a/man/XCMSnExp-class.Rd +++ b/man/XCMSnExp-class.Rd @@ -43,6 +43,7 @@ \alias{dropAdjustedRtime,XCMSnExp-method} \alias{dropAdjustedRtime} \alias{setAs} +\alias{coerce,XCMSnExp,xcmsSet-method} \alias{profMat,XCMSnExp-method} \alias{findChromPeaks,XCMSnExp,Param-method} \alias{dropFilledChromPeaks,XCMSnExp-method} @@ -126,6 +127,8 @@ processHistoryTypes() \S4method{dropAdjustedRtime}{XCMSnExp}(object) +\S4method{coerce}{XCMSnExp,xcmsSet}(from, to = "xcmsSet", strict = TRUE) + \S4method{profMat}{XCMSnExp}( object, method = "bin", @@ -238,7 +241,7 @@ is included in the returned "matrix"\verb{providing the information if a peak wa retention times reported in the files) should be returned.} \item{BPPARAM}{Parameter class for parallel processing. See -\code{\link[BiocParallel:register]{BiocParallel::bpparam()}}.} +\code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}.} \item{keepAdjustedRtime}{For \verb{dropFeatureDefinitions,XCMSnExp()}: \code{logical(1)} defining whether eventually present retention time @@ -252,6 +255,12 @@ chromatographic peaks removes all process history steps related to peak grouping. Setting e.g. \code{dropLastN = 1} will only remove the most recent peak grouping related process history step.} +\item{from}{Original object.} + +\item{to}{\code{character(1)} defining the object to cast to.} + +\item{strict}{Ignored.} + \item{param}{A \code{\link[=CentWaveParam]{CentWaveParam()}}, \code{\link[=MatchedFilterParam]{MatchedFilterParam()}}, \code{\link[=MassifquantParam]{MassifquantParam()}}, \code{\link[=MSWParam]{MSWParam()}} or \code{\link[=CentWavePredIsoParam]{CentWavePredIsoParam()}} object with the settings for the @@ -365,7 +374,7 @@ Along with the results, the object contains the processing history that allows to track each processing step along with the used settings. This can be extracted with the \code{\link[=processHistory]{processHistory()}} function. \code{XCMSnExp} objects, by directly extending the -\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp} object from the \emph{MSnbase} package, inherit +\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp} object from the \emph{MSnbase} package, inherit all of its functionality and allows thus an easy access to the full raw data at any stage of an analysis. To support interaction with packages requiring the \emph{old} objects, @@ -546,7 +555,7 @@ results. If no function is specified the function simply returns the combines identified chromatographic peaks and the objects' pheno data but discards alignment results or feature definitions. -\code{plot()} plots the spectrum data (see \code{\link[MSnbase:plot-methods]{MSnbase::plot()}} for +\code{plot()} plots the spectrum data (see \code{\link[MSnbase:plot]{MSnbase::plot()}} for \code{MSnExp} objects in the \emph{MSnbase} package for more details. For \code{type = "XIC"}, identified chromatographic peaks will be indicated as rectangles with border color \code{peakCol}. @@ -636,7 +645,7 @@ features (see respective help page). in the m/z - rt space (see respective help page). \item \code{\link[=quantify]{quantify()}}: extract feature intensities and put them, along with feature definitions and phenodata information, into a -\code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment::SummarizedExperiment()}}. See help page for details. +\code{\link[SummarizedExperiment:SummarizedExperiment]{SummarizedExperiment::SummarizedExperiment()}}. See help page for details. } } @@ -710,8 +719,8 @@ xs <- as(faahko_sub, "xcmsSet") head(peaks(xs)) } \seealso{ -\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp}, -and \link[MSnbase:pSet-class]{MSnbase::pSet} for a complete list of inherited methods. +\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp}, +and \link[MSnbase:pSet]{MSnbase::pSet} for a complete list of inherited methods. \if{html}{\out{
}}\preformatted{[findChromPeaks()] for available peak detection methods returning a `XCMSnExp` object as a result. diff --git a/man/XCMSnExp-filter-methods.Rd b/man/XCMSnExp-filter-methods.Rd index f7cfa344..293b80d9 100644 --- a/man/XCMSnExp-filter-methods.Rd +++ b/man/XCMSnExp-filter-methods.Rd @@ -109,7 +109,7 @@ All methods return an \link{XCMSnExp} object. } \description{ The methods listed on this page allow to filter and subset \link{XCMSnExp} -objects. Most of them are inherited from the \link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp} object +objects. Most of them are inherited from the \link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp} object defined in the \emph{MSnbase} package and have been adapted for \code{XCMSnExp} to enable correct subsetting of preprocessing results. \itemize{ diff --git a/man/XCMSnExp-inherited-methods.Rd b/man/XCMSnExp-inherited-methods.Rd index dc2cf43f..26cc43f5 100644 --- a/man/XCMSnExp-inherited-methods.Rd +++ b/man/XCMSnExp-inherited-methods.Rd @@ -37,7 +37,7 @@ ) } \arguments{ -\item{x}{\code{\link[=XCMSnExp]{XCMSnExp()}} or \code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} +\item{x}{\code{\link[=XCMSnExp]{XCMSnExp()}} or \code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} object.} \item{binSize}{\code{numeric(1)} defining the size of a bin (in Dalton).} @@ -65,12 +65,12 @@ sub-setted.} object by file.} \item{method}{For \code{normalize()}: \code{character(1)} specifying the -normalization method. See \code{\link[MSnbase:normalise-methods]{MSnbase::normalize()}} in the \emph{MSnbase} +normalization method. See \code{\link[MSnbase:normalize]{MSnbase::normalize()}} in the \emph{MSnbase} package for details. For \code{pickPeaks()}: \code{character(1)} defining the method. See help for \code{pickPeaks()} in the \emph{MSnbase} package for options. For \code{smooth()}: \code{character(1)} defining the method. See -\code{\link[MSnbase:smooth-methods]{MSnbase::smooth()}} in the \emph{MSnbase} package for options and +\code{\link[MSnbase:smooth]{MSnbase::smooth()}} in the \emph{MSnbase} package for options and details.} \item{...}{Optional additional arguments.} @@ -86,7 +86,7 @@ in the \emph{MSnbase} package for details.} \item{t}{For \code{removePeaks()}: either a \code{numeric(1)} or \code{"min"} defining the threshold (method) to be used. See -\code{\link[MSnbase:removePeaks-methods]{MSnbase::removePeaks()}} for details.} +\code{\link[MSnbase:removePeaks]{MSnbase::removePeaks()}} for details.} } \value{ For all methods: a \code{XCMSnExp} object. @@ -94,26 +94,26 @@ For all methods: a \code{XCMSnExp} object. \description{ The methods listed on this page are \code{\link[=XCMSnExp]{XCMSnExp()}} methods inherited from its parent, the -\code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} class from the \emph{MSnbase} +\code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} class from the \emph{MSnbase} package, that alter the raw data or are related to data subsetting. Thus calling any of these methods causes all \emph{xcms} pre-processing results to be removed from the \code{\link[=XCMSnExp]{XCMSnExp()}} object to ensure its data integrity. \code{bin()}: allows to \emph{bin} spectra. See -\code{\link[MSnbase:bin-methods]{MSnbase::bin()}} documentation in the \emph{MSnbase} package for more +\code{\link[MSnbase:bin]{MSnbase::bin()}} documentation in the \emph{MSnbase} package for more details and examples. \code{clean()}: removes unused \code{0} intensity data -points. See \code{\link[MSnbase:clean-methods]{MSnbase::clean()}} documentation in the \emph{MSnbase} package +points. See \code{\link[MSnbase:clean]{MSnbase::clean()}} documentation in the \emph{MSnbase} package for details and examples. \code{filterAcquisitionNum()}: filters the \code{\link[=XCMSnExp]{XCMSnExp()}} object keeping only spectra with the provided acquisition numbers. See -\code{\link[MSnbase:MSnExp-class]{MSnbase::filterAcquisitionNum()}} for details and examples. +\code{\link[MSnbase:filterAcquisitionNum]{MSnbase::filterAcquisitionNum()}} for details and examples. The \code{normalize()} method performs basic normalization of -spectra intensities. See \code{\link[MSnbase:normalise-methods]{MSnbase::normalize()}} documentation +spectra intensities. See \code{\link[MSnbase:normalize]{MSnbase::normalize()}} documentation in the \emph{MSnbase} package for details and examples. The \code{pickPeaks()} method performs peak picking. See documentation for @@ -123,18 +123,18 @@ The \code{removePeaks()} method removes mass peaks (intensities) lower than a threshold. Note that these peaks refer to \emph{mass} peaks, which are different to the chromatographic peaks detected and analyzed in a metabolomics experiment! See -\code{\link[MSnbase:removePeaks-methods]{MSnbase::removePeaks()}} documentation for details and +\code{\link[MSnbase:removePeaks]{MSnbase::removePeaks()}} documentation for details and examples. The \code{smooth()} method smooths spectra. See -\code{\link[MSnbase:smooth-methods]{MSnbase::smooth()}} documentation in \emph{MSnbase} for details and +\code{\link[MSnbase:smooth]{MSnbase::smooth()}} documentation in \emph{MSnbase} for details and examples. } \seealso{ \link{XCMSnExp-filter} for methods to filter and subset \code{XCMSnExp} objects. \code{\link[=XCMSnExp]{XCMSnExp()}} for base class documentation. -\code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} for the documentation of the +\code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} for the documentation of the parent class. } \author{ diff --git a/man/XCMSnExp-peak-grouping-results.Rd b/man/XCMSnExp-peak-grouping-results.Rd index 38a11bb7..99887941 100644 --- a/man/XCMSnExp-peak-grouping-results.Rd +++ b/man/XCMSnExp-peak-grouping-results.Rd @@ -68,7 +68,7 @@ of the features matches the order found in the \code{DataFrame}. \code{NA} is reported for features without corresponding chromatographic peak in the respective sample(s). -For \code{quantify()}: a \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment::SummarizedExperiment()}} +For \code{quantify()}: a \code{\link[SummarizedExperiment:SummarizedExperiment]{SummarizedExperiment::SummarizedExperiment()}} representing the preprocessing results. } \description{ @@ -84,7 +84,7 @@ values should be returned (given that features have been defined for that MS level). \verb{quantify,XCMSnExp()}: return the preprocessing results as an -\code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment::SummarizedExperiment()}} object containing the +\code{\link[SummarizedExperiment:SummarizedExperiment]{SummarizedExperiment::SummarizedExperiment()}} object containing the feature abundances as assay matrix, the feature definitions (returned by \code{\link[=featureDefinitions]{featureDefinitions()}}) as \code{rowData} and the phenotype information as \code{colData}. This is an ideal container for further diff --git a/man/XChromatogram.Rd b/man/XChromatogram.Rd index f38a0fe3..f75aa999 100644 --- a/man/XChromatogram.Rd +++ b/man/XChromatogram.Rd @@ -377,10 +377,10 @@ See help of the individual functions. The \code{XChromatogram} object allows to store chromatographic data (e.g. an extracted ion chromatogram) along with identified chromatographic peaks within that data. The object inherits all functions from the -\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} object in the \code{MSnbase} package. +\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} object in the \code{MSnbase} package. Multiple \code{XChromatogram} objects can be stored in a \code{XChromatograms} object. -This class extends \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} from the \code{MSnbase} package +This class extends \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} from the \code{MSnbase} package and allows thus to arrange chromatograms in a matrix-like structure, columns representing samples and rows m/z-retention time ranges. @@ -401,7 +401,7 @@ used to extract the chromatogram was larger than the peak's m/z. Objects can be created with the contructor function \code{XChromatogram} and \code{XChromatograms}, respectively. Also, they can be coerced from -\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} objects using +\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} objects using \code{as(object, "XChromatogram")} or \code{as(object, "XChromatograms")}. } @@ -409,7 +409,7 @@ Objects can be created with the contructor function \code{XChromatogram} and Besides classical subsetting with \code{[} specific filter operations on -\code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} and \code{XChromatograms} objects are available. See +\code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} and \code{XChromatograms} objects are available. See \code{\link[=filterColumnsIntensityAbove]{filterColumnsIntensityAbove()}} for more details. @@ -436,7 +436,7 @@ returns a filtered \code{XChromatogram} or \code{XChromatograms} object. \section{Accessing data}{ -See also help of \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} in the \emph{MSnbase} package for +See also help of \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} in the \emph{MSnbase} package for general information and data access. The methods listed here are specific for \code{XChromatogram} and \code{XChromatograms} objects. \itemize{ @@ -458,7 +458,7 @@ For \code{XChromatograms} objects the \code{matrix} contains also columns \code{ and \code{"column"} specifying in which chromatogram of \code{object} the peak was identified. Chromatographic peaks are ordered by row. \item \code{chromPeakData}, \verb{chromPeakData<-}: extract or set the -\code{\link[S4Vectors:DataFrame-class]{S4Vectors::DataFrame()}} with optional chromatographic peak annotations. +\code{\link[S4Vectors:DataFrame]{S4Vectors::DataFrame()}} with optional chromatographic peak annotations. \item \code{hasChromPeaks}: infer whether a \code{XChromatogram} (or \code{XChromatograms}) has chromatographic peaks. For \code{XChromatogram}: returns a \code{logical(1)}, for \code{XChromatograms}: returns a \code{matrix}, same dimensions than \code{object} @@ -517,7 +517,7 @@ the individual performed processing steps. Optional parameters \code{type} and \itemize{ \item \code{transformIntensity}: transforms the intensity values of the chromatograms -with provided function \code{FUN}. See \code{\link[MSnbase:Chromatogram-class]{MSnbase::transformIntensity()}} in the +with provided function \code{FUN}. See \code{\link[MSnbase:transformIntensity]{MSnbase::transformIntensity()}} in the \emph{MSnbase} package for details. For \code{XChromatogram} and \code{XChromatograms} in addition to the intensity values also columns \code{"into"} and \code{"maxo"} in the object's \code{chromPeaks} matrix are transformed by the same function. @@ -739,7 +739,7 @@ plot(xchr_sub) } \seealso{ \link[=findChromPeaks-Chromatogram-CentWaveParam]{findChromPeaks-centWave} for peak -detection on \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} objects. +detection on \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} objects. } \author{ Johannes Rainer diff --git a/man/XcmsExperiment.Rd b/man/XcmsExperiment.Rd index d3952afa..621e736f 100644 --- a/man/XcmsExperiment.Rd +++ b/man/XcmsExperiment.Rd @@ -21,6 +21,9 @@ \alias{filterChromPeaks} \alias{featureArea} \alias{quantify} +\alias{coerce,XcmsExperiment,xcmsSet-method} +\alias{coerce,XcmsExperiment,XCMSnExp-method} +\alias{coerce,XCMSnExp,XcmsExperiment-method} \alias{c.XcmsExperiment} \alias{[,XcmsExperiment,ANY,ANY,ANY-method} \alias{filterIsolationWindow,XcmsExperiment-method} @@ -85,7 +88,7 @@ filterFeatureDefinitions(object, ...) msLevel = 1L, isolationWindowTargetMz = NULL, chunkSize = 2L, - return.type = "MChromatograms", + return.type = c("MChromatograms", "Chromatograms"), BPPARAM = bpparam() ) @@ -195,7 +198,7 @@ filterFeatureDefinitions(object, ...) msLevel = 1L, chunkSize = 2L, isolationWindowTargetMz = NULL, - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", "Chromatograms"), include = character(), chromPeaks = c("apex_within", "any", "none"), BPPARAM = bpparam() @@ -210,6 +213,12 @@ filterFeatureDefinitions(object, ...) keepFeatures = FALSE, ... ) + +\S4method{coerce}{XcmsExperiment,xcmsSet}(from, to = "xcmsSet", strict = TRUE) + +\S4method{coerce}{XcmsExperiment,XCMSnExp}(from, to = "XCMSnExp", strict = TRUE) + +\S4method{coerce}{XCMSnExp,XcmsExperiment}(from, to = "XcmsExperiment", strict = TRUE) } \arguments{ \item{object}{An \code{XcmsExperiment} object.} @@ -274,11 +283,15 @@ Defaults to \code{chunkSize = 2L}.} \item{return.type}{For \code{chromPeakData()}: \code{character(1)} defining the class of the returned object. Can be either \code{"DataFrame"} (the default) or \code{"data.frame"}. For \code{chromatogram()}: \code{character(1)} defining the -type of the returned object. Currently only -\code{return.type = "MChromatograms"} is supported.} +type of the returned object. For \code{MsExperiment} objects +\code{return.type = "MChromatograms"} (the default) and +\code{return.type = "Chromatograms"} allows to return a +\link[MSnbase:MChromatograms]{MSnbase::MChromatograms} or a \code{\link[Chromatograms:Chromatograms]{Chromatograms::Chromatograms()}} object, +for \code{XcmsExperiment} also \code{return.type = "XChromatogram"} is supported +which returns the chromatographic data as a \link{XChromatograms} object.} \item{BPPARAM}{For \code{chromatogram()}: parallel processing setup. Defaults -to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for more +to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} \item{x}{An \code{XcmsExperiment} object.} @@ -415,6 +428,12 @@ also parameter \code{type} below for additional information.} \item{keepFeatures}{for most subsetting functions (\code{[}, \code{filterFile()}): \code{logical(1)}: wheter eventually present feature definitions should be retained in the returned (filtered) object.} + +\item{from}{Original object.} + +\item{to}{\code{character(1)} defining the object to cast to.} + +\item{strict}{Ignored.} } \description{ The \code{XcmsExperiment} is a data container for \emph{xcms} preprocessing @@ -534,29 +553,33 @@ performed on \strong{all} MS levels of the object. extract the data from (to e.g. for extracted ion chromatograms EICs). Both parameters are expected to be numerical two-column matrices with the first column defining the lower and the second the upper margin. -Each row can define a separate m/z - retention time region. Currently -the function returns a \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object for \code{object} -being a \code{MsExperiment} or, for \code{object} being an \code{XcmsExperiment}, -either a \code{MChromatograms} or \code{\link[=XChromatograms]{XChromatograms()}} depending on parameter -\code{return.type} (can be either \code{"MChromatograms"} or \code{"XChromatograms"}). -For the latter also chromatographic peaks detected within the provided -m/z and retention times are returned. Parameter \code{chromPeaks} allows +Each row can define a separate m/z - retention time region. + +The chromatographic data can be returned either as an +\link[MSnbase:MChromatograms]{MSnbase::MChromatograms} object (parameter +\code{return.type = "MChromatograms"}, the default) or as the newer +\code{\link[Chromatograms:Chromatograms]{Chromatograms::Chromatograms()}} container +(\code{return.type = "Chromatograms"}). If \code{object} is an \emph{xcms} result object +(\code{XcmsExperiment}), the default is to return a \code{\link[=XChromatograms]{XChromatograms()}} object +that contains also chromatographic peak and feature information. For +\code{XChromatograms} return type, the \code{chromPeaks} parameter allows to specify which chromatographic peaks should be reported. See documentation on the \code{chromPeaks} parameter for more information. If the \code{XcmsExperiment} contains correspondence results, also the associated feature definitions will be included in the returned -\code{XChromatograms}. By default the function returns chromatograms from MS1 -data, but by setting parameter \code{msLevel = 2L} it is possible to e.g. -extract also MS2 chromatograms. By default, with parameter -\code{isolationWindowTargetMz = NULL} or \code{isolationWindowTargetMz = NA_real_}, -data from \strong{all} MS2 spectra will be considered in the chromatogram -extraction. If MS2 data was generated within different m/z isolation -windows (such as e.g. with Scies SWATH data), the parameter -\code{isolationWindowTargetMz} should be used to ensure signal is only extracted -from the respective isolation window. The \code{isolationWindowTargetMz()} -function on the \code{Spectra} object can be used to inspect/list available -isolation windows of a data set. See also the xcms \emph{LC-MS/MS vignette} for -examples and details. +\code{XChromatograms}. + +By default the function returns chromatograms from MS level 1, but by +setting parameter \code{msLevel = 2L} it is possible to extract MS2 +chromatograms. By default, with parameter \code{isolationWindowTargetMz = NULL} +or \code{isolationWindowTargetMz = NA_real_}, data from \strong{all} MS2 spectra +will be considered in the chromatogram extraction. If MS2 data was +generated within different m/z isolation windows (such as e.g. with +Sciex SWATH data), the parameter \code{isolationWindowTargetMz} should be used +to ensure signal is only extracted from the specified isolation window. +The \code{\link[Spectra:isolationWindowTargetMz]{Spectra::isolationWindowTargetMz()}} function on the \code{Spectra} object +can be used to inspect/list available isolation windows of a data set. +See also the xcms \emph{LC-MS/MS vignette} for examples and details. \item \code{chromPeaks()}: returns a \code{numeric} matrix with the identified chromatographic peaks. Each row represents a chromatographic peak identified in one sample (file). The number of columns depends on the @@ -669,12 +692,17 @@ all chromatographic peaks assigned to that feature. Parameter \code{minMzWidthPpm} (default \verb{minMzWidthPpm = 0.01) can be used to define a minimal required (total) m/z width expressed in ppm of the features' m/z. With a }minMzWidthPpm\verb{larger than 0 the reported}"mzmin"\verb{is the minimum of the determined minimal m/z for a feature (based on parameter}mzmin\verb{) and the m/z of the feature minus }minMzWidthPpm / 2\verb{ppm of the feature's m/z value. The reported}"mzmax"\verb{is calculated in the same way. Parameter}features\verb{allows to extract these values for selected features only. Parameters}mzmin\verb{, }mzmax\verb{, }rtmin\code{and}rtmax\verb{allow to define the function to calculate the reported}"mzmin"\verb{, }"mzmax"\verb{, }"rtmin"\code{and}"rtmax"` values. \item \code{featureChromatograms()}: extract ion chromatograms (EICs) for each feature in \code{object}. See \code{\link[=featureChromatograms]{featureChromatograms()}} for more details. +\item \code{featureChromPeaks()}: get the mapping between features and chromatographic +peaks. See \code{\link[=featureChromPeaks]{featureChromPeaks()}} for details. \item \code{featureDefinitions()}: returns a \code{data.frame} with feature definitions or an empty \code{data.frame} if no correspondence analysis results are present. Parameters \code{msLevel}, \code{mz}, \code{ppm} and \code{rt} allow to define subsets of feature definitions that should be returned with the parameter \code{type} defining how these parameters should be used to subset the returned \code{data.frame}. See parameter descriptions for details. +\item \code{featurePeakidx()}: get the indices of chromatographic peaks in the +\code{chromPeaks()} matrix assigned to each feature. See \code{\link[=featurePeakidx]{featurePeakidx()}} for +details. \item \code{featureSpectra()}: returns a \code{\link[Spectra:Spectra]{Spectra::Spectra()}} or \code{List} of \code{Spectra} with (MS1 or MS2) spectra associated to each feature's chromatographic peaks. See \code{\link[=featureSpectra]{featureSpectra()}} for more details and available parameters. @@ -719,7 +747,7 @@ to define the column in \code{chromPeaks} that should be selected; defaults to \verb{intensity = "into"). }method = "sum"`: sum the values for all chromatographic peaks assigned to the feature in the same sample. \item \code{quantify()}: extract the correspondence analysis results as a -\code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment::SummarizedExperiment()}}. The feature \emph{values} +\code{\link[SummarizedExperiment:SummarizedExperiment]{SummarizedExperiment::SummarizedExperiment()}}. The feature \emph{values} are used as \code{assay} in the returned \code{SummarizedExperiment}, \code{rowData} contains the \code{featureDefinitions} (without column \code{"peakidx"}) and \code{colData} the \code{sampleData} of \code{object}. Additional parameters to the @@ -873,6 +901,26 @@ chrs ## Plot the EICs for the second defined region plot(chrs[2, ]) +## Extract chromatographic data for the first two chromatographic peaks +## as the new `Chromatograms` object. +chrs <- chromatogram(xmse, + mz = chromPeaks(xmse)[1:2, c("mzmin", "mzmax")], + rt = chromPeaks(xmse)[1:2, c("rtmin", "rtmax")], + return.type = "Chromatograms") +chrs + +## Get the intensity values from each chromatogram +intensity(chrs) + +## Plot all EICs into a single plot +Chromatograms::plotChromatogramsOverlay(chrs) + +## Plot the first EIC on the 3 files +Chromatograms::plotChromatogramsOverlay(chrs[1:3]) + +## Plot the second EIC on the 3 files +Chromatograms::plotChromatogramsOverlay(chrs[4:6]) + ## Subsetting the data to the results (and data) for the second sample a <- xmse[2] nrow(chromPeaks(xmse)) diff --git a/man/XcmsExperimentHdf5.Rd b/man/XcmsExperimentHdf5.Rd index 419ddfe8..5085ed55 100644 --- a/man/XcmsExperimentHdf5.Rd +++ b/man/XcmsExperimentHdf5.Rd @@ -16,6 +16,8 @@ toXcmsExperimentHdf5(object, hdf5File = tempfile()) toXcmsExperiment(object, ...) +XcmsExperimentHdf5() + \S4method{chromPeakData}{XcmsExperimentHdf5}( object, msLevel = integer(), @@ -210,12 +212,16 @@ parameter. \section{Correspondence analysis results}{ \itemize{ +\item \code{featureChromPeaks()}: get the mapping between features and +chromatographic peaks. See \code{\link[=featureChromPeaks]{featureChromPeaks()}} for details. \item \code{featureDefinitions()}: similarly to \code{featureDefinitions()} for \link{XcmsExperiment} objects, this method returns a \code{data.frame} with the characteristics for the defined LC-MS features. The function for \code{XcmsExperimentHdf5} does however \strong{not} return the \code{"peakidx"} column -with the indices of the chromatographic peaks per feature. Also, the -columns are returned in alphabetic order. +with the indices of the chromatographic peaks per feature. This +information can be extracted with the \code{\link[=featurePeakidx]{featurePeakidx()}} function. +Note: the columns of the data frame returned by \code{featureDefinitions()} are +in alphabetic order. \item \code{featureValues()}: for parameter \code{value}, the option \code{value = "index"} (i.e. returning the index of the chromatographic peaks within the \code{chromPeaks()} matrix per feature) is \strong{not} supported. diff --git a/man/adjustRtime.Rd b/man/adjustRtime.Rd index 0c87a5f3..3164a7a8 100644 --- a/man/adjustRtime.Rd +++ b/man/adjustRtime.Rd @@ -59,7 +59,7 @@ ObiwarpParam( \S4method{adjustRtime}{XCMSnExp,ObiwarpParam}(object, param, msLevel = 1L) } \arguments{ -\item{object}{For \code{adjustRtime}: an \code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}}, \code{\link[=XCMSnExp]{XCMSnExp()}}, +\item{object}{For \code{adjustRtime}: an \code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}}, \code{\link[=XCMSnExp]{XCMSnExp()}}, \code{\link[MsExperiment:MsExperiment]{MsExperiment::MsExperiment()}} or \code{\link[=XcmsExperiment]{XcmsExperiment()}} object.} \item{param}{The parameter object defining the alignment method (and its @@ -81,7 +81,7 @@ the total number of samples in an experiment will load the full MS data into memory and will thus in most settings cause an out-of-memory error.} \item{BPPARAM}{parallel processing setup. Defaults to \code{BPPARAM = bpparam()}. -See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for details.} +See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for details.} \item{msLevel}{For \code{adjustRtime}: \code{integer(1)} defining the MS level on which the alignment should be performed.} diff --git a/man/breaks_on_binSize.Rd b/man/breaks_on_binSize.Rd index 18985bfd..81fe7052 100644 --- a/man/breaks_on_binSize.Rd +++ b/man/breaks_on_binSize.Rd @@ -49,8 +49,8 @@ seq(1, 10, by = 0.51) \seealso{ \code{\link[=binYonX]{binYonX()}} for a binning function. -Other functions to define bins: -\code{\link{breaks_on_nBins}()} +Other functions to define bins: +\code{\link[=breaks_on_nBins]{breaks_on_nBins()}} } \author{ Johannes Rainer diff --git a/man/breaks_on_nBins.Rd b/man/breaks_on_nBins.Rd index 992f3858..e068a83d 100644 --- a/man/breaks_on_nBins.Rd +++ b/man/breaks_on_nBins.Rd @@ -40,8 +40,8 @@ breaks_on_nBins(3, 20, nBins = 20, shiftByHalfBinSize = TRUE) \seealso{ \code{\link[=binYonX]{binYonX()}} for a binning function. -Other functions to define bins: -\code{\link{breaks_on_binSize}()} +Other functions to define bins: +\code{\link[=breaks_on_binSize]{breaks_on_binSize()}} } \author{ Johannes Rainer diff --git a/man/chromPeakChromatograms.Rd b/man/chromPeakChromatograms.Rd index 7fb8663d..29e129d2 100644 --- a/man/chromPeakChromatograms.Rd +++ b/man/chromPeakChromatograms.Rd @@ -13,7 +13,7 @@ chromPeakChromatograms(object, ...) expandMz = 0, aggregationFun = "max", peaks = character(), - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", "Chromatograms"), ..., progressbar = TRUE ) @@ -43,27 +43,52 @@ peaks (i.e. the row names of the peaks in \code{chromPeaks(object)}) for which chromatograms should be returned.} \item{return.type}{\code{character(1)} specifying the type of the returned object. -Can be either \code{return.type = "XChromatograms"} (the default) or -\code{return.type = "MChromatograms"} to return either a chromatographic -object with or without the identified chromatographic peaks, -respectively.} +Can be either \code{return.type = "XChromatograms"} (the default), +\code{return.type = "MChromatograms"} or \code{return.type = "Chromatograms"}.} \item{progressbar}{\code{logical(1)} whether the progress of the extraction process should be displayed.} } \description{ Extract an ion chromatogram (EIC) for each chromatographic peak in an -\code{\link[=XcmsExperiment]{XcmsExperiment()}} object. The result is returned as an \code{\link[=XChromatograms]{XChromatograms()}} -of length equal to the number of chromatographic peaks (and one column). +\code{\link[=XcmsExperiment]{XcmsExperiment()}} object. Parameters \code{expandRt} and \code{expandMz} allow to +increase the retention time and/or m/z boundaries of each chromatographic +peak. Parameter \code{return.type} allows to define the format in which the +chromatograms are returned: +\itemize{ +\item \code{return.type = "Chromatograms"}: return the EICs as a +\code{\link[Chromatograms:Chromatograms]{Chromatograms::Chromatograms()}} object. The ID of the chromatographic peak +can be accessed with \verb{$chrom_peak_id} from the returned object. +\item \code{return.type = "MChromatograms"}: return the EICs as a (single column) +legacy \link[MSnbase:MChromatograms]{MSnbase::MChromatograms} object. +\item \code{return.type = "XChromatograms"}: return the EICs as a (single column) +legacy \code{\link[=XChromatograms]{XChromatograms()}} object which contains also the information of +all chromatographic peaks. +} } \examples{ ## Load a test data set with detected peaks -library(MSnbase) library(xcms) library(MsExperiment) faahko_sub <- loadXcmsData("faahko_sub2") +## Extract EICs for all chromatographic peaks +library(Chromatograms) +chrs <- chromPeakChromatograms(faahko_sub, return.type = "Chromatograms") +chrs + +## Get the chrom peak ID of all EICs +chrs$chrom_peak_id + +## Plot the first 4 EICs +plotChromatograms(chrs[1:4]) + +## Plot the first 4 EICs into the same plot +plotChromatogramsOverlay(chrs[1:4]) + +## Use the legacy EIC infrastructure (MChromatograms, XChromatograms) +library(MSnbase) ## Get EICs for every detected chromatographic peak chrs <- chromPeakChromatograms(faahko_sub) chrs diff --git a/man/chromPeakSpectra.Rd b/man/chromPeakSpectra.Rd index 131b987b..bbc4c44c 100644 --- a/man/chromPeakSpectra.Rd +++ b/man/chromPeakSpectra.Rd @@ -80,7 +80,7 @@ with a prefix \code{"chrom_peak_"}. Defaults to \code{c("mz", "rt")}.} should be returned.} \item{BPPARAM}{parallel processing setup. Defaults to -\code{\link[BiocParallel:register]{BiocParallel::bpparam()}}.} +\code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}.} } \value{ parameter \code{return.type} allow to specify the type of the returned object: diff --git a/man/chromPeakSummary.Rd b/man/chromPeakSummary.Rd index e94db7bb..d0cc6ec6 100644 --- a/man/chromPeakSummary.Rd +++ b/man/chromPeakSummary.Rd @@ -34,7 +34,7 @@ on which the metric should be calculated.} \item{chunkSize}{\code{integer(1)} defining the number of samples from which data should be loaded and processed at a time.} -\item{BPPARAM}{Parallel processing setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} +\item{BPPARAM}{Parallel processing setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for details.} } \value{ diff --git a/man/chromatogram-method.Rd b/man/chromatogram-method.Rd index c99e96b5..8238624f 100644 --- a/man/chromatogram-method.Rd +++ b/man/chromatogram-method.Rd @@ -20,7 +20,7 @@ ) } \arguments{ -\item{object}{Either a \link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp} or \link{XCMSnExp} object from +\item{object}{Either a \link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp} or \link{XCMSnExp} object from which the chromatograms should be extracted.} \item{rt}{\code{numeric(2)} or two-column \code{matrix} defining the lower @@ -52,7 +52,7 @@ depend on the architecture. Default is \item{adjustedRtime}{For \verb{chromatogram,XCMSnExp}: whether the adjusted (\code{adjustedRtime = TRUE}) or raw retention times (\code{adjustedRtime = FALSE}) should be used for filtering and returned -in the resulting \link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms} object. Adjusted +in the resulting \link[MSnbase:MChromatograms]{MSnbase::MChromatograms} object. Adjusted retention times are used by default if available.} \item{filled}{\code{logical(1)} whether filled-in peaks should also be @@ -80,7 +80,7 @@ definitions for these peaks. \description{ \code{chromatogram}: extract chromatographic data (such as an extracted ion chromatogram, a base peak chromatogram or total ion chromatogram) from -an \link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp} or \link{XCMSnExp} objects. See also the help page of +an \link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp} or \link{XCMSnExp} objects. See also the help page of the \code{chromatogram} function in the \emph{MSnbase} package. } \details{ @@ -145,7 +145,7 @@ plot(chrs[1, , drop = FALSE]) } \seealso{ \link{XCMSnExp} for the data object. -\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} for the object representing chromatographic +\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} for the object representing chromatographic data. \if{html}{\out{
}}\preformatted{[XChromatograms] for the object allowing to arrange diff --git a/man/correlate-Chromatogram.Rd b/man/correlate-Chromatogram.Rd index 0ece667c..7c6a9a99 100644 --- a/man/correlate-Chromatogram.Rd +++ b/man/correlate-Chromatogram.Rd @@ -36,9 +36,9 @@ ) } \arguments{ -\item{x}{\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object.} +\item{x}{\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object.} -\item{y}{\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object.} +\item{y}{\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object.} \item{use}{\code{character(1)} passed to the \code{cor} function. See \code{\link[=cor]{cor()}} for details.} @@ -47,7 +47,7 @@ details.} \code{\link[stats:cor]{stats::cor()}} for details.} \item{align}{\code{character(1)} defining the alignment method to be used. See -help on \code{alignRt} in \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} for details. The value of +help on \code{alignRt} in \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} for details. The value of this parameter is passed to the \code{method} parameter of \code{alignRt}.} \item{...}{optional parameters passed along to the \code{alignRt} method such as @@ -61,16 +61,16 @@ represent the chromatograms in \code{x} and the columns the chromatograms in \code{y}. } \description{ -\strong{For \code{xcms} >= 3.15.3 please use \code{\link[MSnbase:Chromatogram-class]{MSnbase::compareChromatograms()}} instead +\strong{For \code{xcms} >= 3.15.3 please use \code{\link[MSnbase:compareChromatograms]{MSnbase::compareChromatograms()}} instead of \code{correlate}} Correlate intensities of two chromatograms with each other. If the two \code{Chromatogram} objects have different retention times they are first \emph{aligned} to match data points in the first to data points in the second -chromatogram. See help on \code{alignRt} in \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} for more +chromatogram. See help on \code{alignRt} in \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} for more details. -If \code{correlate} is called on a single \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object a +If \code{correlate} is called on a single \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object a pairwise correlation of each chromatogram with each other is performed and a \code{matrix} with the correlation coefficients is returned. diff --git a/man/dirname.Rd b/man/dirname.Rd index 58c2b659..48f8b026 100644 --- a/man/dirname.Rd +++ b/man/dirname.Rd @@ -18,7 +18,7 @@ defining the new path to the files.} } \description{ \code{dirname} allows to get and set the path to the directory containing the -source files of the \code{OnDiskMSnExp} (or \linkS4class{XCMSnExp}) object. +source files of the \code{OnDiskMSnExp} (or \link[=XCMSnExp-class]{XCMSnExp}) object. } \author{ Johannes Rainer diff --git a/man/do_findChromPeaks_centWave.Rd b/man/do_findChromPeaks_centWave.Rd index 62912756..06addd91 100644 --- a/man/do_findChromPeaks_centWave.Rd +++ b/man/do_findChromPeaks_centWave.Rd @@ -224,11 +224,11 @@ sensitive feature detection for high resolution LC/MS" doi: \href{https://doi.org/10.1186/1471-2105-9-504}{10.1186/1471-2105-9-504} } \seealso{ -Other core peak detection functions: -\code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}()}, -\code{\link{do_findChromPeaks_massifquant}()}, -\code{\link{do_findChromPeaks_matchedFilter}()}, -\code{\link{do_findPeaks_MSW}()} +Other core peak detection functions: +\code{\link[=do_findChromPeaks_centWaveWithPredIsoROIs]{do_findChromPeaks_centWaveWithPredIsoROIs()}}, +\code{\link[=do_findChromPeaks_massifquant]{do_findChromPeaks_massifquant()}}, +\code{\link[=do_findChromPeaks_matchedFilter]{do_findChromPeaks_matchedFilter()}}, +\code{\link[=do_findPeaks_MSW]{do_findPeaks_MSW()}} } \author{ Ralf Tautenhahn, Johannes Rainer diff --git a/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd b/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd index 9d14f5ba..314e9415 100644 --- a/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd +++ b/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd @@ -236,11 +236,11 @@ For more details on the centWave algorithm see \code{\link[=centWave]{centWave()}}. } \seealso{ -Other core peak detection functions: -\code{\link{do_findChromPeaks_centWave}()}, -\code{\link{do_findChromPeaks_massifquant}()}, -\code{\link{do_findChromPeaks_matchedFilter}()}, -\code{\link{do_findPeaks_MSW}()} +Other core peak detection functions: +\code{\link[=do_findChromPeaks_centWave]{do_findChromPeaks_centWave()}}, +\code{\link[=do_findChromPeaks_massifquant]{do_findChromPeaks_massifquant()}}, +\code{\link[=do_findChromPeaks_matchedFilter]{do_findChromPeaks_matchedFilter()}}, +\code{\link[=do_findPeaks_MSW]{do_findPeaks_MSW()}} } \author{ Hendrik Treutler, Johannes Rainer diff --git a/man/do_findChromPeaks_massifquant.Rd b/man/do_findChromPeaks_massifquant.Rd index 202c8ca4..32fe86bb 100644 --- a/man/do_findChromPeaks_massifquant.Rd +++ b/man/do_findChromPeaks_massifquant.Rd @@ -200,11 +200,11 @@ detection" \emph{Bioinformatics} 2014, 30(18):2636-43. doi: \href{https://doi.org/10.1093/bioinformatics/btu359}{10.1093/bioinformatics/btu359} } \seealso{ -Other core peak detection functions: -\code{\link{do_findChromPeaks_centWave}()}, -\code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}()}, -\code{\link{do_findChromPeaks_matchedFilter}()}, -\code{\link{do_findPeaks_MSW}()} +Other core peak detection functions: +\code{\link[=do_findChromPeaks_centWave]{do_findChromPeaks_centWave()}}, +\code{\link[=do_findChromPeaks_centWaveWithPredIsoROIs]{do_findChromPeaks_centWaveWithPredIsoROIs()}}, +\code{\link[=do_findChromPeaks_matchedFilter]{do_findChromPeaks_matchedFilter()}}, +\code{\link[=do_findPeaks_MSW]{do_findPeaks_MSW()}} } \author{ Christopher Conley diff --git a/man/do_findChromPeaks_matchedFilter.Rd b/man/do_findChromPeaks_matchedFilter.Rd index 764743ba..c2cb44bd 100644 --- a/man/do_findChromPeaks_matchedFilter.Rd +++ b/man/do_findChromPeaks_matchedFilter.Rd @@ -161,11 +161,11 @@ doi: \href{https://doi.org/10.1021/ac051437y}{10.1021/ac051437y} \code{\link[=binYonX]{binYonX()}} for a binning function, \code{\link[=imputeLinInterpol]{imputeLinInterpol()}} for the interpolation of missing values. -Other core peak detection functions: -\code{\link{do_findChromPeaks_centWave}()}, -\code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}()}, -\code{\link{do_findChromPeaks_massifquant}()}, -\code{\link{do_findPeaks_MSW}()} +Other core peak detection functions: +\code{\link[=do_findChromPeaks_centWave]{do_findChromPeaks_centWave()}}, +\code{\link[=do_findChromPeaks_centWaveWithPredIsoROIs]{do_findChromPeaks_centWaveWithPredIsoROIs()}}, +\code{\link[=do_findChromPeaks_massifquant]{do_findChromPeaks_massifquant()}}, +\code{\link[=do_findPeaks_MSW]{do_findPeaks_MSW()}} } \author{ Colin A Smith, Johannes Rainer diff --git a/man/do_findPeaks_MSW.Rd b/man/do_findPeaks_MSW.Rd index c91c8867..6f0ed884 100644 --- a/man/do_findPeaks_MSW.Rd +++ b/man/do_findPeaks_MSW.Rd @@ -61,11 +61,11 @@ This is a wrapper around the peak picker in Bioconductor's \emph{xcmsDirect} vignette for more information. } \seealso{ -Other core peak detection functions: -\code{\link{do_findChromPeaks_centWave}()}, -\code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}()}, -\code{\link{do_findChromPeaks_massifquant}()}, -\code{\link{do_findChromPeaks_matchedFilter}()} +Other core peak detection functions: +\code{\link[=do_findChromPeaks_centWave]{do_findChromPeaks_centWave()}}, +\code{\link[=do_findChromPeaks_centWaveWithPredIsoROIs]{do_findChromPeaks_centWaveWithPredIsoROIs()}}, +\code{\link[=do_findChromPeaks_massifquant]{do_findChromPeaks_massifquant()}}, +\code{\link[=do_findChromPeaks_matchedFilter]{do_findChromPeaks_matchedFilter()}} } \author{ Joachim Kutzera, Steffen Neumann, Johannes Rainer diff --git a/man/do_groupChromPeaks_density.Rd b/man/do_groupChromPeaks_density.Rd index 9163f2ea..857a93fe 100644 --- a/man/do_groupChromPeaks_density.Rd +++ b/man/do_groupChromPeaks_density.Rd @@ -139,9 +139,9 @@ Anal. Chem. 2006, 78:779-787. doi: \href{https://doi.org/10.1021/ac051437y}{10.1021/ac051437y} } \seealso{ -Other core peak grouping algorithms: -\code{\link{do_groupChromPeaks_nearest}()}, -\code{\link{do_groupPeaks_mzClust}()} +Other core peak grouping algorithms: +\code{\link[=do_groupChromPeaks_nearest]{do_groupChromPeaks_nearest()}}, +\code{\link[=do_groupPeaks_mzClust]{do_groupPeaks_mzClust()}} } \author{ Colin Smith, Johannes Rainer diff --git a/man/do_groupChromPeaks_nearest.Rd b/man/do_groupChromPeaks_nearest.Rd index b85161a1..9d2e34ae 100644 --- a/man/do_groupChromPeaks_nearest.Rd +++ b/man/do_groupChromPeaks_nearest.Rd @@ -74,8 +74,8 @@ data. Bioinformatics 2006, 22:634-636. doi: \href{https://doi.org/10.1093/bioinformatics/btk039}{10.1093/bioinformatics/btk039} } \seealso{ -Other core peak grouping algorithms: -\code{\link{do_groupChromPeaks_density}()}, -\code{\link{do_groupPeaks_mzClust}()} +Other core peak grouping algorithms: +\code{\link[=do_groupChromPeaks_density]{do_groupChromPeaks_density()}}, +\code{\link[=do_groupPeaks_mzClust]{do_groupPeaks_mzClust()}} } \concept{core peak grouping algorithms} diff --git a/man/do_groupPeaks_mzClust.Rd b/man/do_groupPeaks_mzClust.Rd index 48eb6d9c..79d53d66 100644 --- a/man/do_groupPeaks_mzClust.Rd +++ b/man/do_groupPeaks_mzClust.Rd @@ -82,8 +82,8 @@ development of a heuristic approach for metabolomics}.\cr Metabolomics, Vol. 2, No. 2, 75-83 (2006) } \seealso{ -Other core peak grouping algorithms: -\code{\link{do_groupChromPeaks_density}()}, -\code{\link{do_groupChromPeaks_nearest}()} +Other core peak grouping algorithms: +\code{\link[=do_groupChromPeaks_density]{do_groupChromPeaks_density()}}, +\code{\link[=do_groupChromPeaks_nearest]{do_groupChromPeaks_nearest()}} } \concept{core peak grouping algorithms} diff --git a/man/estimatePrecursorIntensity.Rd b/man/estimatePrecursorIntensity.Rd index 9189f44f..2f64804d 100644 --- a/man/estimatePrecursorIntensity.Rd +++ b/man/estimatePrecursorIntensity.Rd @@ -37,7 +37,7 @@ respective ion on the MS1 scan.} should be determined (see description above for details). Defaults to \code{method = "previous"}.} -\item{BPPARAM}{parallel processing setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for +\item{BPPARAM}{parallel processing setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for details.} } \value{ diff --git a/man/feature-grouping.Rd b/man/feature-grouping.Rd index 9023e422..bcf758fb 100644 --- a/man/feature-grouping.Rd +++ b/man/feature-grouping.Rd @@ -25,7 +25,7 @@ originating compound. The \href{https://bioconductor.org/packages/MsFeatures}{MsFeatures} package provides a general framework and functionality to group features based on different properties. The \code{groupFeatures} methods for \code{\link[=XcmsExperiment]{XcmsExperiment()}} or -\linkS4class{XCMSnExp} objects implemented in \code{xcms} extend these to enable +\link[=XCMSnExp-class]{XCMSnExp} objects implemented in \code{xcms} extend these to enable the \emph{compounding} of LC-MS data considering also e.g. feature peak shaped. Note that these functions simply define feature groups but don't actually \emph{aggregate} or combine the features. @@ -40,7 +40,7 @@ analysis with \code{\link[=groupChromPeaks]{groupChromPeaks()}}) are: \itemize{ \item Grouping by similar retention times: \code{\link[=groupFeatures-similar-rtime]{groupFeatures-similar-rtime()}}. \item Grouping by similar feature values across samples: -\code{\link[MsFeatures:groupFeatures-similar-abundance]{MsFeatures::AbundanceSimilarityParam()}}. +\code{\link[MsFeatures:AbundanceSimilarityParam]{MsFeatures::AbundanceSimilarityParam()}}. \item Grouping by similar peak shape of extracted ion chromatograms: \code{\link[=EicSimilarityParam]{EicSimilarityParam()}}. } diff --git a/man/featureChromPeaks.Rd b/man/featureChromPeaks.Rd new file mode 100644 index 00000000..aa96e2cc --- /dev/null +++ b/man/featureChromPeaks.Rd @@ -0,0 +1,81 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AllGenerics.R, R/XcmsExperiment.R, +% R/XcmsExperimentHdf5.R +\name{featureChromPeaks} +\alias{featureChromPeaks} +\alias{featurePeakidx} +\alias{featurePeakidx,XcmsResult-method} +\alias{featureChromPeaks,XcmsResult-method} +\alias{featureChromPeaks,XcmsExperimentHdf5-method} +\alias{featurePeakidx,XcmsExperimentHdf5-method} +\title{Feature to chromatographic peak mapping} +\usage{ +featureChromPeaks(object, ...) + +featurePeakidx(object, ...) + +\S4method{featurePeakidx}{XcmsResult}(object, msLevel = integer()) + +\S4method{featureChromPeaks}{XcmsResult}(object, msLevel = integer()) + +\S4method{featureChromPeaks}{XcmsExperimentHdf5}(object, msLevel = integer()) + +\S4method{featurePeakidx}{XcmsExperimentHdf5}(object, msLevel = integer()) +} +\arguments{ +\item{object}{An \emph{xcms} result object with correspondence analysis results +being present.} + +\item{...}{Optional parameters. Currently ignored.} + +\item{msLevel}{Optional \code{integer} to restrict to features from a certain MS +level.} +} +\value{ +See description above. +} +\description{ +During the correspondence step in the preprocessing, chromatographic peaks +get assigned (grouped) to features. The abundances of these resulting LC-MS +features are supposed to represent signal from the same ion across all +analyzed samples. Depending on the correspondence analysis method used, +multiple chromatographic peaks (also eventually from the \strong{same} sample) are +assigned to a feature. This mapping between features and chromatographic +peaks is (for \link{XcmsExperiment} and \link{XCMSnExp} object) stored in the +\code{"peakidx"} column of the \code{\link[=featureDefinitions]{featureDefinitions()}} data frame. Alternatively, +the mapping can be extracted from an \emph{xcms} result object using the +functions: +\itemize{ +\item \code{featureChromPeaks()}: returns a two-column \code{data.frame} with the IDs of +the features and the IDs of the associated chromatographic peaks. Each +row in this \code{data.frame} represents the mapping of one chromatographic +peak with one feature. The order of the features in the \code{data.frame} +matches the order of the features in \code{\link[=featureDefinitions]{featureDefinitions()}}. +\item \code{featurePeakidx()}: returns a named \code{list} of \code{integer} indices of the +rows in the \code{\link[=chromPeaks]{chromPeaks()}} matrix that are assigned to a feature. The names +of the \code{list} are the feature IDs. +The length and order of the \code{list} matches the number of rows and order of +features in \code{\link[=featureDefinitions]{featureDefinitions()}}. +} +} +\examples{ + +## Load preprocessing results +library(MsExperiment) +xmse <- loadXcmsData() + +## Get the mapping between features and chromatographic peaks +map <- featureChromPeaks(xmse) + +head(map) + +## Column `"feature_id"` contains the IDs for the features defined in +## `featureDefinitions()` +featureDefinitions(xmse) |> head() + +## Column `"chrom_peak_id"` contains the IDs of the chromatographic peaks +chromPeaks(xmse) |> head() + +## Alternatively, get the mapping as a `list` of `integer` indices +featurePeakidx(xmse) |> head() +} diff --git a/man/featureChromatograms.Rd b/man/featureChromatograms.Rd index 7f4a7a54..770c0ef7 100644 --- a/man/featureChromatograms.Rd +++ b/man/featureChromatograms.Rd @@ -15,12 +15,13 @@ featureChromatograms(object, ...) expandMz = 0, aggregationFun = "max", features = character(), - return.type = "XChromatograms", + return.type = c("XChromatograms", "MChromatograms", "Chromatograms"), chunkSize = 2L, mzmin = min, mzmax = max, rtmin = min, rtmax = max, + featureArea = TRUE, ..., progressbar = TRUE, BPPARAM = bpparam() @@ -67,9 +68,9 @@ of the features in \code{featureDefinitions}, feature IDs (row names of \code{featureDefinitions}) or a logical vector.} \item{return.type}{\code{character(1)} defining how the result should be -returned. At present only \code{return.type = "XChromatograms"} is -supported and the results are thus returned as an \code{\link[=XChromatograms]{XChromatograms()}} -object.} +returned. Supported are \code{return.type = "XChromatograms"} (the default), +\code{return.type = "MChromatograms"} and \code{return.type = "Chromatograms"}. +See function descriptions for details.} \item{chunkSize}{For \code{object} being an \code{XcmsExperiment}: \code{integer(1)} defining the number of files from which the data should be loaded at @@ -95,10 +96,14 @@ from which the EIC is integrated should be defined. Defaults to \code{rtmax = max} thus the largest \code{"rtmax"} value for all chromatographic peaks of a feature will be used.} +\item{featureArea}{For \code{object} being a \code{XcmsExperiment} and +\code{return.type = FALSE}: return EICs representing data within the +identified chromatographic peaks.} + \item{progressbar}{\code{logical(1)} defining whether a progress bar is shown.} \item{BPPARAM}{For \code{object} being an \code{XcmsExperiment}: parallel processing -setup. Defaults to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} +setup. Defaults to \code{BPPARAM = bpparam()}. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} \item{include}{Only for \code{object} being an \code{XCMSnExp}: \code{character(1)} @@ -121,40 +126,67 @@ specifying the column to be used to sort the samples. Can be either or the integrated peak area, respectively.} } \value{ -\code{\link[=XChromatograms]{XChromatograms()}} object. In future, depending on parameter -\code{return.type}, the data might be returned as a different object. +Depending on parameter \code{return.type}, a \link[MSnbase:MChromatograms]{MSnbase::MChromatograms}, +\link{XChromatograms} or \code{\link[Chromatograms:Chromatograms]{Chromatograms::Chromatograms()}} object. See function +description above for details. } \description{ -Extract ion chromatograms for features in an \link{XcmsExperiment} or -\linkS4class{XCMSnExp} object. The function returns for each feature the -extracted ion chromatograms (along with all associated chromatographic -peaks) in each sample. The chromatogram is extracted from the m/z - rt -region that includes \strong{all} chromatographic peaks of a feature. By default, -this region is defined using the range of the chromatographic peaks' m/z -and retention times (with \code{mzmin = min}, \code{mzmax = max}, \code{rtmin = min} and -\code{rtmax = max}). For some features, and depending on the data, the m/z and -rt range can thus be relatively large. The boundaries of the m/z - rt -region can also be restricted by changing parameters \code{mzmin}, \code{mzmax}, -\code{rtmin} and \code{rtmax} to a different functions, such as \code{median}. - -By default only chromatographic peaks associated with a feature are -included in the returned \link{XChromatograms} object. For \code{object} being an -\code{XCMSnExp} object parameter \code{include} allows also to return all -chromatographic peaks with their apex position within the selected -region (\code{include = "apex_within"}) or any chromatographic peak overlapping -the m/z and retention time range (\code{include = "any"}). +\code{featureChromatograms()} extracts ion chromatograms for features in an +\link{XcmsExperiment} or \link[=XCMSnExp-class]{XCMSnExp} object. The function returns for each +feature the extracted ion chromatograms in each sample. Based on the setting +for parameter \code{return.type} the results are returned as a legacy +\link[MSnbase:MChromatograms]{MSnbase::MChromatograms} or \code{\link[=XChromatograms]{XChromatograms()}} object +(\code{return.type = "MChromatograms"} or \code{return.type = "XChromatograms"}, the +default) or as a new \code{\link[Chromatograms:Chromatograms]{Chromatograms::Chromatograms()}} object +(\code{return.type = "Chromatograms"}): +\itemize{ +\item \code{return.type = "MChromatograms"}: the chromatograms are extracted from the +m/z - rt region that includes all chromatographic peaks for a feature. The +\code{\link[=featureArea]{featureArea()}} function is used to define this region which is defined +using the range of the chromatographic peaks' m/z and retention times. The +\code{MChromatograms} organizes the EICs per feature, i.e., each row in the +returned \code{MChromatograms} corresponds to one feature with columns +containing EICs per sample. +\item \code{return.type = "XChromatograms"}: chromatographic data is defined as for +\code{return.type = "MChromatograms"}, but the returned EICs contain in addition +also the information on the individual chromatographic peaks as well as +the feature definitions. For \code{object} being an \code{XCMSnExp} object, +parameter \code{include} allows also to return all chromatographic peaks with +their apex position within the selected region (\code{include = "apex_within"}) +or any chromatographic peak overlapping the m/z and retention time range +(\code{include = "any"}). +\item \code{return.type = "Chromatograms"}: the EICs, defined through \code{\link[=featureArea]{featureArea()}} +as described above, are returned as a \code{\link[Chromatograms:Chromatograms]{Chromatograms()}} object which +organizes chromatograms sequentially in a list-like structure: first all +chromatograms for the first feature in all samples, then those from the +second feature and so on. See examples for details. +The feature ID is stored in the result object's \verb{$feature_id} variable. +By default, the returned EICs represent the chromatograms of the +\code{featureArea()}, but with \code{featureArea = FALSE} each returned chromatogram +represents the EIC for the actual area of the individual chromatographic +peaks assigned to the feature (same as with \code{\link[=chromPeakChromatograms]{chromPeakChromatograms()}}). +The IDs of the chromatographic peaks can then be accessed through +\verb{$chrom_peak_id}. +} } \note{ -The EIC data of a feature is extracted from every sample using the same -m/z - rt area. The EIC in a sample does thus not exactly represent the -signal of the actually identified chromatographic peak in that sample. -The \code{\link[=chromPeakChromatograms]{chromPeakChromatograms()}} function would allow to extract the actual -EIC of the chromatographic peak in a specific sample. See also examples -below. +Some of the functionality available for \code{XChromatograms} objects is not +yet available for \code{Chromatograms}. Thus, while the newer +\code{Chromatograms}-based infrastructure is more efficient and powerful, for +some operations it is suggested to still use the legacy objects (such as +simulating a correspondence analysis through \code{\link[=plotChromPeakDensity]{plotChromPeakDensity()}}). + +By default the EIC data of a feature is extracted from every sample using +the same m/z - rt area. Unless \code{featureArea = FALSE} is used, the EIC in a +sample does thus not exactly represent the signal of the actually identified +chromatographic peak in that sample. Parameters \code{include}, \code{filled}, \code{n} and \code{value} are only supported for \code{object} being an \code{XCMSnExp}. +Parameter \code{featureArea} is only supported for +\code{return.type = "Chromatograms"}. + When extracting EICs from only the top \code{n} samples it can happen that one or more of the features specified with \code{features} are dropped because they have no detected peak in the \emph{top n} samples. The chance for this to happen @@ -177,10 +209,51 @@ xdata <- groupChromPeaks(faahko_sub, ## Get the feature definitions featureDefinitions(xdata) +############################################################################# +## Extracting the feature's EICs as an `Chromatograms` object + +## Define the IDs for selected features from which to extract the data +fids <- rownames(featureDefinitions(xdata))[1:3] +chrs <- featureChromatograms(xdata, features = fids, + return.type = "Chromatograms") +chrs + +## The data is organized by feature and sample: first all EICs for the first +## feature in all samples, then those from the second etc +chrs$feature_id + +## The sample information is stored in the object's `$dataOrigin` +basename(chrs$dataOrigin) + +## Plot the data for the first feature +library(Chromatograms) + +## Separately +plotChromatograms(chrs[chrs$feature_id == fids[1]]) + +## In a single plot +plotChromatogramsOverlay(chrs[chrs$feature_id == fids[1]]) + +## Extract the EICs for the individual chromatographic peaks associated to +## each feature: +chrs <- featureChromatograms(xdata, features = fids, + return.type = "Chromatograms", featureArea = FALSE) +chrs + +## In contrast to `featureArea = TRUE`, where one (and only one) EIC per +## sample is guaranteed, for `featureArea = FALSE` there can be more than +## one chromatogram per sample (or no chromatogram per sample), representing +## exactly the association between identified chromatographic peaks and +## features +chrs$feature_id +chrs$chrom_peak_id + +############################################################################# +## Using the legacy `MChromatogtrams`/`XChromatograms` + ## Extract ion chromatograms for the first 3 features. Parameter ## `features` can be either the feature IDs or feature indices. -chrs <- featureChromatograms(xdata, - features = rownames(featureDefinitions)[1:3]) +chrs <- featureChromatograms(xdata, features = fids) ## Plot the EIC for the first feature using different colors for each file. plot(chrs[1, ], col = c("red", "green", "blue")) diff --git a/man/filter-MChromatograms.Rd b/man/filter-MChromatograms.Rd index 75c35eb3..b7afb5f2 100644 --- a/man/filter-MChromatograms.Rd +++ b/man/filter-MChromatograms.Rd @@ -39,7 +39,7 @@ ) } \arguments{ -\item{object}{\code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} or \code{\link[=XChromatograms]{XChromatograms()}} object.} +\item{object}{\code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} or \code{\link[=XChromatograms]{XChromatograms()}} object.} \item{threshold}{for \code{filterColumnsIntensityAbove}: \code{numeric(1)} with the threshold value to compare against.} @@ -82,10 +82,10 @@ same number of rows (EICs) but eventually a lower number of columns (samples). } \description{ -These functions allow to filter (subset) \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} or +These functions allow to filter (subset) \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} or \code{\link[=XChromatograms]{XChromatograms()}} objects, i.e. sets of chromatographic data, without changing the data (intensity and retention times) within the individual -chromatograms (\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} objects). +chromatograms (\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} objects). \itemize{ \item \code{filterColumnsIntensityAbove}: subsets a \code{MChromatograms} objects keeping only columns (samples) for which \code{value} is larger than the provided diff --git a/man/findChromPeaks-Chromatogram-CentWaveParam.Rd b/man/findChromPeaks-Chromatogram-CentWaveParam.Rd index b192dfb1..74807af1 100644 --- a/man/findChromPeaks-Chromatogram-CentWaveParam.Rd +++ b/man/findChromPeaks-Chromatogram-CentWaveParam.Rd @@ -15,7 +15,7 @@ \S4method{findChromPeaks}{MChromatograms,MatchedFilterParam}(object, param, BPPARAM = BPPARAM, ...) } \arguments{ -\item{object}{a \link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram} or \link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms} object.} +\item{object}{a \link[MSnbase:Chromatogram]{MSnbase::Chromatogram} or \link[MSnbase:MChromatograms]{MSnbase::MChromatograms} object.} \item{param}{a \link{CentWaveParam} object specifying the settings for the peak detection. See \code{\link[=peaksWithCentWave]{peaksWithCentWave()}} for the description of @@ -25,7 +25,7 @@ arguments used for peak detection.} \item{BPPARAM}{a parameter class specifying if and how parallel processing should be performed (only for \code{XChromatograms} objects). It defaults to -\code{bpparam()}. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for more information.} +\code{bpparam()}. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} } \value{ If called on a \code{Chromatogram} object, the method returns an \link{XChromatogram} @@ -35,7 +35,7 @@ minimum m/z value of the \code{Chromatogram} object. See \code{\link[=peaksWithC for details on the remaining columns. } \description{ -\code{findChromPeaks} on a \link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram} or \link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms} +\code{findChromPeaks} on a \link[MSnbase:Chromatogram]{MSnbase::Chromatogram} or \link[MSnbase:MChromatograms]{MSnbase::MChromatograms} object with a \link{CentWaveParam} parameter object performs centWave-based peak detection on purely chromatographic data. See \link{centWave} for details on the method and \link{CentWaveParam} for details on the parameter class. diff --git a/man/findChromPeaks-Chromatogram-MatchedFilter.Rd b/man/findChromPeaks-Chromatogram-MatchedFilter.Rd index 90dd65b7..131bc759 100644 --- a/man/findChromPeaks-Chromatogram-MatchedFilter.Rd +++ b/man/findChromPeaks-Chromatogram-MatchedFilter.Rd @@ -7,7 +7,7 @@ \S4method{findChromPeaks}{Chromatogram,MatchedFilterParam}(object, param, ...) } \arguments{ -\item{object}{a \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} +\item{object}{a \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object.} \item{param}{a \link{MatchedFilterParam} object specifying the settings for the @@ -24,8 +24,8 @@ minimum m/z value of the \code{Chromatogram} object. See \code{\link[=peaksWithMatchedFilter]{peaksWithMatchedFilter()}} for details on the remaining columns. } \description{ -\code{findChromPeaks} on a \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or -\code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object with a +\code{findChromPeaks} on a \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or +\code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object with a \link{MatchedFilterParam} parameter object performs matchedFilter-based peak detection on purely chromatographic data. See \link{matchedFilter} for details on the method and \link{MatchedFilterParam} for details on the parameter class. diff --git a/man/findChromPeaks-centWave.Rd b/man/findChromPeaks-centWave.Rd index c50696e9..95da3688 100644 --- a/man/findChromPeaks-centWave.Rd +++ b/man/findChromPeaks-centWave.Rd @@ -121,7 +121,7 @@ best-fitting bell curve. See https://github.com/sneumann/xcms/pull/685 and https://doi.org/10.1186/s12859-023-05533-4 for more information.} \item{object}{For \code{findChromPeaks()}: an -\code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} object containing the MS- and all +\code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} object containing the MS- and all other experiment-relevant data. \if{html}{\out{
}}\preformatted{For all other methods: a parameter object. @@ -131,7 +131,7 @@ other experiment-relevant data. centWave algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing -should be performed. It defaults to \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}. +should be performed. It defaults to \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}. See documentation of the \emph{BiocParallel} package for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.} @@ -237,8 +237,8 @@ detection in purely chromatographic data. \code{\link[=XCMSnExp]{XCMSnExp()}} for the object containing the results of the peak detection. -Other peak detection methods: -\code{\link{findChromPeaks}()}, +Other peak detection methods: +\code{\link[=findChromPeaks]{findChromPeaks()}}, \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, \code{\link{findChromPeaks-massifquant}}, \code{\link{findChromPeaks-matchedFilter}}, diff --git a/man/findChromPeaks-centWaveWithPredIsoROIs.Rd b/man/findChromPeaks-centWaveWithPredIsoROIs.Rd index c8c3ac08..7654a744 100644 --- a/man/findChromPeaks-centWaveWithPredIsoROIs.Rd +++ b/man/findChromPeaks-centWaveWithPredIsoROIs.Rd @@ -141,7 +141,7 @@ Currently not used, but has to be \code{"positive"}, \code{"negative"} or \code{"unknown"} if provided.} \item{object}{For \code{findChromPeaks()}: an -\code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} object containing the MS- and all +\code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} object containing the MS- and all other experiment-relevant data. \if{html}{\out{
}}\preformatted{For all other methods: a parameter object. @@ -151,7 +151,7 @@ other experiment-relevant data. chromatographic peak detection algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing -should be performed. It defaults to \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}. +should be performed. It defaults to \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}. See documentation of the \emph{BiocParallel} package for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.} @@ -216,8 +216,8 @@ API function. \code{\link[=XCMSnExp]{XCMSnExp()}} for the object containing the results of the peak detection. -Other peak detection methods: -\code{\link{findChromPeaks}()}, +Other peak detection methods: +\code{\link[=findChromPeaks]{findChromPeaks()}}, \code{\link{findChromPeaks-centWave}}, \code{\link{findChromPeaks-massifquant}}, \code{\link{findChromPeaks-matchedFilter}}, diff --git a/man/findChromPeaks-massifquant.Rd b/man/findChromPeaks-massifquant.Rd index 63208fbf..6a3e43ca 100644 --- a/man/findChromPeaks-massifquant.Rd +++ b/man/findChromPeaks-massifquant.Rd @@ -138,7 +138,7 @@ other experiment-relevant data. the massifquant algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing -should be performed. It defaults to \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}. +should be performed. It defaults to \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}. See documentation of the \emph{BiocParallel} package for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.} @@ -236,8 +236,8 @@ and \code{\link[=findPeaks.massifquant]{findPeaks.massifquant()}} for the old us \code{\link[=XCMSnExp]{XCMSnExp()}} for the object containing the results of the peak detection. -Other peak detection methods: -\code{\link{findChromPeaks}()}, +Other peak detection methods: +\code{\link[=findChromPeaks]{findChromPeaks()}}, \code{\link{findChromPeaks-centWave}}, \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, \code{\link{findChromPeaks-matchedFilter}}, diff --git a/man/findChromPeaks-matchedFilter.Rd b/man/findChromPeaks-matchedFilter.Rd index d17e0114..893e75c3 100644 --- a/man/findChromPeaks-matchedFilter.Rd +++ b/man/findChromPeaks-matchedFilter.Rd @@ -84,7 +84,7 @@ other experiment-relevant data. the matchedFilter algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing -should be performed. It defaults to \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}. +should be performed. It defaults to \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}. See documentation of the \emph{BiocParallel} package for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.} @@ -126,8 +126,8 @@ cut-off. For more details and illustrations see \emph{Smith 2006}. The \verb{findChromPeaks,OnDiskMSnExp,MatchedFilterParam()} method performs peak detection using the \emph{matchedFilter} algorithm -on all samples from an \code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} object. -\code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}} objects encapsule all experiment +on all samples from an \code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} object. +\code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}} objects encapsule all experiment specific data and load the spectra data (mz and intensity values) on the fly from the original files applying also all eventual data manipulations. @@ -186,8 +186,8 @@ peak detection in purely chromatographic data. \code{\link[=XCMSnExp]{XCMSnExp()}} for the object containing the results of the chromatographic peak detection. -Other peak detection methods: -\code{\link{findChromPeaks}()}, +Other peak detection methods: +\code{\link[=findChromPeaks]{findChromPeaks()}}, \code{\link{findChromPeaks-centWave}}, \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, \code{\link{findChromPeaks-massifquant}}, diff --git a/man/findChromPeaks.Rd b/man/findChromPeaks.Rd index 17a49530..17f0c3bf 100644 --- a/man/findChromPeaks.Rd +++ b/man/findChromPeaks.Rd @@ -31,7 +31,7 @@ findChromPeaks(object, param, ...) } \arguments{ \item{object}{The data object on which to perform the peak detection. Can be -an \code{\link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp()}}, \code{\link[=XCMSnExp]{XCMSnExp()}}, \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} +an \code{\link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp()}}, \code{\link[=XCMSnExp]{XCMSnExp()}}, \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} or \code{\link[MsExperiment:MsExperiment]{MsExperiment::MsExperiment()}} object.} \item{param}{The parameter object selecting and configuring the algorithm.} @@ -67,7 +67,7 @@ can be forced using \code{force.overwrite = TRUE}.} existing result file should be overwritten.} \item{BPPARAM}{Parallel processing setup. Uses by default the system-wide -default setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for more details.} +default setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more details.} \item{add}{\code{logical(1)} (if \code{object} contains already chromatographic peaks, i.e. is either an \code{XCMSnExp} or \code{XcmsExperiment}) whether chromatographic @@ -105,7 +105,7 @@ chromatographic peaks. \code{\link[=manualChromPeaks]{manualChromPeaks()}} to manually add/define chromatographic peaks. -Other peak detection methods: +Other peak detection methods: \code{\link{findChromPeaks-centWave}}, \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, \code{\link{findChromPeaks-massifquant}}, diff --git a/man/findChromPeaksIsolationWindow.Rd b/man/findChromPeaksIsolationWindow.Rd index 5334640b..c416be0d 100644 --- a/man/findChromPeaksIsolationWindow.Rd +++ b/man/findChromPeaksIsolationWindow.Rd @@ -34,7 +34,7 @@ object with the DIA data.} \item{...}{currently not used.} \item{param}{Peak detection parameter object, such as a -\linkS4class{CentWaveParam} object defining and configuring the chromographic +\link[=CentWaveParam-class]{CentWaveParam} object defining and configuring the chromographic peak detection algorithm. See also \code{\link[=findChromPeaks]{findChromPeaks()}} for more details.} @@ -51,7 +51,7 @@ loaded into memory and processed at a time. See \code{\link[=findChromPeaks]{fin more information.} \item{BPPARAM}{if \code{object} is an \code{MsExperiment} or \code{XcmsExperiment}: -parallel processing setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for more +parallel processing setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} } \value{ diff --git a/man/findPeaks-MSW.Rd b/man/findPeaks-MSW.Rd index 95482217..8f763743 100644 --- a/man/findPeaks-MSW.Rd +++ b/man/findPeaks-MSW.Rd @@ -79,7 +79,7 @@ other experiment-relevant data. the algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing -should be performed. It defaults to \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}. +should be performed. It defaults to \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}}. See documentation of the \emph{BiocParallel} package for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.} @@ -155,8 +155,8 @@ and \code{\link[=findPeaks.MSW]{findPeaks.MSW()}} for the old user interface. \code{\link[=XCMSnExp]{XCMSnExp()}} for the object containing the results of the peak detection. -Other peak detection methods: -\code{\link{findChromPeaks}()}, +Other peak detection methods: +\code{\link[=findChromPeaks]{findChromPeaks()}}, \code{\link{findChromPeaks-centWave}}, \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, \code{\link{findChromPeaks-massifquant}}, diff --git a/man/groupFeatures-abundance-correlation.Rd b/man/groupFeatures-abundance-correlation.Rd index 435b4a00..bf166090 100644 --- a/man/groupFeatures-abundance-correlation.Rd +++ b/man/groupFeatures-abundance-correlation.Rd @@ -21,7 +21,7 @@ pre-processing results.} \item{param}{\code{AbudanceSimilarityParam} object with the settings for the -method. See \code{\link[MsFeatures:groupFeatures-similar-abundance]{MsFeatures::AbundanceSimilarityParam()}} for details on +method. See \code{\link[MsFeatures:AbundanceSimilarityParam]{MsFeatures::AbundanceSimilarityParam()}} for details on the grouping method and its parameters.} \item{msLevel}{\code{integer(1)} defining the MS level on which the features @@ -51,13 +51,13 @@ Features from the same originating compound are expected to have similar intensities across samples. This method thus groups features based on similarity of abundances (i.e. \emph{feature values}) across samples in a data set. -See also \code{\link[MsFeatures:groupFeatures-similar-abundance]{MsFeatures::AbundanceSimilarityParam()}} for additional +See also \code{\link[MsFeatures:AbundanceSimilarityParam]{MsFeatures::AbundanceSimilarityParam()}} for additional information and details. This help page lists parameters specific for \code{xcms} result objects (i.e. \code{\link[=XcmsExperiment]{XcmsExperiment()}} and \code{\link[=XCMSnExp]{XCMSnExp()}} objects). Documentation of the parameters for the similarity calculation is available in the -\code{\link[MsFeatures:groupFeatures-similar-abundance]{MsFeatures::AbundanceSimilarityParam()}} help page in the \emph{MsFeatures} +\code{\link[MsFeatures:AbundanceSimilarityParam]{MsFeatures::AbundanceSimilarityParam()}} help page in the \emph{MsFeatures} package. } \examples{ @@ -89,7 +89,7 @@ table(featureDefinitions(xodg_grp)$feature_group) \seealso{ feature-grouping for a general overview. -Other feature grouping methods: +Other feature grouping methods: \code{\link{groupFeatures-eic-similarity}}, \code{\link{groupFeatures-similar-rtime}} } diff --git a/man/groupFeatures-eic-similarity.Rd b/man/groupFeatures-eic-similarity.Rd index 926639fd..d39c2bf6 100644 --- a/man/groupFeatures-eic-similarity.Rd +++ b/man/groupFeatures-eic-similarity.Rd @@ -45,15 +45,15 @@ based on a pairwise similarity matrix. Defaults to \item{ALIGNFUN}{\code{function} defining the function to be used to \emph{align} chromatograms prior similarity calculation. Defaults to -\code{ALIGNFUN = alignRt}. See documentation of \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} and -\code{\link[MSnbase:Chromatogram-class]{MSnbase::compareChromatograms()}} for more information.} +\code{ALIGNFUN = alignRt}. See documentation of \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} and +\code{\link[MSnbase:compareChromatograms]{MSnbase::compareChromatograms()}} for more information.} \item{ALIGNFUNARGS}{\strong{named} \code{list} with arguments for \code{ALIGNFUN}. Defaults to \code{ALIGNFUNARGS = list(tolerance = 0, method = "closest")}.} \item{FUN}{\code{function} defining the function to be used to calculate a similarity between (aligned) chromatograms. Defaults to \code{FUN = cor}. -See \code{\link[=cor]{cor()}} and \code{\link[MSnbase:Chromatogram-class]{MSnbase::compareChromatograms()}} for more information.} +See \code{\link[=cor]{cor()}} and \code{\link[MSnbase:compareChromatograms]{MSnbase::compareChromatograms()}} for more information.} \item{FUNARGS}{\strong{named} \code{list} with arguments for \code{FUN}. Defaults to \code{FUN = list(use = "pairwise.complete.obs")}.} @@ -83,14 +83,14 @@ separately for each sample with the similarity score being aggregated across samples for the final generation of the similarity matrix on which the grouping (considering parameter \code{threshold}) will be performed. -The \code{\link[MSnbase:Chromatogram-class]{MSnbase::compareChromatograms()}} function is used for similarity +The \code{\link[MSnbase:compareChromatograms]{MSnbase::compareChromatograms()}} function is used for similarity calculation which by default calculates the Pearson's correlation coefficient. The settings for \code{compareChromatograms()} can be specified with parameters \code{ALIGNFUN}, \code{ALIGNFUNARGS}, \code{FUN} and \code{FUNARGS}. \code{ALIGNFUN} defaults to \code{alignRt} and is the function used to \emph{align} the chromatograms before comparison. For information and parameters of \code{alignRt()} see the -documentation for \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}}. +documentation for \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}}. \code{ALIGNFUNARGS} allows to specify additional arguments for the \code{ALIGNFUN} function. It defaults to \code{ALIGNFUNARGS = list(tolerance = 0, method = "closest")} which ensures that @@ -99,7 +99,7 @@ are compared between the EICs from the same sample. Parameter \code{FUN} defines the function to calculate the similarity score and defaults to \code{FUN = cor} and \code{FUNARGS} allows to pass additional arguments to this function (defaults to \code{FUNARGS = list(use = "pairwise.complete.obs")}. See also -\code{\link[MSnbase:Chromatogram-class]{MSnbase::compareChromatograms()}} for more information. +\code{\link[MSnbase:compareChromatograms]{MSnbase::compareChromatograms()}} for more information. The grouping of features based on the EIC similarity matrix is performed with the function specified with parameter \code{groupFun} which defaults to @@ -111,7 +111,7 @@ cluster. See \code{\link[MsFeatures:groupSimilarityMatrix]{MsFeatures::groupSimi Additional parameters to that function can be passed with the \code{...} argument. This feature grouping should be called \strong{after} an initial feature -grouping by retention time (see \code{\link[MsFeatures:groupFeatures-similar-rtime]{MsFeatures::SimilarRtimeParam()}}). +grouping by retention time (see \code{\link[MsFeatures:SimilarRtimeParam]{MsFeatures::SimilarRtimeParam()}}). The feature groups defined in columns \code{"feature_group"} of \code{featureDefinitions(object)} (for features matching \code{msLevel}) will be used and refined by this method. @@ -174,7 +174,7 @@ table(featureDefinitions(xodg_grp)$feature_group) \seealso{ feature-grouping for a general overview. -Other feature grouping methods: +Other feature grouping methods: \code{\link{groupFeatures-abundance-correlation}}, \code{\link{groupFeatures-similar-rtime}} } diff --git a/man/groupFeatures-similar-rtime.Rd b/man/groupFeatures-similar-rtime.Rd index ea62d7f3..a0c407d2 100644 --- a/man/groupFeatures-similar-rtime.Rd +++ b/man/groupFeatures-similar-rtime.Rd @@ -12,7 +12,7 @@ correspondence results.} \item{param}{\code{SimilarRtimeParam} object with the settings for the method. See -\code{\link[MsFeatures:groupFeatures-similar-rtime]{MsFeatures::SimilarRtimeParam()}} for details and options.} +\code{\link[MsFeatures:SimilarRtimeParam]{MsFeatures::SimilarRtimeParam()}} for details and options.} \item{msLevel}{\code{integer(1)} defining the MS level on which the features should be grouped.} @@ -31,7 +31,7 @@ their retention time which is \code{<=} parameter \code{diffRt} of the parameter are grouped together. If a column \code{"feature_group"} is found in \code{\link[=featureDefinitions]{featureDefinitions()}} this is further sub-grouped by this method. -See \code{\link[MsFeatures:groupFeatures-similar-rtime]{MsFeatures::SimilarRtimeParam()}} in \code{MsFeatures} for more details. +See \code{\link[MsFeatures:SimilarRtimeParam]{MsFeatures::SimilarRtimeParam()}} in \code{MsFeatures} for more details. } \examples{ @@ -62,7 +62,7 @@ xodg_grp <- groupFeatures(xodg, length(unique(featureDefinitions(xodg_grp)$feature_group)) } \seealso{ -Other feature grouping methods: +Other feature grouping methods: \code{\link{groupFeatures-abundance-correlation}}, \code{\link{groupFeatures-eic-similarity}} } diff --git a/man/hidden_aliases.Rd b/man/hidden_aliases.Rd index f8dc51c0..22f13992 100644 --- a/man/hidden_aliases.Rd +++ b/man/hidden_aliases.Rd @@ -2,9 +2,10 @@ % Please edit documentation in R/DataClasses.R, R/XcmsExperiment.R, % R/hidden_aliases.R, R/XcmsExperimentHdf5.R, R/functions-Params.R, % R/methods-MsFeatureData.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R, -% R/methods-ProcessHistory.R, R/methods-XCMSnExp.R, R/methods-XChromatogram.R, -% R/methods-XChromatograms.R, R/methods-xcmsEIC.R, R/methods-xcmsFragments.R, -% R/methods-xcmsPeaks.R, R/methods-xcmsRaw.R, R/methods-xcmsSet.R +% R/methods-ProcessHistory.R, R/methods-XCMSnExp.R, +% R/methods-XChromatogram.R, R/methods-XChromatograms.R, R/methods-xcmsEIC.R, +% R/methods-xcmsFragments.R, R/methods-xcmsPeaks.R, R/methods-xcmsRaw.R, +% R/methods-xcmsSet.R \docType{class} \name{CentWaveParam-class} \alias{CentWaveParam-class} @@ -410,7 +411,7 @@ msLevel = 1L, chunkSize = 2L, isolationWindowTargetMz = NULL, - return.type = c("XChromatograms", "MChromatograms"), + return.type = c("XChromatograms", "MChromatograms", "Chromatograms"), include = character(), chromPeaks = c("apex_within", "any", "none"), BPPARAM = bpparam() @@ -451,12 +452,13 @@ expandMz = 0, aggregationFun = "max", features = character(), - return.type = "XChromatograms", + return.type = c("XChromatograms", "MChromatograms", "Chromatograms"), chunkSize = 2L, mzmin = min, mzmax = max, rtmin = min, rtmax = max, + featureArea = TRUE, ..., progressbar = TRUE, BPPARAM = bpparam() diff --git a/man/highlightChromPeaks.Rd b/man/highlightChromPeaks.Rd index ebc4cb6c..81bdc3b9 100644 --- a/man/highlightChromPeaks.Rd +++ b/man/highlightChromPeaks.Rd @@ -67,8 +67,8 @@ function.} \description{ The \code{highlightChromPeaks()} function adds chromatographic peak definitions to an existing plot, such as one created by the -\code{plot()} method on a \code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}} or -\code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object. +\code{plot()} method on a \code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}} or +\code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object. } \examples{ diff --git a/man/imputeRowMin.Rd b/man/imputeRowMin.Rd index b3999e3e..d4355b49 100644 --- a/man/imputeRowMin.Rd +++ b/man/imputeRowMin.Rd @@ -24,7 +24,7 @@ library(MSnbase) library(faahKO) data("faahko") -xset <- group(faahko) +xset <- xcms::group(faahko) mat <- groupval(xset, value = "into") mat_imp <- imputeRowMin(mat) @@ -38,8 +38,8 @@ head(imputeRowMin(mat, min_fraction = 1/8)) \seealso{ \code{imputeLCMD} package for more left censored imputation functions. -Other imputation functions: -\code{\link{imputeRowMinRand}()} +Other imputation functions: +\code{\link[=imputeRowMinRand]{imputeRowMinRand()}} } \author{ Johannes Rainer diff --git a/man/imputeRowMinRand.Rd b/man/imputeRowMinRand.Rd index 147aebea..f5e43bbe 100644 --- a/man/imputeRowMinRand.Rd +++ b/man/imputeRowMinRand.Rd @@ -69,7 +69,7 @@ library(faahKO) library(MSnbase) data("faahko") -xset <- group(faahko) +xset <- xcms::group(faahko) mat <- groupval(xset, value = "into") ## Estimate the relationship between row sd and mean. The standard deviation @@ -89,8 +89,8 @@ head(mat_imp_fromto) \seealso{ \code{imputeLCMD} package for more left censored imputation functions. -Other imputation functions: -\code{\link{imputeRowMin}()} +Other imputation functions: +\code{\link[=imputeRowMin]{imputeRowMin()}} } \author{ Johannes Rainer, Mar Garcia-Aloy diff --git a/man/manualChromPeaks.Rd b/man/manualChromPeaks.Rd index 10958edb..b1f39a67 100644 --- a/man/manualChromPeaks.Rd +++ b/man/manualChromPeaks.Rd @@ -55,7 +55,7 @@ manualFeatures(object, ...) \S4method{manualFeatures}{XCMSnExp}(object, peakIdx = list(), msLevel = 1L) } \arguments{ -\item{object}{\link{XcmsExperiment}, \link{XCMSnExp} or \link[MSnbase:OnDiskMSnExp-class]{MSnbase::OnDiskMSnExp} object.} +\item{object}{\link{XcmsExperiment}, \link{XCMSnExp} or \link[MSnbase:OnDiskMSnExp]{MSnbase::OnDiskMSnExp} object.} \item{...}{ignored.} @@ -84,7 +84,7 @@ using 4 CPUs (separate processes) but using \verb{chunkSize = }1\verb{will not p the total number of samples in an experiment will load the full MS data into memory and will thus in most settings cause an out-of-memory error.} -\item{BPPARAM}{parallel processing settings (see \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} +\item{BPPARAM}{parallel processing settings (see \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for details).} \item{peakIdx}{For \code{manualFeatures}: \code{list} of \code{integer} vectors with the diff --git a/man/peaksWithCentWave.Rd b/man/peaksWithCentWave.Rd index 189b6c22..16d634f4 100644 --- a/man/peaksWithCentWave.Rd +++ b/man/peaksWithCentWave.Rd @@ -134,8 +134,8 @@ rect(xleft = pks[, "rtmin"], xright = pks[, "rtmax"], \link{centWave} for a detailed description of the peak detection method. -Other peak detection functions for chromatographic data: -\code{\link{peaksWithMatchedFilter}()} +Other peak detection functions for chromatographic data: +\code{\link[=peaksWithMatchedFilter]{peaksWithMatchedFilter()}} } \author{ Johannes Rainer diff --git a/man/peaksWithMatchedFilter.Rd b/man/peaksWithMatchedFilter.Rd index ca3b4f8a..d38638b5 100644 --- a/man/peaksWithMatchedFilter.Rd +++ b/man/peaksWithMatchedFilter.Rd @@ -76,8 +76,8 @@ rect(xleft = pks[, "rtmin"], xright = pks[, "rtmax"], ybottom = c(0, 0), \link{matchedFilter} for a detailed description of the peak detection method. -Other peak detection functions for chromatographic data: -\code{\link{peaksWithCentWave}()} +Other peak detection functions for chromatographic data: +\code{\link[=peaksWithCentWave]{peaksWithCentWave()}} } \author{ Johannes Rainer diff --git a/man/plotChromatogramsOverlay.Rd b/man/plotChromatogramsOverlay.Rd index d2677170..fe42d434 100644 --- a/man/plotChromatogramsOverlay.Rd +++ b/man/plotChromatogramsOverlay.Rd @@ -39,7 +39,7 @@ ) } \arguments{ -\item{object}{\code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} or \code{\link[=XChromatograms]{XChromatograms()}} object.} +\item{object}{\code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} or \code{\link[=XChromatograms]{XChromatograms()}} object.} \item{col}{definition of the color in which the chromatograms should be drawn. Can be of length 1 or equal to \code{nrow(object)} to plot each @@ -103,7 +103,7 @@ each EIC. \code{plotOverlay} draws chromatographic peak data from multiple (different) extracted ion chromatograms (EICs) into the same plot. This allows to directly compare the peak shape of these EICs in the same sample. In -contrast to the \code{plot} function for \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}} object, +contrast to the \code{plot} function for \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}} object, which draws the data from the same EIC across multiple samples in the same plot, this function draws the different EICs from the same sample into the same plot. diff --git a/man/plotQC.Rd b/man/plotQC.Rd index af8ff61c..a386469d 100644 --- a/man/plotQC.Rd +++ b/man/plotQC.Rd @@ -40,7 +40,7 @@ For the m/z deviations, the median of all m/z withon one group are assumed. } \examples{ library(faahKO) -xsg <- group(faahko) +xsg <- xcms::group(faahko) plotQC(xsg, what="mzdevhist") plotQC(xsg, what="rtdevhist") diff --git a/man/profMat-xcmsSet.Rd b/man/profMat-xcmsSet.Rd index 2acfc79c..5ba64f13 100644 --- a/man/profMat-xcmsSet.Rd +++ b/man/profMat-xcmsSet.Rd @@ -70,7 +70,7 @@ that should be used.} the MS level from which the profile matrix should be generated.} \item{BPPARAM}{For \code{MsExperiment} or \code{XcmsExperiment}: parallel processing -setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for more details. Defaults to +setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more details. Defaults to \code{BPPARAM = bpparam()}.} \item{...}{ignored.} diff --git a/man/reconstructChromPeakSpectra.Rd b/man/reconstructChromPeakSpectra.Rd index 8e0d7ce4..917a33dd 100644 --- a/man/reconstructChromPeakSpectra.Rd +++ b/man/reconstructChromPeakSpectra.Rd @@ -58,7 +58,7 @@ be used as \code{precursorIntensity} of the resulting spectra.} \code{chromPeaks}) of MS1 peaks for which MS2 spectra should be reconstructed. By default they are reconstructed for all MS1 chromatographic peaks.} -\item{BPPARAM}{parallel processing setup. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}} +\item{BPPARAM}{parallel processing setup. See \code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for more information.} \item{return.type}{\code{character(1)} defining the type of the returned object. @@ -73,8 +73,8 @@ empty spectra (i.e. without m/z and intensity values) for MS1 peaks for which reconstruction was not possible (either no MS2 signal was recorded or the correlation of the MS2 chromatographic peaks with the MS1 chromatographic peak was below threshold \code{minCor}. Spectra variables -\code{"ms2_peak_id"} and \code{"ms2_peak_cor"} (of type \code{\link[IRanges:AtomicList-class]{IRanges::CharacterList()}} -and \code{\link[IRanges:AtomicList-class]{IRanges::NumericList()}} with length equal to the number of peaks per +\code{"ms2_peak_id"} and \code{"ms2_peak_cor"} (of type \code{\link[IRanges:CharacterList]{IRanges::CharacterList()}} +and \code{\link[IRanges:NumericList]{IRanges::NumericList()}} with length equal to the number of peaks per reconstructed MS2 spectrum) providing the IDs and the correlation of the MS2 chromatographic peaks from which the MS2 spectrum was reconstructed. As retention time the median retention times of all MS2 chromatographic diff --git a/man/refineChromPeaks.Rd b/man/refineChromPeaks.Rd index 4d5303bc..a6b5b740 100644 --- a/man/refineChromPeaks.Rd +++ b/man/refineChromPeaks.Rd @@ -90,7 +90,7 @@ into memory and will thus in most settings cause an out-of-memory error.} \item{BPPARAM}{parameter object to set up parallel processing. Uses the default parallel processing setup returned by \code{bpparam()}. See -\code{\link[BiocParallel:register]{BiocParallel::bpparam()}} for details and examples.} +\code{\link[BiocParallel:bpparam]{BiocParallel::bpparam()}} for details and examples.} \item{maxPeakwidth}{For \code{CleanPeaksParam}: \code{numeric(1)} defining the maximal allowed peak width (in retention time).} diff --git a/man/removeIntensity-Chromatogram.Rd b/man/removeIntensity-Chromatogram.Rd index 43ef434b..d6890e53 100644 --- a/man/removeIntensity-Chromatogram.Rd +++ b/man/removeIntensity-Chromatogram.Rd @@ -20,7 +20,7 @@ } \arguments{ \item{object}{an object representing chromatographic data. Can be a -\code{\link[MSnbase:Chromatogram-class]{MSnbase::Chromatogram()}}, \code{\link[MSnbase:MChromatograms-class]{MSnbase::MChromatograms()}}, +\code{\link[MSnbase:Chromatogram]{MSnbase::Chromatogram()}}, \code{\link[MSnbase:MChromatograms]{MSnbase::MChromatograms()}}, \code{\link[=XChromatogram]{XChromatogram()}} or \code{\link[=XChromatograms]{XChromatograms()}} object.} \item{which}{\code{character(1)} defining the condition to remove intensities. @@ -37,7 +37,7 @@ the input object with matching intensities being replaced by \code{NA}. matching certain conditions (depending on parameter \code{which}). The intensities are actually not \emph{removed} but replaced with \code{NA_real_}. To actually \strong{remove} the intensities (and the associated retention times) -use \code{\link[MSnbase:clean-methods]{MSnbase::clean()}} afterwards. +use \code{\link[MSnbase:clean]{MSnbase::clean()}} afterwards. Parameter \code{which} allows to specify which intensities should be replaced by \code{NA_real_}. By default (\code{which = "below_threshod"} intensities below diff --git a/man/useOriginalCode.Rd b/man/useOriginalCode.Rd index 471a70fb..58dd34c7 100644 --- a/man/useOriginalCode.Rd +++ b/man/useOriginalCode.Rd @@ -31,7 +31,7 @@ matchedFilter settings with a very small bin size. } \note{ For parallel processing using the SOCKS method (e.g. by -\code{\link[BiocParallel:SnowParam-class]{BiocParallel::SnowParam()}} on +\code{\link[BiocParallel:SnowParam]{BiocParallel::SnowParam()}} on Windows computers) this option might not be passed to the individual R processes performing the calculations. In such cases it is suggested to specify the option manually and system-wide by adding the line diff --git a/tests/testthat/test_MsExperiment-functions.R b/tests/testthat/test_MsExperiment-functions.R index e74db223..c6c80743 100644 --- a/tests/testthat/test_MsExperiment-functions.R +++ b/tests/testthat/test_MsExperiment-functions.R @@ -248,17 +248,17 @@ test_that(".mse_obiwarp_chunks works", { expect_error(.mse_obiwarp_chunks(mse, p, msLevel = 2), "MS level") }) -test_that(".mse_chromatogram works", { +test_that(".mse_mchromatograms_for_ranges works", { rtr <- rbind(c(2600, 2630), c(3500, 3600)) mzr <- rbind(c(250, 252), c(400, 410)) - res <- .mse_chromatogram(mse, rt = rtr, mz = mzr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges(mse, rt = rtr, mz = mzr, msLevel = 1L) expect_s4_class(res, "MChromatograms") expect_equal(ncol(res), length(mse)) expect_equal(nrow(res), 2) expect_true(validObject(res)) - expect_error(.mse_chromatogram( + expect_error(.mse_mchromatograms_for_ranges( mse, mz = mzr, rt = cbind(c(300, 310), c(123, NA))), "Missing values") @@ -267,13 +267,13 @@ test_that(".mse_chromatogram works", { expect_equal(unname(intensity(ref[2, 3])), intensity(res[2, 3])) ## aggregationFun passed correctly - res_2 <- .mse_chromatogram(mse, rt = rtr, mz = mzr, msLevel = 1L, - aggregationFun = "max") + res_2 <- .mse_mchromatograms_for_ranges( + mse, rt = rtr, mz = mzr, msLevel = 1L, aggregationFun = "max") expect_true(all(intensity(res[1, 1]) > intensity(res_2[1, 1]))) expect_true(all(intensity(res[2, 2]) > intensity(res_2[2, 2]))) ## MS Level 2 - res <- .mse_chromatogram(mse, rt = rtr, mz = mzr, msLevel = 2L) + res <- .mse_mchromatograms_for_ranges(mse, rt = rtr, mz = mzr, msLevel = 2L) expect_s4_class(res, "MChromatograms") expect_equal(ncol(res), length(mse)) expect_equal(nrow(res), 2) @@ -282,7 +282,7 @@ test_that(".mse_chromatogram works", { ## rt, mz out of range rtr <- rbind(c(20, 30), c(34, 45)) - res <- .mse_chromatogram(mse, rt = rtr, mz = mzr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges(mse, rt = rtr, mz = mzr, msLevel = 1L) expect_s4_class(res, "MChromatograms") expect_equal(ncol(res), length(mse)) expect_equal(nrow(res), 2) @@ -290,7 +290,7 @@ test_that(".mse_chromatogram works", { expect_equal(intensity(res[1, 2]), numeric()) rtr <- rbind(c(20, 30), c(3500, 3600)) - res <- .mse_chromatogram(mse, rt = rtr, mz = mzr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges(mse, rt = rtr, mz = mzr, msLevel = 1L) expect_s4_class(res, "MChromatograms") expect_equal(ncol(res), length(mse)) expect_equal(nrow(res), 2) @@ -309,7 +309,8 @@ test_that(".mse_chromatogram works", { ## sample 2: 0 - 899 rtr <- rbind(c(13, 20), c(2900, 3010)) mzr <- rbind(c(220, 240), c(220, 240)) - res <- xcms:::.mse_chromatogram(mse_rt, rt = rtr, mz = mzr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges( + mse_rt, rt = rtr, mz = mzr, msLevel = 1L) expect_s4_class(res, "MChromatograms") expect_equal(ncol(res), 2L) expect_equal(nrow(res), 2L) @@ -327,11 +328,13 @@ test_that(".mse_chromatogram works", { c(500, 510)) rtr <- rbind(c(200, 220), c(500, 520)) - res <- .mse_chromatogram(mse_dda, rt = rtr, mz = mzr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges( + mse_dda, rt = rtr, mz = mzr, msLevel = 1L) expect_true(validObject(res)) expect_true(all(intensity(res[[1L]]) > 0)) expect_true(all(intensity(res[[2L]]) > 0, na.rm = TRUE)) - res <- .mse_chromatogram(mse_dda, rt = rtr, mz = mzr, msLevel = 2L) + res <- .mse_mchromatograms_for_ranges( + mse_dda, rt = rtr, mz = mzr, msLevel = 2L) expect_true(validObject(res)) expect_equal(msLevel(res[[1L]]), 2L) expect_true(length(intensity(res[[1L]])) > 0) @@ -345,14 +348,15 @@ test_that(".mse_chromatogram works", { c(81, 83)) rtr <- rbind(c(10, 700), c(10, 700)) - res <- .mse_chromatogram(mse_dda, rt = rtr, mz = mzr, msLevel = 2L) - res2 <- .mse_chromatogram(mse_dda, rt = rtr, mz = mzr, msLevel = 2L, - isolationWindow = c(56, 40)) + res <- .mse_mchromatograms_for_ranges( + mse_dda, rt = rtr, mz = mzr, msLevel = 2L) + res2 <- .mse_mchromatograms_for_ranges( + mse_dda, rt = rtr, mz = mzr, msLevel = 2L, isolationWindow = c(56, 40)) expect_true(all(intensity(res2[[1L]]) > 0)) expect_true(length(intensity(res2[[2L]])) == 0) expect_true(length(rtime(res[[1L]])) > length(rtime(res2[[1L]]))) - res2 <- .mse_chromatogram(mse_dda, rt = rtr, mz = mzr, msLevel = 2L, - isolationWindow = c(56, 82)) + res2 <- .mse_mchromatograms_for_ranges( + mse_dda, rt = rtr, mz = mzr, msLevel = 2L, isolationWindow = c(56, 82)) expect_true(all(intensity(res2[[1L]]) > 0)) expect_true(length(intensity(res[[1L]])) > length(intensity(res2[[1L]]))) expect_true(all(intensity(res[[2L]]) > 0, na.rm = TRUE)) @@ -361,7 +365,8 @@ test_that(".mse_chromatogram works", { mse_dia <- readMsExperiment(pest_mix_swath_file) mzr <- rbind(c(100, 110), c(500, 510)) - res <- .mse_chromatogram(mse_dia, mz = mzr, rt = rtr, msLevel = 1L) + res <- .mse_mchromatograms_for_ranges( + mse_dia, mz = mzr, rt = rtr, msLevel = 1L) expect_equal(msLevel(res[[1L]]), 1L) expect_equal(msLevel(res[[2L]]), 1L) expect_true(length(intensity(res[[1L]])) > 0) @@ -369,14 +374,94 @@ test_that(".mse_chromatogram works", { mzr <- rbind(c(40, 200), c(40, 200)) - res <- .mse_chromatogram(mse_dia, mz = mzr, rt = rtr, msLevel = 2L, - isolationWindow = c(163.75, 367.35)) + res <- .mse_mchromatograms_for_ranges( + mse_dia, mz = mzr, rt = rtr, msLevel = 2L, + isolationWindow = c(163.75, 367.35)) expect_equal(msLevel(res[[1L]]), 2L) expect_equal(msLevel(res[[2L]]), 2L) expect_true(all(intensity(res[[1L]]) > 0)) expect_true(all(intensity(res[[2L]]) > 0)) }) +test_that(".mse_chromatograms_for_ranges works", { + rtr <- rbind(c(2600, 2630), c(3500, 3600)) + mzr <- rbind(c(250, 252), c(400, 410)) + + ## TIC + res <- .mse_chromatograms_for_ranges(mse) + expect_s4_class(res, "Chromatograms") + expect_equal(length(res), length(mse)) + ref <- chromatogram(mse) + expect_equal(intensity(res), lapply(ref, intensity)) + ## BPC + res <- .mse_chromatograms_for_ranges(mse, aggregationFun = "max") + ref <- chromatogram(mse, aggregationFun = "max") + expect_equal(intensity(res), lapply(ref, intensity)) + + ## EIC + res <- .mse_chromatograms_for_ranges(mse, rt = rtr, mz = mzr) + ref <- chromatogram(mse, rt = rtr, mz = mzr) + res <- split(res, dataOrigin(res)) + expect_equal(intensity(res[[1L]]), lapply(ref[, 1L], intensity)) + expect_equal(intensity(res[[2L]]), lapply(ref[, 2L], intensity)) + expect_equal(intensity(res[[3L]]), lapply(ref[, 3L], intensity)) +}) + +test_that(".chrom_data_for_ranges works", { + res <- .chrom_data_for_ranges(rt = matrix(ncol = 2, nrow = 0)) + expect_equal(res, data.frame()) + + res <- .chrom_data_for_ranges(rt = cbind(c(1, 2, 3), c(2, 3, 4)), + mz = cbind(c(3, 4, 5), c(6, 7, 8)), + c("a", "b", "c", "d", "e")) + expect_true(is.data.frame(res)) + expect_equal(colnames(res), c("rtMin", "rtMax", "mzMin", "mzMax", + "dataOrigin", "msLevel")) + expect_equal(res$rtMin, rep(1:3, each = 5)) + expect_equal(res$dataOrigin, rep(c("a", "b", "c", "d", "e"), 3)) + + res <- .chrom_data_for_ranges(rt = cbind(c(1, 2, 3), c(2, 3, 4)), + mz = cbind(c(3, 4, 5), c(6, 7, 8)), + c("a", "b", "c", "d", "e"), + isolationWindowTargetMz = c(2, 3, 4)) + expect_equal(res$isolationWindowTargetMz, rep(c(2, 3, 4), each = 5)) +}) + +test_that(".mse_chromatograms_for_peaks works", { + pks <- chromPeaks(xmse)[1:10, ] + pkd <- chromPeakData(xmse, return.type = "data.frame")[1:10, ] + + res <- .mse_chromatograms_for_peaks( + mse, pks, pkd, expandRt = 10, expandMz = 1) + expect_s4_class(res, "Chromatograms") + expect_equal(length(res), nrow(pks)) + expect_true(all(dataOrigin(res) == fileNames(mse)[1L])) + expect_true(all(vapply(rtime(res), min, NA_real_) >= pks[, "rtmin"] - 10)) + expect_true(all(vapply(rtime(res), max, NA_real_) <= pks[, "rtmax"] + 10)) + + ## Empty matrices. + res <- .mse_chromatograms_for_peaks( + mse, pks[integer(), ], pkd[integer(), ], expandRt = 10, expandMz = 1) + expect_s4_class(res, "Chromatograms") + expect_true(length(res) == 0) +}) + +test_that(".mse_mchromatograms_for_peaks works", { + pks <- chromPeaks(xmse)[1:10, ] + pkd <- chromPeakData(xmse, return.type = "data.frame")[1:10, ] + + res <- .mse_mchromatograms_for_peaks( + mse, pks, pkd, expandRt = 10, expandMz = 1) + expect_s4_class(res, "MChromatograms") + expect_equal(nrow(res), nrow(pks)) + expect_equal(ncol(res), 1L) + expect_equal(rownames(res), rownames(pks)) + expect_true(all(vapply(res, function(z) min(rtime(z)), NA_real_) >= + pks[, "rtmin"] - 10)) + expect_true(all(vapply(res, function(z) max(rtime(z)), NA_real_) <= + pks[, "rtmax"] + 10)) +}) + test_that(".mse_split_spectra_variable works", { ## MS level - results should be the same. res <- .mse_split_spectra_variable(mse, msLevel(spectra(mse))) diff --git a/tests/testthat/test_MsExperiment.R b/tests/testthat/test_MsExperiment.R index ed4c29ee..302f7ab7 100644 --- a/tests/testthat/test_MsExperiment.R +++ b/tests/testthat/test_MsExperiment.R @@ -75,6 +75,11 @@ test_that("chromatogram,MsExperiment works", { expect_equal(intensity(res[1, 2]), unname(intensity(ref[1, 2]))) expect_equal(intensity(res[1, 3]), unname(intensity(ref[1, 3]))) + ## Chromatograms + res2 <- chromatogram(mse, return.type = "Chromatograms") + expect_s4_class(res2, "Chromatograms") + expect_equal(intensity(res2), lapply(res, intensity)) + ## Subset. res <- chromatogram(mse, rt = c(10, 3000)) expect_s4_class(res, "MChromatograms") @@ -82,6 +87,10 @@ test_that("chromatogram,MsExperiment works", { expect_equal(1L, nrow(res)) expect_true(all(rtime(res[1, 1]) <= 3000)) + res2 <- chromatogram(mse, rt = c(10, 3000), return.type = "Chromatograms") + expect_s4_class(res2, "Chromatograms") + expect_equal(intensity(res2), lapply(res, intensity)) + res <- chromatogram(mse, msLevel = 2L) expect_s4_class(res, "MChromatograms") expect_equal(length(mse), ncol(res)) @@ -90,10 +99,25 @@ test_that("chromatogram,MsExperiment works", { expect_equal(intensity(res[1, 2]), numeric()) expect_equal(intensity(res[1, 2]), numeric()) + res2 <- chromatogram(mse, msLevel = 2L, return.type = "Chromatograms") + expect_s4_class(res2, "Chromatograms") + expect_true(length(res2) == 0) + res <- chromatogram(mse, rt = rbind(c(3000, 3500), c(4000, 4500))) expect_equal(nrow(res), 2) + res2 <- chromatogram(mse, rt = rbind(c(3000, 3500), c(4000, 4500)), + return.type = "Chromatograms") + expect_equal(length(res2), 2 * length(mse)) + expect_equal(intensity(res2[1:3]), lapply(res[1L, ], intensity)) + expect_equal(intensity(res2[4:6]), lapply(res[2L, ], intensity)) + res <- chromatogram(mse, mz = rbind(c(200, 210), c(330, 331))) expect_equal(nrow(res), 2) + res2 <- chromatogram(mse, mz = rbind(c(200, 210), c(330, 331)), + return.type = "Chromatograms") + expect_equal(length(res2), 2 * length(mse)) + expect_equal(intensity(res2[1:3]), lapply(res[1L, ], intensity)) + expect_equal(intensity(res2[4:6]), lapply(res[2L, ], intensity)) }) test_that("uniqueMsLevels,MsExperiment works", { diff --git a/tests/testthat/test_XcmsExperiment.R b/tests/testthat/test_XcmsExperiment.R index 9120c143..2d14fff5 100644 --- a/tests/testthat/test_XcmsExperiment.R +++ b/tests/testthat/test_XcmsExperiment.R @@ -59,6 +59,11 @@ test_that("findChromPeaks,MsExperiment et al works", { expect_s4_class(chromPeakData(xmse), "DataFrame") expect_true(nrow(chromPeakData(xmse, 2:3)) == 0) expect_true(is.integer(chromPeakData(res)$ms_level)) + ## chromPeakData<- + expect_no_error(chromPeakData(res) <- xmse@chromPeakData) + expect_equal(res@chromPeakData, xmse@chromPeakData) + expect_no_error(chromPeakData(res) <- chromPeakData(res)) + expect_equal(res@chromPeakData, xmse@chromPeakData) ## dropChromPeaks rres <- dropChromPeaks(res) @@ -1352,6 +1357,11 @@ test_that("chromatogram,XcmsExperiment and .xmse_extract_chromatograms_old", { ref <- chromatogram(xod_x, mz = mzr, rt = rtr) expect_equal(chromPeaks(res), chromPeaks(ref)) + res2 <- chromatogram(xmse, mz = mzr, rt = rtr, + return.type = "Chromatograms") + expect_s4_class(res2, "Chromatograms") + expect_equal(intensity(res2[1:3]),lapply(res[1,], intensity)) + ## Multiple rows. res <- .xmse_extract_chromatograms_old( xmse, mz = chromPeaks(xmse)[1:10, c("mzmin", "mzmax")], @@ -1398,6 +1408,16 @@ test_that("chromatogram,XcmsExperiment and .xmse_extract_chromatograms_old", { ## have more data points without isolation windows expect_true(length(intensity(res[[1L]])) > length(intensity(res2[[1L]]))) + b <- chromatogram(mse_dia, msLevel = 2L, mz = c(50, 300), + rt = c(100, 600), return.type = "Chromatograms") + expect_s4_class(b, "Chromatograms") + expect_equal(intensity(b), lapply(res, intensity)) + b <- chromatogram(mse_dia, msLevel = 2L, mz = c(50, 300), + rt = c(100, 600), isolationWindowTargetMz = 270.85, + return.type = "Chromatograms") + expect_s4_class(b, "Chromatograms") + expect_equal(intensity(b), lapply(res2, intensity)) + ## fake MS2 data with undefined isolation window. a <- chromatogram(xmseg, msLevel = 1L, mz = chromPeaks(xmse)[1:5, c("mzmin", "mzmax")], @@ -1630,6 +1650,15 @@ test_that("chromPeaksChromatograms,XcmsExperiment works", { expect_error(chromPeakChromatograms(xmse, peaks = 1:3), "expected to") chrs <- chromPeakChromatograms(xmse) + expect_s4_class(chrs, "XChromatograms") + b <- chromPeakChromatograms(xmse, return.type = "MChromatograms") + expect_s4_class(b, "MChromatograms") + c <- chromPeakChromatograms(xmse, return.type = "Chromatograms") + expect_s4_class(c, "Chromatograms") + expect_equal(nrow(chrs), nrow(b)) + expect_equal(nrow(chrs), length(c)) + expect_equal(intensity(c), lapply(b, intensity)) + expect_equal(c$chrom_peak_id, rownames(chromPeaks(xmse))) ## Test providing peaks. Only those from one file. pks <- rownames(chromPeaks(xmse)[chromPeaks(xmse)[, "sample"] == 2, ]) @@ -1640,6 +1669,12 @@ test_that("chromPeaksChromatograms,XcmsExperiment works", { expect_equal(fData(ref), fData(res)) expect_equal(chromPeaks(ref), chromPeaks(res)) + b <- chromPeakChromatograms(xmse, peaks = pks, return.type ="Chromatograms") + expect_s4_class(b, "Chromatograms") + expect_equal(pks, b$chrom_peak_id) + expect_equal(intensity(b), lapply(res, intensity)) + expect_equal(unique(dataOrigin(b)), fileNames(xmse)[2L]) + ## Test providing peaks. different order. pks <- sample(rownames(chromPeaks(xmseg)), 10) res <- chromPeakChromatograms(xmseg, peaks = pks) @@ -1648,16 +1683,26 @@ test_that("chromPeaksChromatograms,XcmsExperiment works", { expect_equal(fData(res), fData(ref)) expect_equal(chromPeaks(res), chromPeaks(ref)) + b <- chromPeakChromatograms(xmse, peaks = pks, return.type ="Chromatograms") + expect_s4_class(b, "Chromatograms") + expect_equal(pks, b$chrom_peak_id) + expect_equal(intensity(b), lapply(res, intensity)) + ## Test on a SWATH data set: are MS1 and MS2 chrom peaks extracted ## correctly? cwp <- CentWaveParam(snthresh = 5, noise = 100, ppm = 10, peakwidth = c(3, 20), prefilter = c(3, 1000)) xmse_dia <- findChromPeaks(mse_dia, param = cwp) - xmse_dia <- findChromPeaksIsolationWindow(xmse_dia, param = cwp) + expect_warning( + xmse_dia <- findChromPeaksIsolationWindow(xmse_dia, param = cwp)) res <- chromPeakChromatograms(xmse_dia) ## To compare against what? ints <- vapply(res, function(z) sum(intensity(z), na.rm = TRUE), numeric(1)) expect_true(cor(chromPeaks(res)[, "into"], ints) >= 0.97) + + b <- chromPeakChromatograms(xmse_dia, return.type = "Chromatograms") + expect_s4_class(b, "Chromatograms") + expect_equal(length(b), nrow(res)) }) test_that("setAs,XcmsExperiment,xcmsSet works", { @@ -1749,3 +1794,86 @@ test_that("chromPeakData,XcmsExperiment works with parameter columns", { expect_error(chromPeakData(xmse, columns = "a"), "valid column") }) + +test_that("featureChromatograms,XcmsExperiment without featureArea works", { + ## Compare against chromPeakChromatograms + a <- featureChromatograms(xmseg, return.type = "Chromatograms", + expandRt = 2, featureArea = FALSE) + ref <- chromPeakChromatograms(xmseg, return.type = "Chromatograms", + expandRt = 2) + cp <- rownames(chromPeaks(xmseg))[unlist(featureDefinitions(xmseg)$peakidx)] + expect_equal(a$chrom_peak_id, cp) + i <- match(a$chrom_peak_id, ref$chrom_peak_id) + ref <- ref[i] + expect_equal(intensity(ref), intensity(a)) + + ## Selected features. + a <- featureChromatograms(xmseg, return.type = "Chromatograms", + features = c("FT03", "FT01", "FT03"), + featureArea = FALSE) + cp <- rownames(chromPeaks(xmseg))[ + unlist(featureDefinitions(xmseg)[c("FT03", "FT01", "FT03"), ]$peakidx)] + expect_equal(a$chrom_peak_id, cp) + ref <- chromPeakChromatograms(xmseg, return.type = "Chromatograms", + peaks = cp) + expect_equal(ref$chrom_peak_id, cp) + expect_equal(ref$chrom_peak_id, a$chrom_peak_id) + expect_equal(intensity(ref), intensity(a)) +}) + +test_that("featureChromatograms,XcmsExperiment different return.type works", { + a <- featureChromatograms(xmseg, return.type = "MChromatograms") + expect_s4_class(a, "MChromatograms") + expect_equal(nrow(a), nrow(featureDefinitions(xmseg))) + expect_equal(ncol(a), length(xmseg)) + expect_equal(fData(a)$feature_id, rownames(featureDefinitions(xmseg))) + + b <- featureChromatograms(xmseg, return.type = "XChromatograms") + expect_s4_class(b, "XChromatograms") + expect_equal(nrow(b), nrow(featureDefinitions(xmseg))) + expect_equal(ncol(b), length(xmseg)) + expect_equal(fData(b)$feature_id, rownames(featureDefinitions(xmseg))) + expect_equal(lapply(a[1, ], intensity), lapply(b[1, ], intensity)) + + c <- featureChromatograms(xmseg, return.type = "Chromatograms") + expect_s4_class(c, "Chromatograms") + expect_equal(length(c), length(xmseg) * nrow(featureDefinitions(xmseg))) + expect_equal(lapply(a[1, ], intensity), intensity(c[1:3])) + expect_equal(lapply(a[2, ], intensity), intensity(c[4:6])) + + fts <- rownames(featureDefinitions(xmseg))[c(4, 1, 23, 4)] + a <- featureChromatograms(xmseg, return.type = "MChromatograms", + features = fts, expandRt = 3) + expect_equal(nrow(a), 4) + expect_equal(fData(a)$feature_id, fts) + expect_equal(lapply(a[1, ], intensity), lapply(a[4, ], intensity)) + + b <- featureChromatograms(xmseg, return.type = "XChromatograms", + features = fts, expandRt = 3) + expect_equal(nrow(b), 4) + expect_equal(fData(b)$feature_id, fts) + expect_equal(lapply(a[2, ], intensity), lapply(b[2, ], intensity)) + + c <- featureChromatograms(xmseg, return.type = "Chromatograms", + features = fts, expandRt = 3) + expect_s4_class(c, "Chromatograms") + expect_equal(length(c), length(xmseg) * length(fts)) + expect_equal(c$feature_id, rep(fts, each = 3)) + expect_equal(lapply(a[2, ], intensity), intensity(c[4:6])) + expect_equal(intensity(c[1:3]), intensity(c[10:12])) +}) + +test_that("featureChromPeaks works", { + ref <- featureDefinitions(xmseg) + res <- featureChromPeaks(xmseg) + expect_true(is.data.frame(res)) + expect_equal(colnames(res), c("feature_id", "chrom_peak_id")) + expect_equal(res$feature_id, rep(rownames(ref), lengths(ref$peakidx))) + expect_equal(res$chrom_peak_id, + rownames(chromPeaks(xmseg))[unlist(ref$peakidx)]) +}) + +test_that("featurePeakidx works", { + expect_equal(unname(featurePeakidx(xmseg)), + featureDefinitions(xmseg)$peakidx) +}) diff --git a/tests/testthat/test_XcmsExperimentHdf5.R b/tests/testthat/test_XcmsExperimentHdf5.R index aa8f8180..819b1ee8 100644 --- a/tests/testthat/test_XcmsExperimentHdf5.R +++ b/tests/testthat/test_XcmsExperimentHdf5.R @@ -59,6 +59,10 @@ test_that("chromPeaks,XcmsExperiementHdf5 works", { expect_equal(colnames(res), c("mz", "mzmin", "mzmax", "sample")) expect_equal(unname(res), unname(ref[, c("mz","mzmin","mzmax","sample")])) + res2 <- chromPeaks(a, msLevel = 1, columns = c("mz", "mzmin", "mzmax", + "sample")) + expect_equal(res, res2) + ## providing mz and rt res <- chromPeaks(a, msLevel = 1, type = "apex_within", rt = c(2500, 2600)) expect_true(all(res[, "rt"] > 2500)) @@ -99,7 +103,7 @@ test_that("findChromPeaks,XcmsExperimentHdf5 works", { a <- as(xmse_h5, "MsExperiment") a <- as(a, "XcmsExperimentHdf5") h5_file <- tempfile() - xcms:::.h5_initialize_file(h5_file) + .h5_initialize_file(h5_file) a@hdf5_file <- h5_file a@sample_id <- c("S1", "S2", "S3") p <- xmse_h5@processHistory[[1L]]@param @@ -150,7 +154,7 @@ test_that("dropChromPeaks,XcmsExperimentHdf5 works", { ## With features tmpf <- tempfile() ref <- loadXcmsData("xmse") - x <- xcms:::.xcms_experiment_to_hdf5(ref, tmpf) + x <- .xcms_experiment_to_hdf5(ref, tmpf) expect_true(hasChromPeaks(x)) expect_true(hasAdjustedRtime(x)) expect_true(hasFeatures(x)) @@ -162,7 +166,7 @@ test_that("dropChromPeaks,XcmsExperimentHdf5 works", { file.remove(tmpf) tmpf <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(ref, tmpf) + x <- .xcms_experiment_to_hdf5(ref, tmpf) res <- dropChromPeaks(x, keepAdjustedRtime = TRUE) expect_false(hasChromPeaks(res)) expect_true(hasAdjustedRtime(res)) @@ -179,14 +183,14 @@ test_that("refineChromPeaks,XcmsExperimentHdf5,MergeNeighboringPeaksParam", { af <- tempfile() ref <- loadXcmsData("faahko_sub2") - a <- xcms:::.xcms_experiment_to_hdf5(ref, af) + a <- .xcms_experiment_to_hdf5(ref, af) res <- refineChromPeaks(a, MergeNeighboringPeaksParam()) expect_error(validObject(a)) expect_true(validObject(res)) ## Compare results from both. Need chromPeaks() function first. ref <- refineChromPeaks(ref, MergeNeighboringPeaksParam()) ref_pks <- chromPeaks(ref) - res_pks <- xcms:::.h5_read_data(res@hdf5_file, id = res@sample_id, + res_pks <- .h5_read_data(res@hdf5_file, id = res@sample_id, ms_level = rep(1L, length(res)), read_colnames = TRUE, read_rownames = TRUE) res_pks <- do.call( @@ -215,7 +219,7 @@ test_that("groupChromPeaks,featureDefinitions,XcmsExperimentHdf5 works", { expect_true(hasFeatures(x, 1L)) expect_false(hasFeatures(x, 2L)) expect_false(hasFeatures(x, 1:2)) - a <- xcms:::.h5_read_data_frame("/features/ms_1/feature_definitions", + a <- .h5_read_data_frame("/features/ms_1/feature_definitions", x@hdf5_file, read_rownames = TRUE) ref <- featureDefinitions(loadXcmsData("xmse")) ref$peakidx <- NULL @@ -224,7 +228,7 @@ test_that("groupChromPeaks,featureDefinitions,XcmsExperimentHdf5 works", { rownames(ref) <- NULL expect_true(all(colnames(ref) %in% colnames(a))) expect_equal(ref, a[, colnames(ref)]) - pks <- xcms:::.h5_chrom_peaks(x, msLevel = 1L) + pks <- .h5_chrom_peaks(x, msLevel = 1L) for (i in seq_along(pks)) { b <- .h5_read_matrix(paste0("/S", i, "/ms_1/feature_to_chrom_peaks"), x@hdf5_file) @@ -254,7 +258,7 @@ test_that("hasFeatures,XcmsExperimentHdf5 works", { test_that("dropFeatureDefinitions,XcmsExperimentHdf5 works", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) expect_true(hasFeatures(x)) expect_true(hasAdjustedRtime(x)) expect_true(hasFilledChromPeaks(x)) @@ -292,19 +296,19 @@ test_that("featureValues,XcmsExperimentHdf5 etc works", { nf <- nrow(b) rtmed <- b$rtmed ## .h5_feature_values_sample - a <- xcms:::.h5_feature_values_sample( + a <- .h5_feature_values_sample( xmseg_full_h5@hdf5_file, sample_id = "S1", ms_level = 1L, n_features = nf, method = "sum", filled = FALSE, col_idx = 9L) b <- unname(featureValues(ref, method = "sum", value = "maxo", filled = FALSE)[, 1L]) expect_equal(a, b) - a <- xcms:::.h5_feature_values_sample( + a <- .h5_feature_values_sample( xmseg_full_h5@hdf5_file, sample_id = "S4", ms_level = 1L, n_features = nf, filled = FALSE, method = "maxint", col_idx = c(7L, 9L)) b <- unname(featureValues(ref, method = "maxint", value = "into", filled = FALSE, intensity = "maxo")[, 4L]) expect_equal(a, b) - a <- xcms:::.h5_feature_values_sample( + a <- .h5_feature_values_sample( xmseg_full_h5@hdf5_file, sample_id = "S4", ms_level = 1L, n_features = nf, filled = FALSE, method = "medret", col_idx = c(8L, 4L), rtmed = rtmed) @@ -313,15 +317,15 @@ test_that("featureValues,XcmsExperimentHdf5 etc works", { expect_equal(a, b) ## .h5_feature_values_ms_level - a <- xcms:::.h5_feature_values_ms_level(1L, xmseg_full_h5, method = "medret", + a <- .h5_feature_values_ms_level(1L, xmseg_full_h5, method = "medret", value = "into", filled = FALSE) b <- featureValues(ref, method = "medret", value = "into", filled = FALSE) expect_equal(unname(a), unname(b)) - a <- xcms:::.h5_feature_values_ms_level(1L, xmseg_full_h5, method = "sum", + a <- .h5_feature_values_ms_level(1L, xmseg_full_h5, method = "sum", value = "maxo", filled = FALSE) b <- featureValues(ref, method = "sum", value = "maxo", filled = FALSE) expect_equal(unname(a), unname(b)) - a <- xcms:::.h5_feature_values_ms_level(1L, xmseg_full_h5, method = "maxint", + a <- .h5_feature_values_ms_level(1L, xmseg_full_h5, method = "maxint", value = "sn", intensity = "into", filled = FALSE) b <- featureValues(ref, method = "maxint", value = "sn", intensity = "into", @@ -398,11 +402,11 @@ test_that("adjustRtime,XcmsExperimentHdf5 and related function work", { dropFeatureDefinitions() |> applyAdjustedRtime() res_h5 <- tempfile() - res <- xcms:::.xcms_experiment_to_hdf5(ref, res_h5) + res <- .xcms_experiment_to_hdf5(ref, res_h5) ## Create a single sample XcmsExperimentHdf5 a <- ref[3L] a_h5 <- tempfile() - a <- xcms:::.xcms_experiment_to_hdf5(a, a_h5) + a <- .xcms_experiment_to_hdf5(a, a_h5) ## Perform retention time alignment on reference data ref <- ref |> groupChromPeaks(pdp, msLevel = 1L) |> @@ -415,7 +419,7 @@ test_that("adjustRtime,XcmsExperimentHdf5 and related function work", { ############################################################################ ## .h5_update_rt_chrom_peaks_sample: adjust rt of chrom peaks: - cnt <- xcms:::.h5_update_rt_chrom_peaks_sample( + cnt <- .h5_update_rt_chrom_peaks_sample( a@sample_id[1L], rt_raw, rt_adj, 1L, a@hdf5_file) expect_equal(cnt, a@hdf5_mod_count + 1L) a@hdf5_mod_count <- cnt @@ -554,6 +558,30 @@ test_that("chromatogram,XcmsExperimentHdf5 works", { expect_true(rrt[2] <= 2700) }) +test_that("chromatogram,XcmsExperimentHdf5 Chromatograms works", { + fa <- featureArea(xmseg_full_ref) + n <- length(xmseg_full_ref) + + ref <- chromatogram( + xmseg_full_ref, rt = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + mz = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + return.type = "MChromatograms") + res <- chromatogram( + xmseg_full_h5, rt = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + mz = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + return.type = "MChromatograms") + expect_equal(lapply(ref, intensity), lapply(res, intensity)) + res <- chromatogram( + xmseg_full_h5, rt = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + mz = as.matrix(fa[1:10, c("rtmin", "rtmax")]), + return.type = "Chromatograms") + expect_s4_class(res, "Chromatograms") + expect_equal(lapply(ref[1, ], intensity), + intensity(res[seq_len(n)])) + expect_equal(lapply(ref[2, ], intensity), + intensity(res[seq_len(n) + n])) +}) + test_that("hasFilledChromPeaks,XcmsExperimentHdf5 works", { expect_false(hasFilledChromPeaks(new("XcmsExperimentHdf5"))) }) @@ -752,7 +780,7 @@ test_that("filterIsolationWindow,XcmsExperimentHdf5 works", { test_that("refineChromPeaks,XcmsExperimentHdf5,CleanPeaksParam works", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) expect_warning( res <- refineChromPeaks(x, CleanPeaksParam(), msLevel = 2L), @@ -767,7 +795,7 @@ test_that("refineChromPeaks,XcmsExperimentHdf5,CleanPeaksParam works", { ## With features. tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) expect_true(hasFeatures(x)) expect_true(hasAdjustedRtime(x)) expect_true(hasChromPeaks(x)) @@ -785,7 +813,7 @@ test_that("refineChromPeaks,XcmsExperimentHdf5,CleanPeaksParam works", { test_that("refineChromPeaks,XcmsExperimentHdf5,FilterIntensityParam works", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) fip <- FilterIntensityParam(threshold = 100000, nValues = 1) expect_warning( @@ -800,7 +828,7 @@ test_that("refineChromPeaks,XcmsExperimentHdf5,FilterIntensityParam works", { ## nValues > 1 tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) fip <- FilterIntensityParam(threshold = 100000, nValues = 4) res <- refineChromPeaks(x, fip, msLevel = 1L) @@ -812,7 +840,7 @@ test_that("refineChromPeaks,XcmsExperimentHdf5,FilterIntensityParam works", { ## With features. tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) fip <- FilterIntensityParam(threshold = 100000, nValues = 1) expect_true(hasFeatures(x)) expect_true(hasAdjustedRtime(x)) @@ -1007,9 +1035,39 @@ test_that("featureChromatograms,XcmsExperimentHdf5 works", { expect_equal(res_fd, ref_fd[, colnames(res_fd)]) }) +test_that("featureChromatogram,XcmsExperimentHdf5 Chromatograms works", { + n <- length(xmseg_full_ref) + + ## MChromatograms + ref <- featureChromatograms(xmseg_full_ref, return.type = "MChromatograms") + res <- featureChromatograms(xmseg_full_h5, return.type = "MChromatograms") + expect_s4_class(res, "MChromatograms") + expect_equal(lapply(ref, intensity), lapply(res, intensity)) + + ## Chromatograms + res <- featureChromatograms(xmseg_full_h5, return.type = "Chromatograms") + expect_s4_class(res, "Chromatograms") + expect_equal(lapply(ref[1, ], intensity), + intensity(res[seq_len(n)])) + expect_equal(lapply(ref[2, ], intensity), + intensity(res[seq_len(n) + n])) + ref <- featureChromatograms(xmseg_full_ref, return.type = "Chromatograms") + expect_equal(intensity(res[1:100]), intensity(ref[1:100])) + + ## featureArea = FALSE + ref <- featureChromatograms(xmseg_full_ref, return.type = "Chromatograms", + featureArea = FALSE) + res <- featureChromatograms(xmseg_full_h5, return.type = "Chromatograms", + featureArea = FALSE) + expect_s4_class(res, "Chromatograms") + expect_false(anyNA(res$chrom_peak_id)) + expect_false(anyNA(res$feature_id)) + expect_equal(intensity(res[1:100]), intensity(ref[1:100])) +}) + test_that("filterChromPeaks,XcmsExperimentHdf5 works", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) pks <- chromPeaks(x) fts <- featureDefinitions(x) mc <- x@hdf5_mod_count @@ -1034,7 +1092,7 @@ test_that("filterChromPeaks,XcmsExperimentHdf5 works", { test_that("filterFeatureDefinitions,XcmsExperimentHdf5 works", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("xmse"), tmp) fts <- featureDefinitions(x) fvals <- featureValues(x) mc <- x@hdf5_mod_count @@ -1056,14 +1114,14 @@ test_that("filterFeatureDefinitions,XcmsExperimentHdf5 works", { rm(tmp) tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) expect_error(filterFeatureDefinitions(x, 1:3), "No feature definitions") rm(tmp) }) test_that("manualChromPeaks,XcmsExperimentHdf5", { tmp <- tempfile() - x <- xcms:::.xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) + x <- .xcms_experiment_to_hdf5(loadXcmsData("faahko_sub2"), tmp) cpks <- chromPeaks(x) ## errors @@ -1261,6 +1319,26 @@ test_that("chromPeakData,XcmsExperimentHdf5 works with columns", { expect_equal(res$is_filled, ref$is_filled) }) +test_that("featureChromPeaks,XcmsExperimentHdf5 works", { + expect_error(featureChromPeaks(xmseg_full_h5, msLevel = 3L), "for MS") + res <- featureChromPeaks(xmseg_full_h5) + expect_true(is.data.frame(res)) + expect_equal(colnames(res), c("feature_id", "chrom_peak_id")) + ord <- match(res$feature_id, rownames(featureDefinitions(xmseg_full_h5))) + expect_false(is.unsorted(ord)) + expect_true(all(res$chrom_peak_id %in% rownames(chromPeaks(xmseg_full_h5)))) +}) + +test_that("featurePeakidx,XcmsExperimentHdf5 works", { + res <- featurePeakidx(xmseg_full_h5) + expect_true(is.list(res)) + fd <- featureDefinitions(xmseg_full_h5) + expect_equal(length(res), nrow(fd)) + expect_equal(names(res), rownames(fd)) + ref <- featurePeakidx(xmseg_full_ref) + expect_equal(unname(res), unname(ref)) +}) + ## test_that(".h5_feature_chrom_peaks_sample works", { ## cn <- .h5_chrom_peaks_colnames(xmseg_full_h5, 1L) ## res <- .h5_feature_chrom_peaks_sample("S3", xmseg_full_h5@hdf5_file, diff --git a/vignettes/xcms.Rmd b/vignettes/xcms.Rmd index 070018e9..05f3d62e 100644 --- a/vignettes/xcms.Rmd +++ b/vignettes/xcms.Rmd @@ -10,7 +10,7 @@ vignette: > %\VignetteIndexEntry{LC-MS data preprocessing and analysis with xcms} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} - %\VignetteDepends{xcms,RColorBrewer,faahKO,pander,BiocStyle,pheatmap,SummarizedExperiment} + %\VignetteDepends{xcms,RColorBrewer,faahKO,pander,BiocStyle,pheatmap,SummarizedExperiment,Chromatograms,MSnbase} %\VignettePackage{xcms} %\VignetteKeywords{mass spectrometry, metabolomics} bibliography: references.bib @@ -174,45 +174,38 @@ spectra(faahko_3) sampleData(faahko_3) ``` +### Inspecting chromatographic data + As a first evaluation of the data we below plot the base peak chromatogram (BPC) for each file in our experiment. We use the `chromatogram()` method and set the `aggregationFun` to `"max"` to return for each spectrum the maximal intensity -and hence create the BPC from the raw data. To create a total ion chromatogram -we could set `aggregationFun` to `"sum"`. +and hence create the BPC from the raw data (using `"sum"` instead would create a +total ion chromatogram). Note that we also set `return.type = "Chromatograms"` +to switch to the newer infrastructure for chromatographic data in R, provided +by Bioconductor's `r Biocpkg("Chromatograms")` package. -```{r data-inspection-bpc, message = FALSE, fig.align = "center", fig.width = 12, fig.height = 6, fig.cap = "Base peak chromatogram."} +```{r data-inspection-bpc, message = FALSE, warning = FALSE, fig.align = "center", fig.width = 12, fig.height = 6, fig.cap = "Base peak chromatogram."} ## Get the base peak chromatograms. This reads data from the files. -bpis <- chromatogram(faahko, aggregationFun = "max") +bpis <- chromatogram(faahko, aggregationFun = "max", + return.type = "Chromatograms") ## Define colors for the two groups group_colors <- paste0(brewer.pal(3, "Set1")[1:2], "60") names(group_colors) <- c("KO", "WT") ## Plot all chromatograms. -plot(bpis, col = group_colors[sampleData(faahko)$sample_group]) -``` - -The `chromatogram()` method returned a `MChromatograms` object that organizes -individual `Chromatogram` objects (which in fact contain the chromatographic -data) in a two-dimensional array: columns represent samples and rows -(optionally) m/z and/or retention time ranges. Below we extract the chromatogram -of the first sample and access its retention time and intensity values. - -```{r data-inspection-chromatogram, message = FALSE } -bpi_1 <- bpis[1, 1] -rtime(bpi_1) |> head() -intensity(bpi_1) |> head() +library(Chromatograms) +plotChromatogramsOverlay( + bpis, col = group_colors[sampleData(faahko)$sample_group]) +grid() ``` From the BPC above it seems that after around 4200 seconds no signal is measured anymore. Thus, we filter below the full data set to a retention time range from 2550 to 4250 seconds using the `filterRt()` function. Note that at present this -will only subset the spectra within the `MsExperiment`. Subsequently we -re-create also the BPC. +will only subset the spectra within the `MsExperiment`. ```{r, message = FALSE} faahko <- filterRt(faahko, rt = c(2550, 4250)) -## creating the BPC on the subsetted data -bpis <- chromatogram(faahko, aggregationFun = "max") ``` We next create boxplots representing the distribution of the total ion currents @@ -229,6 +222,41 @@ boxplot(tc, col = group_colors[sampleData(faahko)$sample_group], ylab = "intensity", main = "Total ion current") ``` +### Inspecting chromatographic data, legacy framework + +While the `r Biocpkg("Chromatograms")` will become the new standard +infrastructure to represent and handle chromatographic data, *xcms* still fully +supports the legacy *MSnbase*-based objects. To use the legacy objects (that at +present provide more functionality) use `return.type = "MChromatograms"` in the +`chromatogram()` calls. + +```{r legacy-data-inspection-bpc, message = FALSE, fig.align = "center", fig.width = 12, fig.height = 6, fig.cap = "Base peak chromatogram."} +## Get the base peak chromatograms. This reads data from the files. +bpis <- chromatogram(faahko, aggregationFun = "max", + return.type = "MChromatograms") + +## Plot all chromatograms. +plot(bpis, col = group_colors[sampleData(faahko)$sample_group]) +grid() +``` + +With `return.type = "MChromatograms"`, the `chromatogram()` method returned the +data as a legacy `MChromatograms` object. + +We next create boxplots representing the distribution of the total ion currents +per data file. Such plots can be very useful to spot potentially problematic MS +runs. To extract this information, we use the `tic()` function on the `Spectra` +object within `faahko` and split the values by file using `fromFile()`. + +```{r legacy-data-inspection-tic-boxplot, message = FALSE, fig.align = "center", fig.width = 8, fig.height = 4, fig.cap = "Distribution of total ion currents per file." } +## Get the total ion current by file +tc <- spectra(faahko) |> + tic() |> + split(f = fromFile(faahko)) +boxplot(tc, col = group_colors[sampleData(faahko)$sample_group], + ylab = "intensity", main = "Total ion current") +``` + In addition, we can also cluster the samples based on similarity of their base peak chromatograms. Samples would thus be grouped based on similarity of their LC runs. For that we need however to *bin* the data along the retention time @@ -237,7 +265,7 @@ the `bin()` function on the BPC to bin intensities into 2 second wide retention time bins. The clustering is then performed using complete linkage hierarchical clustering on the pairwise correlations of the binned base peak chromatograms. -```{r data-inspection-bpc-heatmap, message = FALSE, fig.align = "center", fig.width = 7, fig.height = 6, fig.cap = "Grouping of samples based on similarity of their base peak chromatogram."} +```{r legacy-data-inspection-bpc-heatmap, message = FALSE, fig.align = "center", fig.width = 7, fig.height = 6, fig.cap = "Grouping of samples based on similarity of their base peak chromatogram."} ## Bin the BPC bpis_bin <- bin(bpis, binSize = 2) @@ -981,7 +1009,9 @@ Results from the correspondence analysis can be accessed with the frame with general information on each of the defined features, with each row being one feature and columns providing information on the median m/z and retention time as well as the indices of the chromatographic peaks assigned to -the feature in column `"peakidx"`. Below we show the information on the first 6 +the feature in column `"peakidx"`. This mapping between features and +chromatographic peaks can also be extracted using the `featureChromPeaks()` and +`featurePeakidx()` functions. Below we show the information on the first 6 features. ```{r}