diff --git a/DESCRIPTION b/DESCRIPTION index deabbce9f..7a5846d70 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: xcms -Version: 1.51.6 -Date: 2017-02-03 +Version: 1.51.7 +Date: 2017-02-21 Title: LC/MS and GC/MS Data Analysis Author: Colin A. Smith , Ralf Tautenhahn , @@ -57,10 +57,11 @@ Collate: 'functions-MsFeatureData.R' 'do_adjustRtime-functions.R' 'functions-binning.R' - 'do_detectFeatures-functions.R' + 'do_findChromPeaks-functions.R' 'functions-Params.R' - 'do_groupFeatures-functions.R' + 'do_groupChromPeaks-functions.R' 'fastMatch.R' + 'functions-Chromatogram.R' 'functions-utils.R' 'functions-IO.R' 'functions-OnDiskMSnExp.R' @@ -72,6 +73,7 @@ Collate: 'functions-xcmsSet.R' 'init.R' 'matchpeaks.R' + 'methods-Chromatogram.R' 'methods-IO.R' 'methods-MsFeatureData.R' 'methods-OnDiskMSnExp.R' diff --git a/NAMESPACE b/NAMESPACE index 47099e923..bce2ce4ba 100755 --- a/NAMESPACE +++ b/NAMESPACE @@ -45,7 +45,8 @@ importMethodsFrom("MSnbase", "intensity", "mz", "rtime", "fileNames", "fromFile" "spectra", "impute", "isCentroided", "polarity", "[", "bin", "clean", "featureNames", "filterAcquisitionNum", "filterMz", "filterRt", "normalize", "pickPeaks", "removePeaks", - "removeReporters", "smooth", "trimMz", "splitByFile", "[[") + "removeReporters", "smooth", "trimMz", "splitByFile", "[[", + "spectrapply", "peaksCount") importFrom("MSnbase", "as.data.frame.Spectrum") export( @@ -184,26 +185,27 @@ export( "binYonX", "breaks_on_binSize", "breaks_on_nBins", - "do_detectFeatures_centWave", - "do_detectFeatures_massifquant", - "do_detectFeatures_matchedFilter", - "do_detectFeatures_MSW", - "do_detectFeatures_centWaveWithPredIsoROIs", - "do_detectFeatures_addPredIsoROIs", + "do_findChromPeaks_centWave", + "do_findChromPeaks_massifquant", + "do_findChromPeaks_matchedFilter", + "do_findPeaks_MSW", + "do_findChromPeaks_centWaveWithPredIsoROIs", + "do_findChromPeaks_addPredIsoROIs", "imputeLinInterpol", "useOriginalCode", "setAs", - "do_groupFeatures_density", - "do_groupFeatures_mzClust", - "do_groupFeatures_nearest", - "do_adjustRtime_featureGroups" + "do_groupChromPeaks_density", + "do_groupPeaks_mzClust", + "do_groupChromPeaks_nearest", + ## "Chromatogram", + "do_adjustRtime_peakGroups" ) ## New analysis methods exportMethods( "showError", - "detectFeatures", - "groupFeatures", + "findChromPeaks", + "groupChromPeaks", "adjustRtime" ) @@ -214,10 +216,10 @@ exportClasses( "MassifquantParam", "MSWParam", "CentWavePredIsoParam", - "FeatureDensityParam", + "PeakDensityParam", "MzClustParam", - "NearestFeaturesParam", - "FeatureGroupsParam", + "NearestPeaksParam", + "PeakGroupsParam", "ObiwarpParam" ) ## Param methods @@ -307,7 +309,7 @@ exportMethods( "mzIntervalExtension<-", "polarity", "polarity<-", - ## FeatureDensityParam + ## PeakDensityParam "sampleGroups", "sampleGroups<-", "bw", @@ -321,15 +323,15 @@ exportMethods( ## MzClustParam "absMz", "absMz<-", - ## NearestFeaturesParam + ## NearestPeaksParam "absRt", "absRt<-", "mzVsRtBalance", "mzVsRtBalance<-", "kNN", "kNN<-", - "extraFeatures", - "extraFeatures<-", + "extraPeaks", + "extraPeaks<-", "smooth", "smooth<-", "span", @@ -358,22 +360,25 @@ exportMethods( ) ## Param class functions export("CentWaveParam", "MatchedFilterParam", "MassifquantParam", "MSWParam", - "CentWavePredIsoParam", "FeatureDensityParam", "MzClustParam", - "NearestFeaturesParam", "FeatureGroupsParam", "ObiwarpParam") + "CentWavePredIsoParam", "PeakDensityParam", "MzClustParam", + "NearestPeaksParam", "PeakGroupsParam", "ObiwarpParam") ## Param class methods. ## New Classes -exportClasses("XCMSnExp", "MsFeatureData", "ProcessHistory", "XProcessHistory") +exportClasses("XCMSnExp", "MsFeatureData", "ProcessHistory", + ## "Chromatogram", + "XProcessHistory" + ) ## New methods for these classes -exportMethods("hasDetectedFeatures", - "hasAlignedFeatures", +exportMethods("hasChromPeaks", + "hasFeatures", "hasAdjustedRtime", "adjustedRtime", "adjustedRtime<-", - "featureGroups", - "featureGroups<-", - "features", - "features<-", + "featureDefinitions", + "featureDefinitions<-", + "chromPeaks", + "chromPeaks<-", "processHistory", "fileIndex", "processDate", @@ -392,10 +397,13 @@ exportMethods("hasDetectedFeatures", "removePeaks", "smooth", "dropAdjustedRtime", - "dropFeatureGroups", - "dropFeatures", + "dropFeatureDefinitions", + "dropChromPeaks", "spectra", "rtime", "mz", - "intensity" + "intensity", + "aggregationFun", +## "extractChromatograms", + "as.data.frame" ) diff --git a/R/AllGenerics.R b/R/AllGenerics.R index b57a44bea..12ae3aa00 100644 --- a/R/AllGenerics.R +++ b/R/AllGenerics.R @@ -16,6 +16,8 @@ setGeneric("adjustRtime", function(object, param, ...) setGeneric("adjustedRtime", function(object, ...) standardGeneric("adjustedRtime")) setGeneric("adjustedRtime<-", function(object, value) standardGeneric("adjustedRtime<-")) +setGeneric("aggregationFun", function(object, ...) + standardGeneric("aggregationFun")) setGeneric("ampTh", function(object, ...) standardGeneric("ampTh")) setGeneric("ampTh<-", function(object, value) standardGeneric("ampTh<-")) setGeneric("AutoLockMass", function(object) standardGeneric("AutoLockMass")) @@ -47,8 +49,8 @@ setGeneric("criticalValue<-", function(object, value) ## D setGeneric("deepCopy", function(object) standardGeneric("deepCopy")) -setGeneric("detectFeatures", function(object, param, ...) - standardGeneric("detectFeatures")) +setGeneric("findChromPeaks", function(object, param, ...) + standardGeneric("findChromPeaks")) setGeneric("diffreport", function(object, ...) standardGeneric("diffreport")) setGeneric("distance", function(object, ...) standardGeneric("distance")) setGeneric("distance<-", function(object, value) standardGeneric("distance<-")) @@ -56,16 +58,19 @@ setGeneric("distFun", function(object) standardGeneric("distFun")) setGeneric("distFun<-", function(object, value) standardGeneric("distFun<-")) setGeneric("dropAdjustedRtime", function(object, ...) standardGeneric("dropAdjustedRtime")) -setGeneric("dropFeatureGroups", function(object, ...) - standardGeneric("dropFeatureGroups")) -setGeneric("dropFeatures", function(object, ...) - standardGeneric("dropFeatures")) +setGeneric("dropFeatureDefinitions", function(object, ...) + standardGeneric("dropFeatureDefinitions")) +setGeneric("dropChromPeaks", function(object, ...) + standardGeneric("dropChromPeaks")) ## E -setGeneric("extraFeatures", function(object, ...) - standardGeneric("extraFeatures")) -setGeneric("extraFeatures<-", function(object, value) - standardGeneric("extraFeatures<-")) +setGeneric("extraPeaks", function(object, ...) + standardGeneric("extraPeaks")) +setGeneric("extraPeaks<-", function(object, value) + standardGeneric("extraPeaks<-")) +setGeneric("extractChromatograms", function(object, ...) + standardGeneric("extractChromatograms")) + ## F setGeneric("factorDiag", function(object) standardGeneric("factorDiag")) @@ -74,12 +79,12 @@ setGeneric("factorGap", function(object) standardGeneric("factorGap")) setGeneric("factorGap<-", function(object, value) standardGeneric("factorGap<-")) setGeneric("family", function(object, ...) standardGeneric("family")) setGeneric("family<-", function(object, value) standardGeneric("family<-")) -setGeneric("features", function(object, ...) standardGeneric("features")) -setGeneric("features<-", function(object, value) - standardGeneric("features<-")) -setGeneric("featureGroups", function(object, ...) standardGeneric("featureGroups")) -setGeneric("featureGroups<-", function(object, value) - standardGeneric("featureGroups<-")) +setGeneric("chromPeaks", function(object, ...) standardGeneric("chromPeaks")) +setGeneric("chromPeaks<-", function(object, value) + standardGeneric("chromPeaks<-")) +setGeneric("featureDefinitions", function(object, ...) standardGeneric("featureDefinitions")) +setGeneric("featureDefinitions<-", function(object, value) + standardGeneric("featureDefinitions<-")) setGeneric("fileIndex", function(object) standardGeneric("fileIndex")) setGeneric("fileIndex<-", function(object, value) standardGeneric("fileIndex<-")) setGeneric("filepaths", function(object) standardGeneric("filepaths")) @@ -136,8 +141,8 @@ 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")) -setGeneric("groupFeatures", function(object, param, ...) - standardGeneric("groupFeatures")) +setGeneric("groupChromPeaks", function(object, param, ...) + standardGeneric("groupChromPeaks")) setGeneric("groupidx", function(object) standardGeneric("groupidx")) setGeneric("groupidx<-", function(object, value) standardGeneric("groupidx<-")) setGeneric("groupnames", function(object, ...) standardGeneric("groupnames")) @@ -149,10 +154,10 @@ setGeneric("groupval", function(object, ...) standardGeneric("groupval")) setGeneric("hasMSn", function(object, ...) standardGeneric("hasMSn")) setGeneric("hasAdjustedRtime", function(object, ...) standardGeneric("hasAdjustedRtime")) -setGeneric("hasAlignedFeatures", function(object, ...) - standardGeneric("hasAlignedFeatures")) -setGeneric("hasDetectedFeatures", function(object, ...) - standardGeneric("hasDetectedFeatures")) +setGeneric("hasFeatures", function(object, ...) + standardGeneric("hasFeatures")) +setGeneric("hasChromPeaks", function(object, ...) + standardGeneric("hasChromPeaks")) ## I @@ -202,7 +207,7 @@ setGeneric("msnparent2ms", function(object, ...) standardGeneric("msnparent2ms") setGeneric("msn2ms", function(object, ...) standardGeneric("msn2ms")) setGeneric("mzdiff", function(object, ...) standardGeneric("mzdiff")) setGeneric("mzdiff<-", function(object, value) standardGeneric("mzdiff<-")) -setGeneric("mzrange", function(object) standardGeneric("mzrange")) +setGeneric("mzrange", function(object, ...) standardGeneric("mzrange")) setGeneric("mzCenterFun", function(object, ...) standardGeneric("mzCenterFun")) setGeneric("mzCenterFun<-", function(object, value) standardGeneric("mzCenterFun<-")) diff --git a/R/DataClasses.R b/R/DataClasses.R index 31b72e355..d7d3fa769 100644 --- a/R/DataClasses.R +++ b/R/DataClasses.R @@ -43,7 +43,7 @@ setClass("xcmsSet", progressCallback = function(progress) NULL, .processHistory = list()), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() ## Check if all slots are present. slNames <- slotNames(object) missingSlots <- character() @@ -52,10 +52,10 @@ setClass("xcmsSet", missingSlots <- c(missingSlots, slNames[i]) } if (length(missingSlots) > 0) - msg <- validMsg(msg, paste0("This xcmsSet lacks slot(s): ", - paste(missingSlots, collapse = ","), - ". Please update the object using", - " the 'updateObject' method.")) + msg <- c(msg, paste0("This xcmsSet lacks slot(s): ", + paste(missingSlots, collapse = ","), + ". Please update the object using", + " the 'updateObject' method.")) ## Check the .processHistory slot. if (!any(missingSlots == ".processHistory")) { inh <- unlist(lapply(object@.processHistory, @@ -63,16 +63,15 @@ setClass("xcmsSet", return(inherits(z, "ProcessHistory")) })) if (!all(inh)) - msg <- validMsg(msg, - paste0("Slot '.processHistory' should", - " only contain 'ProcessHistory'", - " objects!")) + msg <- c(msg, + paste0("Slot '.processHistory' should", + " only contain 'ProcessHistory'", + " objects!")) } - if (!is.null(msg)) + if (length(msg)) return(msg) return(TRUE) - } - ) + }) ############################################################ ## xcmsEIC @@ -198,13 +197,13 @@ setClass("xcmsPeaks", contains = "matrix") ############################################################ ## Processing history type statics .PROCSTEP.UNKNOWN <- "Unknown" -.PROCSTEP.FEATURE.DETECTION <- "Feature detection" -.PROCSTEP.FEATURE.ALIGNMENT <- "Feature alignment" +.PROCSTEP.PEAK.DETECTION <- "Peak detection" +.PROCSTEP.PEAK.GROUPING <- "Peak grouping" .PROCSTEP.RTIME.CORRECTION <- "Retention time correction" .PROCSTEPS <- c( .PROCSTEP.UNKNOWN, - .PROCSTEP.FEATURE.DETECTION, - .PROCSTEP.FEATURE.ALIGNMENT, + .PROCSTEP.PEAK.DETECTION, + .PROCSTEP.PEAK.GROUPING, .PROCSTEP.RTIME.CORRECTION ) @@ -215,13 +214,15 @@ setClass("xcmsPeaks", contains = "matrix") ##' ##' @description Objects of the type \code{ProcessHistory} allow to keep track ##' of any data processing step in an metabolomics experiment. They are created -##' by the data processing methods, such as \code{\link{detectFeatures}} and +##' by the data processing methods, such as \code{\link{findChromPeaks}} and ##' added to the corresponding results objects. Thus, usually, users don't need ##' to create them. ##' ##' @slot type character(1): string defining the type of the processing step. ##' This string has to match predefined values defined in the internal variable -##' \code{.PROCSTEPS}. +##' \code{.PROCSTEPS} (allowed values are \code{"Unknown"}, +##' \code{"Peak detection"}, \code{"Peak grouping"} and +##' \code{"Retention time correction"}). ##' ##' @slot date character(1): date time stamp when the processing step was started. ##' @slot info character(1): optional additional information. @@ -247,24 +248,26 @@ setClass("ProcessHistory", ## new("Versioned", versions = c(ProcessHistory = "0.0.2")) ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() ## check type: if (!any(object@type == .PROCSTEPS)) - msg <- validMsg(msg, paste0("Got invalid type '", object@type, - "'! Allowd are: ", - paste0("\"", .PROCSTEPS, "\"", - collapse = ", "))) + msg <- c(msg, paste0("Got invalid type '", object@type, + "'! Allowd are: ", + paste0("\"", .PROCSTEPS, "\"", + collapse = ", "))) if (length(object@type) > 1) - msg <- validMsg(msg, paste0("length of 'type' should not be ", - "larger than 1!")) + msg <- c(msg, paste0("length of 'type' should not be ", + "larger than 1!")) if (length(object@date) > 1) - msg <- validMsg(msg, paste0("length of 'date' should not be ", - "larger than 1!")) + msg <- c(msg, paste0("length of 'date' should not be ", + "larger than 1!")) if (length(object@info) > 1) - msg <- validMsg(msg, paste0("length of 'info' should not be ", - "larger than 1!")) - if (is.null(msg)) TRUE - else msg + msg <- c(msg, paste0("length of 'info' should not be ", + "larger than 1!")) + if (length(msg)) + msg + else + TRUE } ) @@ -294,100 +297,102 @@ setClass("XProcessHistory", param = NULL ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@param) > 0) if(!is(object@param, "Param")) - msg <- validMsg(msg, - paste0("Only objects from type 'Param' ", - "allowed in slot '@param'! I got ", - class(object@param))) - if (is.null(msg)) TRUE - else msg + msg <- c(msg, + paste0("Only objects from type 'Param' ", + "allowed in slot '@param'! I got ", + class(object@param))) + if (length(msg)) msg + else TRUE }) -## General detectFeatures method. -##' @title Feature detection methods. +##' @aliases findChromPeaks +##' @title Chromatographic peak detection methods. ##' -##' @description The \code{detectFeature} methods are part of the modernized -##' \code{xcms} user interface. +##' @description The \code{findChromPeaks} methods perform the chromatographic +##' peak detection on LC/GC-MS data and are part of the modernized \code{xcms} +##' user interface. ##' -##' The implemented feature detection methods are: +##' The implemented peak detection methods in chromatographic space are: ##' \describe{ -##' \item{centWave}{feature detection using the \emph{centWave} method. -##' See \code{\link{centWave}} for more details.} +##' \item{centWave}{chromatographic peak detection using the \emph{centWave} +##' method. See \code{\link{centWave}} for more details.} ##' -##' \item{centWave with predicted isotopes}{feature detection using a two-step +##' \item{centWave with predicted isotopes}{peak detection using a two-step ##' centWave-based approach considering also feature isotopes. See ##' \code{\link{centWaveWithPredIsoROIs}} for more details.} ##' ##' \item{matchedFilter}{peak detection in chromatographic space. See ##' \code{\link{matchedFilter}} for more details.} ##' -##' \item{massifquant}{peak detection using the Kalman filter-based feature +##' \item{massifquant}{peak detection using the Kalman filter-based ##' method. See \code{\link{massifquant}} for more details.} ##' -##' \item{MSW}{single-spectrum non-chromatography MS data feature detection. +##' \item{MSW}{single-spectrum non-chromatography MS data peak detection. ##' See \code{\link{MSW}} for more details.} ##' ##' } -##' @name detectFeatures -##' @family feature detection methods -##' @seealso \code{\link{findPeaks}} for the \emph{old} feature detection +##' @name chromatographic-peak-detection +##' @family peak detection methods +##' @seealso \code{\link{findPeaks}} for the \emph{old} peak detection ##' methods. ##' @author Johannes Rainer NULL #> NULL ## Main centWave documentation. -##' @title Feature detection using the centWave method +##' @title Chromatographic peak detection using the centWave method ##' ##' @aliases centWave ##' ##' @description The centWave algorithm perform peak density and wavelet based -##' feature detection for high resolution LC/MS data in centroid +##' chromatographic peak detection for high resolution LC/MS data in centroid ##' mode [Tautenhahn 2008]. ##' -##' @param ppm Maximal tolerated m/z deviation in consecutive scans in parts -##' per million (ppm). -##' @param peakwidth numeric(2) with the expected approximate -##' feature/peak width in chromatographic space. Given as a range (min, max) +##' @param ppm \code{numeric(1)} defining the maximal tolerated m/z deviation in +##' consecutive scans in parts per million (ppm) for the initial ROI definition. +##' @param peakwidth \code{numeric(2)} with the expected approximate +##' peak width in chromatographic space. Given as a range (min, max) ##' in seconds. -##' @param snthresh numeric(1) defining the signal to noise ratio cutoff. -##' @param prefilter numeric(2): \code{c(k, I)} specifying the prefilter +##' @param snthresh \code{numeric(1)} defining the signal to noise ratio cutoff. +##' @param prefilter \code{numeric(2)}: \code{c(k, I)} specifying the prefilter ##' step for the first analysis step (ROI detection). Mass traces are only ##' retained if they contain at least \code{k} peaks with intensity \code{>= I}. ##' @param mzCenterFun Name of the function to calculate the m/z center of the -##' feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -##' m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -##' use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -##' mean of the m/z value at the peak apex and the m/z values left and right of -##' it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -##' m/z values left and right of it. +##' chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +##' the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +##' \code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +##' intensity weighted mean of the m/z value at the peak apex and the m/z values +##' left and right of it and \code{"meanApex3"}: mean of the m/z value of the +##' peak apex and the m/z values left and right of it. ##' @param integrate Integration method. For \code{integrate = 1} peak limits ##' are found through descent on the mexican hat filtered data, for ##' \code{integrate = 2} the descent is done on the real data. The latter method ##' is more accurate but prone to noise, while the former is more robust, but ##' less exact. -##' @param mzdiff Numeric representing the minimum difference in m/z dimension -##' for peaks with overlapping retention times; can be negatove to allow overlap. -##' @param fitgauss Logical whether or not a Gaussian should be fitted to each -##' peak. -##' @param noise numeric(1) allowing to set a minimum intensity required +##' @param mzdiff \code{numeric(1)} representing the minimum difference in m/z +##' dimension for peaks with overlapping retention times; can be negatove to +##' allow overlap. +##' @param fitgauss \code{logical(1)} whether or not a Gaussian should be fitted +##' to each peak. +##' @param noise \code{numeric(1)} allowing to set a minimum intensity required ##' for centroids to be considered in the first analysis step (centroids with ##' intensity \code{< noise} are omitted from ROI detection). -##' @param verboseColumns Logical whether additional feature meta data columns -##' should be returned. +##' @param verboseColumns \code{logical(1)} whether additional peak meta data +##' columns should be returned. ##' @param roiList An optional list of regions-of-interest (ROI) representing ##' detected mass traces. If ROIs are submitted the first analysis step is -##' omitted and feature detection is performed on the submitted ROIs. Each -##' ROI is expected to have the following elements specified: +##' omitted and chromatographic peak detection is performed on the submitted +##' ROIs. Each ROI is expected to have the following elements specified: ##' \code{scmin} (start scan index), \code{scmax} (end scan index), ##' \code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} ##' (number of scans), \code{intensity} (summed intensity). Each ROI should be ##' represented by a \code{list} of elements or a single row \code{data.frame}. -##' @param firstBaselineCheck logical(1). If \code{TRUE} continuous +##' @param firstBaselineCheck \code{logical(1)}. If \code{TRUE} continuous ##' data within regions of interest is checked to be above the first baseline. ##' @param roiScales Optional numeric vector with length equal to \code{roiList} ##' defining the scale for each region of interest in \code{roiList} that should @@ -404,33 +409,33 @@ NULL ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{findPeaks}} methods. It supports feature detection on +##' \code{\link{findPeaks}} methods. It supports peak detection on ##' \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} ##' objects (both defined in the \code{MSnbase} package). All of the settings ##' to the centWave algorithm can be passed with a \code{CentWaveParam} object. ##' -##' @family feature detection methods -##' @seealso The \code{\link{do_detectFeatures_centWave}} core API function and +##' @family peak detection methods +##' @seealso The \code{\link{do_findChromPeaks_centWave}} core API function and ##' \code{\link{findPeaks.centWave}} for the old user interface. ##' ##' @references ##' Ralf Tautenhahn, Christoph B\"{o}ttcher, and Steffen Neumann "Highly ##' sensitive feature detection for high resolution LC/MS" \emph{BMC Bioinformatics} ##' 2008, 9:504 -##' @name featureDetection-centWave +##' @name findChromPeaks-centWave ##' @author Ralf Tautenhahn, Johannes Rainer NULL #> NULL -##' @description The \code{CentWaveParam} class allows to specify all settings for -##' a feature detection using the centWave method. Instances should be created -##' with the \code{CentWaveParam} constructor. +##' @description The \code{CentWaveParam} class allows to specify all settings +##' for a chromatographic peak detection using the centWave method. Instances +##' should be created with the \code{CentWaveParam} constructor. ##' ##' @slot .__classVersion__,ppm,peakwidth,snthresh,prefilter,mzCenterFun,integrate,mzdiff,fitgauss,noise,verboseColumns,roiList,firstBaselineCheck,roiScales See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave ##' ##' @examples ##' @@ -442,7 +447,7 @@ NULL ##' snthresh(cwp) <- 25 ##' cwp ##' -##' ## Perform the feature detection using centWave on some of the files from the +##' ## Perform the peak detection using centWave on some of the files from the ##' ## faahKO package. Files are read using the readMSData2 from the MSnbase ##' ## package ##' library(faahKO) @@ -451,10 +456,9 @@ NULL ##' full.names = TRUE) ##' raw_data <- readMSData2(fls[1:2]) ##' -##' ## Perform the feature detection using the settings defined above. We're -##' ## returning the results as an xcmsSet object. -##' res <- detectFeatures(raw_data, param = cwp, return.type = "xcmsSet") -##' head(peaks(res)) +##' ## Perform the peak detection using the settings defined above. +##' res <- findChromPeaks(raw_data, param = cwp) +##' head(chromPeaks(res)) setClass("CentWaveParam", slots = c( ppm = "numeric", @@ -488,44 +492,44 @@ setClass("CentWaveParam", roiScales = numeric() ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@ppm) != 1 | any(object@ppm < 0)) - msg <- validMsg(msg, paste0("'ppm' has to be positive numeric", - " of length 1.")) + msg <- c(msg, paste0("'ppm' has to be positive numeric", + " of length 1.")) if (length(object@peakwidth) != 2 | any(object@peakwidth < 0)) - msg <- validMsg(msg, paste0("'peakwidth' has to be a numeric", - " of length 2 with only positive", - " values.")) + msg <- c(msg, paste0("'peakwidth' has to be a numeric", + " of length 2 with only positive", + " values.")) if (length(object@snthresh) != 1 | any(object@snthresh < 0)) - msg <- validMsg(msg, paste0("'snthresh' has to be a positive", - " numeric of length 1.")) + msg <- c(msg, paste0("'snthresh' has to be a positive", + " numeric of length 1.")) if (length(object@prefilter) != 2) - msg <- validMsg(msg, paste0("'prefilter' has to be a numeric", - " of length 2.")) + msg <- c(msg, paste0("'prefilter' has to be a numeric", + " of length 2.")) allowed_vals <- c("wMean", "mean", "apex", "wMeanApex3", "meanApex3") if (!(object@mzCenterFun) %in% allowed_vals) - msg <- validMsg(msg, paste0("'mzCenterFun' has to be one of ", - paste0("'", allowed_vals, "'", + msg <- c(msg, paste0("'mzCenterFun' has to be one of ", + paste0("'", allowed_vals, "'", collapse = ", "), ".")) if (!(object@integrate %in% c(1L, 2L))) - msg <- validMsg(msg, paste0("'integrate' has to be either 1", - " or 2.")) + msg <- c(msg, paste0("'integrate' has to be either 1", + " or 2.")) if (length(object@mzdiff) != 1) - msg <- validMsg(msg, paste0("'mzdiff' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'mzdiff' has to be a numeric of", + " length 1.")) if (length(object@noise) != 1) - msg <- validMsg(msg, paste0("'noise' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'noise' has to be a numeric of", + " length 1.")) if (length(object@fitgauss) != 1) - msg <- validMsg(msg, paste0("'fitgauss' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'fitgauss' has to be a numeric of", + " length 1.")) if (length(object@verboseColumns) != 1) - msg <- validMsg(msg, paste0("'verboseColumns' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'verboseColumns' has to be a ", + "numeric of length 1.")) if (length(object@firstBaselineCheck) != 1) - msg <- validMsg(msg, paste0("'firstBaselineCheck' has to be a", - " numeric of length 1.")) + msg <- c(msg, paste0("'firstBaselineCheck' has to be a", + " numeric of length 1.")) if (length(object@roiList) > 0) { doHaveExpectedEls <- function(z) { need <- c("scmax", "scmin", "mzmin", "mzmax", "length", @@ -539,18 +543,17 @@ setClass("CentWaveParam", } OKs <- unlist(lapply(object@roiList, doHaveExpectedEls)) if (any(!OKs)) - msg <- validMsg(msg, paste0("'roiList' does not provide ", - "all required fields!")) + msg <- c(msg, paste0("'roiList' does not provide ", + "all required fields!")) } if (length(object@roiList) > 0 & length(object@roiList) != length(object@roiScales)) - msg <- validMsg(msg, paste0("'roiScales' has to have the same", - " length than 'roiList'.")) - if (is.null(msg)) { - return(TRUE) - } else { - return(msg) - } + msg <- c(msg, paste0("'roiScales' has to have the same", + " length than 'roiList'.")) + if (length(msg)) + msg + else + TRUE }) ## Main matchedFilter documentation. @@ -558,41 +561,41 @@ setClass("CentWaveParam", ##' ##' @aliases matchedFilter ##' -##' @description The \emph{matchedFilter} algorithm identifies features in the +##' @description The \emph{matchedFilter} algorithm identifies peaks in the ##' chromatographic time domain as described in [Smith 2006]. The intensity ##' values are binned by cutting The LC/MS data into slices (bins) of a mass unit ##' (\code{binSize} m/z) wide. Within each bin the maximal intensity is selected. -##' The feature detection is then performed in each bin by extending it based on -##' the \code{steps} parameter to generate slices comprising bins +##' The chromatographic peak detection is then performed in each bin by extending +##' it based on the \code{steps} parameter to generate slices comprising bins ##' \code{current_bin - steps +1} to \code{current_bin + steps - 1}. Each of ##' these slices is then filtered with matched filtration using a second-derative -##' Gaussian as the model feature/peak shape. After filtration features are -##' detected using a signal-to-ration cut-off. For more details and -##' illustrations see [Smith 2006]. +##' Gaussian as the model peak shape. After filtration peaks are detected using +##' a signal-to-ration cut-off. For more details and illustrations see +##' [Smith 2006]. ##' -##' @param binSize numeric(1) specifying the width of the +##' @param binSize \code{numeric(1)} specifying the width of the ##' bins/slices in m/z dimension. ##' @param impute Character string specifying the method to be used for missing ##' value imputation. Allowed values are \code{"none"} (no linear interpolation), ##' \code{"lin"} (linear interpolation), \code{"linbase"} (linear interpolation ##' within a certain bin-neighborhood) and \code{"intlin"}. See ##' \code{\link{imputeLinInterpol}} for more details. -##' @param fwhm numeric(1) specifying the full width at half maximum +##' @param fwhm \code{numeric(1)} specifying the full width at half maximum ##' of matched filtration gaussian model peak. Only used to calculate the actual ##' sigma, see below. -##' @param sigma numeric(1) specifying the standard deviation (width) +##' @param sigma \code{numeric(1)} specifying the standard deviation (width) ##' of the matched filtration model peak. -##' @param max numeric(1) representing the maximum number of peaks +##' @param max \code{numeric(1)} representing the maximum number of peaks ##' that are expected/will be identified per slice. -##' @param snthresh numeric(1) defining the signal to noise cutoff -##' to be used in the feature detection step. -##' @param steps numeric(1) defining the number of bins to be +##' @param snthresh \code{numeric(1)} defining the signal to noise cutoff +##' to be used in the chromatographic peak detection step. +##' @param steps \code{numeric(1)} defining the number of bins to be ##' merged before filtration (i.e. the number of neighboring bins that will be ##' joined to the slice in which filtration and peak detection will be ##' performed). -##' @param mzdiff numeric(1) defining the minimum difference +##' @param mzdiff \code{numeric(1)} defining the minimum difference ##' in m/z for peaks with overlapping retention times -##' @param index Logical specifying whether indicies should be returned instead +##' @param index \code{logical(1)} specifying whether indicies should be returned instead ##' of values for m/z and retention times. ##' ##' @details The intensities are binned by the provided m/z values within each @@ -605,17 +608,17 @@ setClass("CentWaveParam", ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{findPeaks}} methods. It supports feature detection on -##' \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +##' \code{\link{findPeaks}} methods. It supports chromatographic peak detection +##' on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} ##' objects (both defined in the \code{MSnbase} package). All of the settings ##' to the matchedFilter algorithm can be passed with a ##' \code{MatchedFilterParam} object. ##' ##' @inheritParams imputeLinInterpol -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @family feature detection methods -##' @seealso The \code{\link{do_detectFeatures_matchedFilter}} core API function +##' @family peak detection methods +##' @seealso The \code{\link{do_findChromPeaks_matchedFilter}} core API function ##' and \code{\link{findPeaks.matchedFilter}} for the old user interface. ##' ##' @references @@ -625,19 +628,19 @@ setClass("CentWaveParam", ##' \emph{Anal. Chem.} 2006, 78:779-787. ##' @author Colin A Smith, Johannes Rainer ##' -##' @name featureDetection-matchedFilter +##' @name findChromPeaks-matchedFilter NULL #> NULL ##' @description The \code{MatchedFilterParam} class allows to specify all -##' settings for a feature detection using the matchedFilter method. Instances -##' should be created with the \code{MatchedFilterParam} constructor. +##' settings for a chromatographic peak detection using the matchedFilter method. +##' Instances should be created with the \code{MatchedFilterParam} constructor. ##' ##' @slot .__classVersion__,binSize,impute,baseValue,distance,fwhm,sigma,max,snthresh,steps,mzdiff,index See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter ##' ##' @examples ##' @@ -647,7 +650,7 @@ NULL ##' snthresh(mfp) <- 15 ##' mfp ##' -##' ## Perform the feature detection using matchecFilter on the files from the +##' ## Perform the peak detection using matchecFilter on the files from the ##' ## faahKO package. Files are read using the readMSData2 from the MSnbase ##' ## package ##' library(faahKO) @@ -655,12 +658,12 @@ NULL ##' fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, ##' full.names = TRUE) ##' raw_data <- readMSData2(fls) -##' ## Perform the feature detection using the settings defined above. We're -##' ## returning the results as an xcmsSet object. Note that we are also -##' ## disabling parallel processing in this example by registering a "SerialParam" +##' ## Perform the chromatographic peak detection using the settings defined +##' ## above. Note that we are also disabling parallel processing in this +##' ## example by registering a "SerialParam" ##' register(SerialParam()) -##' res <- detectFeatures(raw_data, param = mfp, return.type = "xcmsSet") -##' head(peaks(res)) +##' res <- findChromPeaks(raw_data, param = mfp) +##' head(chromPeaks(res)) setClass("MatchedFilterParam", slots = c( binSize = "numeric", @@ -690,114 +693,113 @@ setClass("MatchedFilterParam", index = FALSE ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@binSize) != 1 | any(object@binSize < 0)) - msg <- validMsg(msg, paste0("'binSize' has to be positive", - " numeric of length 1.")) + msg <- c(msg, paste0("'binSize' has to be positive", + " numeric of length 1.")) if (!any(c("none", "lin", "linbase") == object@impute)) - msg <- validMsg(msg, - paste0("Only values 'none', 'lin' and ", - "'linbase' are allowed for'impute'")) + msg <- c(msg, + paste0("Only values 'none', 'lin' and ", + "'linbase' are allowed for'impute'")) if (length(object@baseValue) > 1) - msg <- validMsg(msg, paste0("'baseValue' has to be a", - " numeric of length 1.")) + msg <- c(msg, paste0("'baseValue' has to be a", + " numeric of length 1.")) if (length(object@distance) > 1) - msg <- validMsg(msg, paste0("'distance' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'distance' has to be a numeric", + " of length 1.")) if (length(object@fwhm) != 1) - msg <- validMsg(msg, paste0("'fwhm' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'fwhm' has to be a numeric", + " of length 1.")) if (length(object@sigma) != 1) - msg <- validMsg(msg, paste0("'sigma' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'sigma' has to be a numeric", + " of length 1.")) if (length(object@max) != 1) - msg <- validMsg(msg, paste0("'max' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'max' has to be a numeric", + " of length 1.")) if (length(object@snthresh) != 1) - msg <- validMsg(msg, paste0("'snthresh' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'snthresh' has to be a numeric", + " of length 1.")) if (length(object@steps) != 1) - msg <- validMsg(msg, paste0("'steps' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'steps' has to be a numeric", + " of length 1.")) if (length(object@mzdiff) != 1) - msg <- validMsg(msg, paste0("'mzdiff' has to be a numeric", - " of length 1.")) + msg <- c(msg, paste0("'mzdiff' has to be a numeric", + " of length 1.")) if (length(object@index) != 1) - msg <- validMsg(msg, paste0("'index' has to be a logical", - " of length 1.")) - if (is.null(msg)) { - return(TRUE) - } else { - return(msg) - } + msg <- c(msg, paste0("'index' has to be a logical", + " of length 1.")) + if (length(msg)) + msg + else + TRUE }) ## Main massifquant documentation. -##' @title Feature detection using the massifquant method +##' @title Chromatographic peak detection using the massifquant method ##' ##' @aliases massifquant ##' -##' @description Massifquant is a Kalman filter (KF)-based feature -##' detection for XC-MS data in centroid mode. The identified features +##' @description Massifquant is a Kalman filter (KF)-based chromatographic peak +##' detection for XC-MS data in centroid mode. The identified peaks ##' can be further refined with the \emph{centWave} method (see -##' \code{\link{do_detectFeatures_centWave}} for details on centWave) +##' \code{\link{findChromPeaks-centWave}} for details on centWave) ##' by specifying \code{withWave = TRUE}. ##' -##' @param peakwidth numeric(2). Only the first element is used by -##' massifquant, which specifices the minimum feature length in time scans. +##' @param peakwidth \code{numeric(2)}. Only the first element is used by +##' massifquant, which specifices the minimum peak length in time scans. ##' For \code{withWave = TRUE} the second argument represents the maximum -##' feature length subject to being greater than the mininum feature length -##' (see also documentation of \code{\link{do_detectFeatures_centWave}}). -##' @param prefilter numeric(2). The first argument is only used -##' if (\code{withWave = TRUE}); see \code{\link{do_detectFeatures_centWave}} +##' peak length subject to being greater than the mininum peak length +##' (see also documentation of \code{\link{do_findChromPeaks_centWave}}). +##' @param prefilter \code{numeric(2)}. The first argument is only used +##' if (\code{withWave = TRUE}); see \code{\link{findChromPeaks-centWave}} ##' for details. The second argument specifies the minimum threshold for the -##' maximum intensity of a feature that must be met. -##' @param criticalValue numeric(1). Suggested values: +##' maximum intensity of a chromatographic peak that must be met. +##' @param criticalValue \code{numeric(1)}. Suggested values: ##' (\code{0.1-3.0}). This setting helps determine the the Kalman Filter ##' prediciton margin of error. A real centroid belonging to a bonafide -##' feature must fall within the KF prediction margin of error. Much like +##' peak must fall within the KF prediction margin of error. Much like ##' in the construction of a confidence interval, \code{criticalVal} loosely ##' translates to be a multiplier of the standard error of the prediction -##' reported by the Kalman Filter. If the features in the XC-MS sample have +##' reported by the Kalman Filter. If the peak in the XC-MS sample have ##' a small mass deviance in ppm error, a smaller critical value might be ##' better and vice versa. -##' @param consecMissedLimit Integer: Suggested values: (\code{1,2,3}). While -##' a feature is in the proces of being detected by a Kalman Filter, the +##' @param consecMissedLimit \code{integer(1)} Suggested values: (\code{1,2,3}). +##' While a peak is in the proces of being detected by a Kalman Filter, the ##' Kalman Filter may not find a predicted centroid in every scan. After 1 ##' or more consecutive failed predictions, this setting informs Massifquant -##' when to stop a Kalman Filter from following a candidate feature. -##' @param unions Integer: set to \code{1} if apply t-test union on +##' when to stop a Kalman Filter from following a candidate peak. +##' @param unions \code{integer(1)} set to \code{1} if apply t-test union on ##' segmentation; set to \code{0} if no t-test to be applied on -##' chromatographically continous features sharing same m/z range. +##' chromatographically continous peaks sharing same m/z range. ##' Explanation: With very few data points, sometimes a Kalman Filter stops -##' tracking a feature prematurely. Another Kalman Filter is instantiated +##' tracking a peak prematurely. Another Kalman Filter is instantiated ##' and begins following the rest of the signal. Because tracking is done -##' backwards to forwards, this algorithmic defect leaves a real feature +##' backwards to forwards, this algorithmic defect leaves a real peak ##' divided into two segments or more. With this option turned on, the -##' program identifies segmented features and combines them (merges them) +##' program identifies segmented peaks and combines them (merges them) ##' into one with a two sample t-test. The potential danger of this option -##' is that some truly distinct features may be merged. -##' @param checkBack Integer: set to \code{1} if turned on; set to \code{0} -##' if turned off. The convergence of a Kalman Filter to a feature's precise -##' m/z mapping is very fast, but sometimes it incorporates erroneous centroids -##' as part of a feature (especially early on). The \code{scanBack} option is an -##' attempt to remove the occasional outlier that lies beyond the converged +##' is that some truly distinct peaks may be merged. +##' @param checkBack \code{integer(1)} set to \code{1} if turned on; set to +##' \code{0} if turned off. The convergence of a Kalman Filter to a peak's +##' precise m/z mapping is very fast, but sometimes it incorporates erroneous +##' centroids as part of a peak (especially early on). The \code{scanBack} option +##' is an attempt to remove the occasional outlier that lies beyond the converged ##' bounds of the Kalman Filter. The option does not directly affect -##' identification of a feature because it is a postprocessing measure; it +##' identification of a peak because it is a postprocessing measure; it ##' has not shown to be a extremely useful thus far and the default is set ##' to being turned off. -##' @param withWave Logical: if \code{TRUE}, the features identified first +##' @param withWave \code{logical(1)} if \code{TRUE}, the peaks identified first ##' with Massifquant are subsequently filtered with the second step of the ##' centWave algorithm, which includes wavelet estimation. ##' ##' @details This algorithm's performance has been tested rigorously ##' on high resolution LC/{OrbiTrap, TOF}-MS data in centroid mode. -##' Simultaneous kalman filters identify features and calculate their -##' area under the curve. The default parameters are set to operate on +##' Simultaneous kalman filters identify chromatographic peaks and calculate +##' their area under the curve. The default parameters are set to operate on ##' a complex LC-MS Orbitrap sample. Users will find it useful to do some ##' simple exploratory data analysis to find out where to set a minimum -##' intensity, and identify how many scans an average feature spans. The +##' intensity, and identify how many scans an average peak spans. The ##' \code{consecMissedLimit} parameter has yielded good performance on ##' Orbitrap data when set to (\code{2}) and on TOF data it was found best ##' to be at (\code{1}). This may change as the algorithm has yet to be @@ -810,16 +812,16 @@ setClass("MatchedFilterParam", ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{findPeaks}} methods. It supports feature detection on -##' \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +##' \code{\link{findPeaks}} methods. It supports chromatographic peak detection +##' on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} ##' objects (both defined in the \code{MSnbase} package). All of the settings ##' to the massifquant and centWave algorithm can be passed with a ##' \code{MassifquantParam} object. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @family feature detection methods -##' @seealso The \code{\link{do_detectFeatures_massifquant}} core API function +##' @family peak detection methods +##' @seealso The \code{\link{do_findChromPeaks_massifquant}} core API function ##' and \code{\link{findPeaks.massifquant}} for the old user interface. ##' ##' @references @@ -828,20 +830,20 @@ setClass("MatchedFilterParam", ##' detection" \emph{Bioinformatics} 2014, 30(18):2636-43. ##' @author Christopher Conley, Johannes Rainer ##' -##' @name featureDetection-massifquant +##' @name findChromPeaks-massifquant NULL #> NULL ##' @description The \code{MassifquantParam} class allows to specify all -##' settings for a feature detection using the massifquant method eventually in -##' combination with the centWave algorithm. Instances should be created with -##' the \code{MassifquantParam} constructor. +##' settings for a chromatographic peak detection using the massifquant method +##' eventually in combination with the centWave algorithm. Instances should be +##' created with the \code{MassifquantParam} constructor. ##' ##' @slot .__classVersion__,ppm,peakwidth,snthresh,prefilter,mzCenterFun,integrate,mzdiff,fitgauss,noise,verboseColumns,criticalValue,consecMissedLimit,unions,checkBack,withWave See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant ##' ##' @examples ##' @@ -851,7 +853,7 @@ NULL ##' snthresh(mqp) <- 30 ##' mqp ##' -##' ## Perform the feature detection using massifquant on the files from the +##' ## Perform the peak detection using massifquant on the files from the ##' ## faahKO package. Files are read using the readMSData2 from the MSnbase ##' ## package ##' library(faahKO) @@ -859,10 +861,9 @@ NULL ##' fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, ##' full.names = TRUE) ##' raw_data <- readMSData2(fls[1:2]) -##' ## Perform the feature detection using the settings defined above. We're -##' ## returning the results as an xcmsSet object. -##' res <- detectFeatures(raw_data, param = mqp, return.type = "xcmsSet") -##' head(peaks(res)) +##' ## Perform the peak detection using the settings defined above. +##' res <- findChromPeaks(raw_data, param = mqp) +##' head(chromPeaks(res)) setClass("MassifquantParam", slots = c( ppm = "numeric", @@ -900,74 +901,72 @@ setClass("MassifquantParam", withWave = FALSE ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@ppm) != 1 | any(object@ppm < 0)) - msg <- validMsg(msg, paste0("'ppm' has to be positive numeric", - " of length 1.")) + msg <- c(msg, paste0("'ppm' has to be positive numeric", + " of length 1.")) if (length(object@peakwidth) != 2 | any(object@peakwidth < 0)) - msg <- validMsg(msg, paste0("'peakwidth' has to be a numeric", - " of length 2 with only positive", - " values.")) + msg <- c(msg, paste0("'peakwidth' has to be a numeric", + " of length 2 with only positive", + " values.")) if (length(object@snthresh) != 1 | any(object@snthresh < 0)) - msg <- validMsg(msg, paste0("'snthresh' has to be a positive", - " numeric of length 1.")) + msg <- c(msg, paste0("'snthresh' has to be a positive", + " numeric of length 1.")) if (length(object@prefilter) != 2) - msg <- validMsg(msg, paste0("'prefilter' has to be a numeric", - " of length 2.")) + msg <- c(msg, paste0("'prefilter' has to be a numeric", + " of length 2.")) allowed_vals <- c("wMean", "mean", "apex", "wMeanApex3", "meanApex3") if (!(object@mzCenterFun) %in% allowed_vals) - msg <- validMsg(msg, paste0("'mzCenterFun' has to be one of ", - paste0("'", allowed_vals, "'", + msg <- c(msg, paste0("'mzCenterFun' has to be one of ", + paste0("'", allowed_vals, "'", collapse = ", "), ".")) if (!(object@integrate %in% c(1L, 2L))) - msg <- validMsg(msg, paste0("'integrate' has to be either 1", - " or 2.")) + msg <- c(msg, paste0("'integrate' has to be either 1", + " or 2.")) if (length(object@mzdiff) != 1) - msg <- validMsg(msg, paste0("'mzdiff' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'mzdiff' has to be a numeric of", + " length 1.")) if (length(object@noise) != 1) - msg <- validMsg(msg, paste0("'noise' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'noise' has to be a numeric of", + " length 1.")) if (length(object@fitgauss) != 1) - msg <- validMsg(msg, paste0("'fitgauss' has to be a numeric of", - " length 1.")) + msg <- c(msg, paste0("'fitgauss' has to be a numeric of", + " length 1.")) if (length(object@verboseColumns) != 1) - msg <- validMsg(msg, paste0("'verboseColumns' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'verboseColumns' has to be a ", + "numeric of length 1.")) if (length(object@criticalValue) != 1) - msg <- validMsg(msg, paste0("'criticalValue' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'criticalValue' has to be a ", + "numeric of length 1.")) if (length(object@consecMissedLimit) != 1) - msg <- validMsg(msg, paste0("'consecMissedLimit' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'consecMissedLimit' has to be a ", + "numeric of length 1.")) if (length(object@unions) != 1) - msg <- validMsg(msg, paste0("'unions' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'unions' has to be a ", + "numeric of length 1.")) if (object@unions != 0 & object@unions != 1) - msg <- validMsg(msg, paste0("'unions' has to be either 0 or 1!")) + msg <- c(msg, paste0("'unions' has to be either 0 or 1!")) if (length(object@checkBack) != 1) - msg <- validMsg(msg, paste0("'checkBack' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'checkBack' has to be a ", + "numeric of length 1.")) if (object@checkBack != 0 & object@checkBack != 1) - msg <- validMsg(msg, paste0("'checkBack' has to be either 0", - " or 1!")) + msg <- c(msg, paste0("'checkBack' has to be either 0", + " or 1!")) if (length(object@withWave) != 1) - msg <- validMsg(msg, paste0("'withWave' has to be a ", - "numeric of length 1.")) - if (is.null(msg)) { - return(TRUE) - } else { - return(msg) - } + msg <- c(msg, paste0("'withWave' has to be a ", + "numeric of length 1.")) + if (length(msg)) + msg + else TRUE }) ## Main MSW documentation. -##' @title Single-spectrum non-chromatography MS data feature detection +##' @title Single-spectrum non-chromatography MS data peak detection ##' ##' @aliases MSW ##' -##' @description Perform feature detection in mass spectrometry +##' @description Perform peak detection in mass spectrometry ##' direct injection spectrum using a wavelet based algorithm. ##' ##' @details This is a wrapper for the peak picker in Bioconductor's @@ -978,33 +977,32 @@ setClass("MassifquantParam", ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{findPeaks}} methods. It supports feature detection on +##' \code{\link{findPeaks}} methods. It supports peak detection on ##' \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} ##' objects (both defined in the \code{MSnbase} package). All of the settings -##' to the massifquant and centWave algorithm can be passed with a -##' \code{MassifquantParam} object. +##' to the algorithm can be passed with a \code{MSWParam} object. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @family feature detection methods -##' @seealso The \code{\link{do_detectFeatures_MSW}} core API function +##' @family peak detection methods +##' @seealso The \code{\link{do_findPeaks_MSW}} core API function ##' and \code{\link{findPeaks.MSW}} for the old user interface. ##' ##' @author Joachim Kutzera, Steffen Neumann, Johannes Rainer ##' -##' @name featureDetection-MSW +##' @name findPeaks-MSW NULL #> NULL ##' @description The \code{MSWParam} class allows to specify all -##' settings for a feature detection using the MSW method. Instances should be +##' settings for a peak detection using the MSW method. Instances should be ##' created with the \code{MSWParam} constructor. ##' ##' @slot .__classVersion__,snthresh,verboseColumns,scales,nearbyPeak,peakScaleRange,ampTh,minNoiseLevel,ridgeLength,peakThr,tuneIn,addParams See corresponding parameter above. \code{.__classVersion__} stores the version from the class. Slots values ##' should exclusively be accessed \emph{via} the corresponding getter and ##' setter methods listed above. ##' -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW ##' ##' @examples ##' @@ -1020,12 +1018,12 @@ NULL ##' recursive = TRUE, full.names = TRUE) ##' fticr <- readMSData2(fticrf[1:2], msLevel. = 1) ##' -##' ## Perform the MSW feature detection on these: +##' ## Perform the MSW peak detection on these: ##' p <- MSWParam(scales = c(1, 7), peakThr = 80000, ampTh = 0.005, ##' SNR.method = "data.mean", winSize.noise = 500) -##' fticr <- detectFeatures(fticr, param = p) +##' fticr <- findChromPeaks(fticr, param = p) ##' -##' head(features(fticr)) +##' head(chromPeaks(fticr)) setClass("MSWParam", slots = c( snthresh = "numeric", @@ -1056,97 +1054,96 @@ setClass("MSWParam", addParams = list() ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@snthresh) != 1 | any(object@snthresh < 0)) - msg <- validMsg(msg, paste0("'snthresh' has to be a positive", - " numeric of length 1.")) + msg <- c(msg, paste0("'snthresh' has to be a positive", + " numeric of length 1.")) if (length(object@verboseColumns) != 1) - msg <- validMsg(msg, paste0("'verboseColumns' has to be a ", - "numeric of length 1.")) + msg <- c(msg, paste0("'verboseColumns' has to be a ", + "numeric of length 1.")) if (length(object@nearbyPeak) != 1) - msg <- validMsg(msg, paste0("'nearbyPeak' has to be a ", - "logical of length 1.")) + msg <- c(msg, paste0("'nearbyPeak' has to be a ", + "logical of length 1.")) if (length(object@peakScaleRange) != 1 | any(object@peakScaleRange < 0)) - msg <- validMsg(msg, paste0("'peakScaleRange' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'peakScaleRange' has to be a ", + "positive numeric of length 1.")) if (length(object@ampTh) != 1 | any(object@ampTh < 0)) - msg <- validMsg(msg, paste0("'ampTh' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'ampTh' has to be a ", + "positive numeric of length 1.")) if (length(object@minNoiseLevel) != 1 | any(object@minNoiseLevel < 0)) - msg <- validMsg(msg, paste0("'minNoiseLevel' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'minNoiseLevel' has to be a ", + "positive numeric of length 1.")) if (length(object@ridgeLength) != 1 | any(object@ridgeLength < 0)) - msg <- validMsg(msg, paste0("'ridgeLength' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'ridgeLength' has to be a ", + "positive numeric of length 1.")) if (length(object@peakThr) > 1) - msg <- validMsg(msg, paste0("'peakThr' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'peakThr' has to be a ", + "positive numeric of length 1.")) if (length(object@tuneIn) != 1) - msg <- validMsg(msg, paste0("'tuneIn' has to be a ", - "logical of length 1.")) - if (is.null(msg)) { - return(TRUE) - } else { - return(msg) - } + msg <- c(msg, paste0("'tuneIn' has to be a ", + "logical of length 1.")) + if (length(msg)) + msg + else TRUE }) -##' @title Two-step centWave feature detection considering also feature isotopes +##' @title Two-step centWave peak detection considering also isotopes ##' ##' @aliases centWaveWithPredIsoROIs ##' -##' @description This method performs a two-step centWave-based feature -##' detection: in a first centWave run features are identified for which then +##' @description This method performs a two-step centWave-based chromatographic +##' peak detection: in a first centWave run peaks are identified for which then ##' the location of their potential isotopes in the mz-retention time is ##' predicted. A second centWave run is then performed on these -##' \emph{regions of interest} (ROIs). The final list of features comprises all -##' non-overlapping features from both centWave runs. +##' \emph{regions of interest} (ROIs). The final list of chromatographic peaks +##' comprises all non-overlapping peaks from both centWave runs. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @param maxCharge integer(1) defining the maximal isotope charge. Isotopes -##' will be defined for charges \code{1:maxCharge}. +##' @param maxCharge \code{integer(1)} defining the maximal isotope charge. +##' Isotopes will be defined for charges \code{1:maxCharge}. ##' -##' @param maxIso integer(1) defining the number of isotope peaks that should be -##' predicted for each feature identified in the first centWave run. +##' @param maxIso \code{integer(1)} defining the number of isotope peaks that +##' should be predicted for each peak identified in the first centWave run. ##' -##' @param mzIntervalExtension logical(1) whether the mz range for the predicted -##' isotope ROIs should be extended to increase detection of low intensity peaks. +##' @param mzIntervalExtension \code{logical(1)} whether the mz range for the +##' predicted isotope ROIs should be extended to increase detection of low +##' intensity peaks. ##' -##' @param snthreshIsoROIs numeric(1) defining the signal to noise ratio cutoff -##' to be used in the second centWave run to identify features for predicted +##' @param snthreshIsoROIs \code{numeric(1)} defining the signal to noise ratio +##' cutoff to be used in the second centWave run to identify peaks for predicted ##' isotope ROIs. ##' -##' @param polarity character(1) specifying the polarity of the data. Currently -##' not used, but has to be \code{"positive"}, \code{"negative"} or +##' @param polarity \code{character(1)} specifying the polarity of the data. +##' Currently not used, but has to be \code{"positive"}, \code{"negative"} or ##' \code{"unknown"} if provided. ##' ##' @details See \code{\link{centWave}} for details on the centWave method. ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{findPeaks}} methods. It supports feature detection on -##' \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +##' \code{\link{findPeaks}} methods. It supports chromatographic peak detection +##' on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} ##' objects (both defined in the \code{MSnbase} package). All of the settings -##' to the centWave algorithm can be passed with a \code{CentWaveParam} object. +##' to the algorithm can be passed with a \code{CentWavePredIsoParam} object. ##' -##' @family feature detection methods -##' @seealso The \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}} core +##' @family peak detection methods +##' @seealso The \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}} core ##' API function and \code{\link{findPeaks.centWave}} for the old user interface. ##' \code{\link{CentWaveParam}} for the class the \code{CentWavePredIsoParam} ##' extends. ##' -##' @name featureDetection-centWaveWithPredIsoROIs +##' @name findChromPeaks-centWaveWithPredIsoROIs ##' @author Hendrik Treutler, Johannes Rainer NULL #> NULL ##' @description The \code{CentWavePredIsoParam} class allows to specify all -##' settings for the two-step centWave-based feature detection considering also -##' predicted isotopes of features identified in the first centWave run. +##' settings for the two-step centWave-based peak detection considering also +##' predicted isotopes of peaks identified in the first centWave run. ##' Instances should be created with the \code{CentWavePredIsoParam} constructor. ##' See also the documentation of the \code{\link{CentWaveParam}} for all methods ##' and arguments this class inherits. @@ -1155,7 +1152,7 @@ NULL ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs ##' ##' @examples ##' @@ -1182,106 +1179,109 @@ setClass("CentWavePredIsoParam", polarity = "unknown" ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@snthreshIsoROIs) != 1 | any(object@snthreshIsoROIs < 0)) - msg <- validMsg(msg, paste0("'snthreshIsoROIs' has to be a ", - "positive numeric of length 1.")) + msg <- c(msg, paste0("'snthreshIsoROIs' has to be a ", + "positive numeric of length 1.")) if (length(object@maxCharge) != 1 | any(object@maxCharge < 0)) - msg <- validMsg(msg, paste0("'maxCharge' has to be a ", - "positive integer of length 1.")) + msg <- c(msg, paste0("'maxCharge' has to be a ", + "positive integer of length 1.")) if (length(object@maxIso) != 1 | any(object@maxIso < 0)) - msg <- validMsg(msg, paste0("'maxIso' has to be a ", - "positive integer of length 1.")) + msg <- c(msg, paste0("'maxIso' has to be a ", + "positive integer of length 1.")) if (length(object@mzIntervalExtension) != 1) - msg <- validMsg(msg, paste0("'mzIntervalExtension' has to be a", - " logical of length 1.")) + msg <- c(msg, paste0("'mzIntervalExtension' has to be a", + " logical of length 1.")) if (length(object@polarity) != 1) - msg <- validMsg(msg, paste0("'polarity' has to be a", - " character of length 1.")) + msg <- c(msg, paste0("'polarity' has to be a", + " character of length 1.")) if (!(object@polarity %in% c("positive", "negative", "unknown"))) - msg <- validMsg(msg, paste0("'polarity' has to be either ", - "'positive', 'negative' or ", - "'unknown'!")) - if (is.null(msg)) - return(TRUE) - else - return(msg) + msg <- c(msg, paste0("'polarity' has to be either ", + "'positive', 'negative' or ", + "'unknown'!")) + if (length(msg)) + msg + else TRUE }) -## General groupFeatures method. -##' @title Feature alignment methods. +## General groupChromPeaks method. +##' @title Correspondence: Chromatographic peak grouping methods. ##' -##' @description The \code{groupFeatures} method(s) perform alignment of features -##' within and between samples. These methods are part of the modernized -##' \code{xcms} user interface. +##' @description The \code{groupChromPeaks} method(s) perform the correspondence, +##' i.e. the grouping of chromatographic peaks within and between samples. +##' These methods are part of the modernized \code{xcms} user interface. +##' The resulting peak groups are referred to as (mz-rt) features and can be +##' accessed \emph{via} the \code{\link{featureDefinitions}} method on the result +##' object. ##' -##' The implemented feature alignment methods are: +##' The implemented peak grouping methods are: ##' \describe{ -##' \item{density}{feature alignment based on time dimension feature densities. -##' See \code{\link{groupFeatures-density}} for more details.} +##' \item{density}{peak grouping based on time dimension peak densities. +##' See \code{\link{groupChromPeaks-density}} for more details.} ##' -##' \item{mzClust}{high resolution feature alignment for single spectra (direct -##' infusion) MS data. See \code{\link{groupFeatures-mzClust}} for more details.} +##' \item{mzClust}{high resolution peak grouping for single spectra (direct +##' infusion) MS data. See \code{\link{groupChromPeaks-mzClust}} for more +##' details.} ##' -##' \item{nearest}{feature alignment based on their proximity in the mz-rt space. -##' See \code{\link{groupFeatures-nearest}} for more details.} +##' \item{nearest}{chromatographic peak grouping based on their proximity in +##' the mz-rt space. See \code{\link{groupChromPeaks-nearest}} for more details.} ##' ##' } -##' @name groupFeatures -##' @family feature alignment methods -##' @seealso \code{\link{group}} for the \emph{old} feature alignment -##' methods. -##' @seealso \code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -##' for methods to access feature grouping results. +##' @name groupChromPeaks +##' @family peak grouping methods +##' @seealso \code{\link{group}} for the \emph{old} peak grouping methods. +##' @seealso \code{\link{featureDefinitions}} and +##' \code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +##' results. ##' ##' @author Johannes Rainer NULL #> NULL -## Main group.density documentation. -##' @title Feature alignment based on time dimension feature densities +##' @title Peak grouping based on time dimension peak densities ##' -##' @description This method performs performs feature alignment based on the -##' density (distribution) of identified features along the retention time axis -##' within slices of overlapping mz ranges. All features (from the same or from -##' different samples) being close on the retention time axis are grouped into -##' a \emph{feature group}. +##' @description This method performs performs correspondence (chromatographic +##' peak grouping) based on the density (distribution) of identified peaks +##' along the retention time axis within slices of overlapping mz ranges. +##' All peaks (from the same or from different samples) being close on the +##' retention time axis are grouped into a feature (\emph{peak group}). ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{group}} methods. All of the settings to the alignment algorithm -##' can be passed with a \code{FeatureDensityParam} object. +##' \code{\link{group}} methods. All of the settings to the algorithm +##' can be passed with a \code{PeakDensityParam} object. ##' ##' @param sampleGroups A vector of the same length than samples defining the -##' sample group assignments. +##' sample group assignments (i.e. which samples belong to which sample group). ##' -##' @param bw numeric(1) defining the bandwidth (standard deviation ot the +##' @param bw \code{numeric(1)} defining the bandwidth (standard deviation ot the ##' smoothing kernel) to be used. This argument is passed to the ##' \code{\link{density}} method. ##' -##' @param minFraction numeric(1) defining the minimum fraction of samples in at -##' least one sample group in which the features have to be present to be -##' considered as a feature group. +##' @param minFraction \code{numeric(1)} defining the minimum fraction of samples +##' in at least one sample group in which the peaks have to be present to be +##' considered as a peak group (feature). ##' -##' @param minSamples numeric(1) with the minimum number of samples in at least -##' one sample group in which the features have to be detected to be considered -##' as a feature group. +##' @param minSamples \code{numeric(1)} with the minimum number of samples in at +##' least one sample group in which the peaks have to be detected to be +##' considered a peak group (feature). ##' -##' @param binSize numeric(1) defining the size of the overlapping slices in mz -##' dimension. +##' @param binSize \code{numeric(1)} defining the size of the overlapping slices +##' in mz dimension. ##' -##' @param maxFeatures numeric(1) with the maximum number of feature groups to -##' be identified in a single mz slice. +##' @param maxFeatures \code{numeric(1)} with the maximum number of peak groups +##' to be identified in a single mz slice. ##' -##' @family feature alignment methods -##' @seealso The \code{\link{do_groupFeatures_density}} core +##' @family peak grouping methods +##' @seealso The \code{\link{do_groupChromPeaks_density}} core ##' API function and \code{\link{group.density}} for the old user interface. -##' @seealso \code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -##' for methods to access feature grouping results. +##' @seealso \code{\link{featureDefinitions}} and +##' \code{\link{groupval,XCMSnExp-method}} for methods to access the features +##' (i.e. the peak grouping results). ##' -##' @name groupFeatures-density +##' @name groupChromPeaks-density ##' ##' @author Colin Smith, Johannes Rainer ##' @@ -1293,31 +1293,31 @@ NULL NULL #> NULL -##' @description The \code{FeatureDensityParam} class allows to specify all -##' settings for the feature alignment based on feature densities along the time -##' dimension. Instances should be created with the \code{FeatureDensityParam} +##' @description The \code{PeakDensityParam} class allows to specify all +##' settings for the peak grouping based on peak densities along the time +##' dimension. Instances should be created with the \code{PeakDensityParam} ##' constructor. ##' ##' @slot .__classVersion__,sampleGroups,bw,minFraction,minSamples,binSize,maxFeatures See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname groupFeatures-density +##' @rdname groupChromPeaks-density ##' ##' @examples ##' -##' ## Create a FeatureDensityParam object -##' p <- FeatureDensityParam(binSize = 0.05) +##' ## Create a PeakDensityParam object +##' p <- PeakDensityParam(binSize = 0.05) ##' ## Change hte minSamples slot ##' minSamples(p) <- 3 ##' p ##' ##' ############################## -##' ## feature detection and alignment. +##' ## Chromatographic peak detection and grouping. ##' ## -##' ## Below we perform first a feature detection (using the matchedFilter +##' ## Below we perform first a peak detection (using the matchedFilter ##' ## method) on some of the test files from the faahKO package followed by -##' ## a feature alignment using the density method. +##' ## a peak grouping using the density method. ##' library(faahKO) ##' library(MSnbase) ##' fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, @@ -1326,28 +1326,28 @@ NULL ##' ## Reading 2 of the KO samples ##' raw_data <- readMSData2(fls[1:2]) ##' -##' ## Perform the feature detection using the matchedFilter method. +##' ## Perform the chromatographic peak detection using the matchedFilter method. ##' mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -##' res <- detectFeatures(raw_data, param = mfp) +##' res <- findChromPeaks(raw_data, param = mfp) ##' -##' head(features(res)) -##' ## The number of features identified per sample: -##' table(features(res)[, "sample"]) +##' head(chromPeaks(res)) +##' ## The number of peaks identified per sample: +##' table(chromPeaks(res)[, "sample"]) ##' -##' ## Performing the feature alignment -##' fdp <- FeatureDensityParam() -##' res <- groupFeatures(res, fdp) +##' ## Performing the chromatographic peak grouping +##' fdp <- PeakDensityParam() +##' res <- groupChromPeaks(res, fdp) ##' -##' ## The results from the feature alignment: -##' featureGroups(res) +##' ## The definition of the features (peak groups): +##' featureDefinitions(res) ##' ##' ## Using the groupval method to extract a matrix with the intensities of -##' ## the feature groups per sample. +##' ## the features per sample. ##' head(groupval(res, value = "into")) ##' ##' ## The process history: ##' processHistory(res) -setClass("FeatureDensityParam", +setClass("PeakDensityParam", slots = c(sampleGroups = "ANY", bw = "numeric", minFraction = "numeric", @@ -1363,55 +1363,57 @@ setClass("FeatureDensityParam", binSize = 0.25, maxFeatures = 50), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@bw) > 1 | any(object@bw < 0)) - msg <- validMsg(msg, paste0("'bw' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'bw' has to be a ", + "positive numeric of length 1!")) if (length(object@minFraction) > 1 | any(object@minFraction < 0) | any(object@minFraction > 1)) - msg <- validMsg(msg, paste0("'minFraction' has to be a ", - "single positive number between ", - "0 and 1!")) + msg <- c(msg, paste0("'minFraction' has to be a ", + "single positive number between ", + "0 and 1!")) if (length(object@minSamples) > 1 | any(object@minSamples < 0)) - msg <- validMsg(msg, paste0("'minSamples' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'minSamples' has to be a ", + "positive numeric of length 1!")) if (length(object@binSize) > 1 | any(object@binSize < 0)) - msg <- validMsg(msg, paste0("'binSize' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'binSize' has to be a ", + "positive numeric of length 1!")) if (length(object@maxFeatures) > 1 | any(object@maxFeatures < 0)) - msg <- validMsg(msg, paste0("'maxFeatures' has to be a ", + msg <- c(msg, paste0("'maxFeatures' has to be a ", "positive numeric of length 1!")) - if (is.null(msg)) - return(TRUE) - else + if (length(msg)) return(msg) + else + return(TRUE) }) ## Main group.mzClust documentation. -##' @title High resolution feature alignment for single spectra samples +##' @title High resolution peak grouping for single spectra samples ##' -##' @description This method performs high resolution alignment for single +##' @description This method performs high resolution correspondence for single ##' spectra samples. ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{group}} methods. All of the settings to the alignment algorithm +##' \code{\link{group}} methods. All of the settings to the algorithm ##' can be passed with a \code{MzClustParam} object. ##' -##' @inheritParams groupFeatures-density +##' @inheritParams groupChromPeaks-density ##' -##' @param ppm numeric(1) representing the relative mz error for the +##' @param ppm \code{numeric(1)} representing the relative mz error for the ##' clustering/grouping (in parts per million). ##' -##' @param absMz numeric(1) representing the absolute mz error for the clustering. +##' @param absMz \code{numeric(1)} representing the absolute mz error for the +##' clustering. ##' -##' @family feature alignment methods -##' @seealso The \code{\link{do_groupFeatures_mzClust}} core +##' @family peak grouping methods +##' @seealso The \code{\link{do_groupPeaks_mzClust}} core ##' API function and \code{\link{group.mzClust}} for the old user interface. -##' @seealso \code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -##' for methods to access feature grouping results. +##' @seealso \code{\link{featureDefinitions}} and +##' \code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +##' results (i.e. the features). ##' -##' @name groupFeatures-mzClust +##' @name groupChromPeaks-mzClust ##' ##' @references Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill ##' and David F. Grant\cr \emph{Alignment of high resolution mass spectra: @@ -1421,14 +1423,14 @@ NULL #> NULL ##' @description The \code{MzClustParam} class allows to specify all -##' settings for the feature alignment based on the \emph{mzClust} algorithm. +##' settings for the peak grouping based on the \emph{mzClust} algorithm. ##' Instances should be created with the \code{MzClustParam} constructor. ##' ##' @slot .__classVersion__,sampleGroups,ppm,absMz,minFraction,minSamples See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust ##' ##' @examples ##' @@ -1438,20 +1440,21 @@ NULL ##' recursive = TRUE, full.names = TRUE) ##' fticr <- readMSData2(fticrf[1:2], msLevel. = 1) ##' -##' ## Perform the MSW feature detection on these: +##' ## Perform the MSW peak detection on these: ##' p <- MSWParam(scales = c(1, 7), peakThr = 80000, ampTh = 0.005, ##' SNR.method = "data.mean", winSize.noise = 500) -##' fticr <- detectFeatures(fticr, param = p) +##' fticr <- findChromPeaks(fticr, param = p) ##' -##' head(features(fticr)) +##' head(chromPeaks(fticr)) ##' ##' ## Now create the MzClustParam parameter object: we're assuming here that ##' ## both samples are from the same sample group. ##' p <- MzClustParam(sampleGroups = c(1, 1)) ##' -##' fticr <- groupFeatures(fticr, param = p) +##' fticr <- groupChromPeaks(fticr, param = p) ##' -##' featureGroups(fticr) +##' ## Get the definition of the features. +##' featureDefinitions(fticr) setClass("MzClustParam", slots = c(sampleGroups = "ANY", ppm = "numeric", @@ -1466,63 +1469,66 @@ setClass("MzClustParam", minFraction = 0.5, minSamples = 1), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@ppm) > 1 | any(object@ppm < 0)) - msg <- validMsg(msg, paste0("'ppm' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'ppm' has to be a ", + "positive numeric of length 1!")) if (length(object@absMz) > 1 | any(object@absMz < 0)) - msg <- validMsg(msg, paste0("'absMz' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'absMz' has to be a ", + "positive numeric of length 1!")) if (length(object@minFraction) > 1 | any(object@minFraction < 0) | any(object@minFraction > 1)) - msg <- validMsg(msg, paste0("'minFraction' has to be a ", - "single positive number between ", - "0 and 1!")) + msg <- c(msg, paste0("'minFraction' has to be a ", + "single positive number between ", + "0 and 1!")) if (length(object@minSamples) > 1 | any(object@minSamples < 0)) - msg <- validMsg(msg, paste0("'minSamples' has to be a ", - "positive numeric of length 1!")) - if (is.null(msg)) - return(TRUE) + msg <- c(msg, paste0("'minSamples' has to be a ", + "positive numeric of length 1!")) + if (length(msg)) + msg else - return(msg) + TRUE }) ## Main group.nearest documentation. -##' @title Feature alignment based on proximity in the mz-rt space +##' @title Peak grouping based on proximity in the mz-rt space ##' -##' @description This method is inspired by the alignment algorithm of mzMine -##' [Katajamaa 2006] and performs alignment based on proximity of features in the -##' space spanned by retention time and mz values. -##' The method creates first a \emph{master feature list} consisting of all -##' features from the sample in which most features were identified, and -##' starting from that, calculates distances to features from the sample with the -##' next most features. If features are closer than the defined threshold they -##' are grouped together. +##' @description This method is inspired by the grouping algorithm of mzMine +##' [Katajamaa 2006] and performs correspondence based on proximity of peaks in +##' the space spanned by retention time and mz values. +##' The method creates first a \emph{master peak list} consisting of all +##' chromatographic peaks from the sample in which most peaks were identified, +##' and starting from that, calculates distances to peaks from the sample with +##' the next most number of peaks. If peaks are closer than the defined +##' threshold they are grouped together. ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the -##' \code{\link{group}} methods. All of the settings to the alignment algorithm -##' can be passed with a \code{NearestFeaturesParam} object. +##' \code{\link{group}} methods. All of the settings to the algorithm +##' can be passed with a \code{NearestPeaksParam} object. ##' -##' @inheritParams groupFeatures-density +##' @inheritParams groupChromPeaks-density ##' -##' @param mzVsRtBalance numeric(1) representing the factor by which mz values are -##' multiplied before calculating the (euclician) distance between two features. +##' @param mzVsRtBalance \code{numeric(1)} representing the factor by which mz +##' values are multiplied before calculating the (euclician) distance between +##' two peaks. ##' -##' @param absMz numeric(1) maximum tolerated distance for mz values. +##' @param absMz \code{numeric(1)} maximum tolerated distance for mz values. ##' -##' @param absRt numeric(1) maximum tolerated distance for rt values. +##' @param absRt \code{numeric(1)} maximum tolerated distance for rt values. ##' -##' @param kNN numeric(1) representing the number of nearest neighbors to check. +##' @param kNN \code{numeric(1)} representing the number of nearest neighbors +##' to check. ##' -##' @family feature alignment methods +##' @family peak grouping methods ##' -##' @seealso The \code{\link{do_groupFeatures_nearest}} core +##' @seealso The \code{\link{do_groupChromPeaks_nearest}} core ##' API function and \code{\link{group.nearest}} for the old user interface. -##' @seealso \code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -##' for methods to access feature grouping results. +##' @seealso \code{\link{featureDefinitions}} and +##' \code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +##' results (i.e. the features). ##' -##' @name groupFeatures-nearest +##' @name groupChromPeaks-nearest ##' ##' @references Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for ##' processing and visualization of mass spectrometry based molecular profile @@ -1530,28 +1536,28 @@ setClass("MzClustParam", NULL #> NULL -##' @description The \code{NearestFeaturesParam} class allows to specify all -##' settings for the feature alignment based on the \emph{nearest} algorithm. -##' Instances should be created with the \code{NearestFeaturesParam} constructor. +##' @description The \code{NearestPeaksParam} class allows to specify all +##' settings for the peak grouping based on the \emph{nearest} algorithm. +##' Instances should be created with the \code{NearestPeaksParam} constructor. ##' ##' @slot .__classVersion__,sampleGroups,mzVsRtBalance,absMz,absRt,kNN See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname groupFeatures-nearest +##' @rdname groupChromPeaks-nearest ##' ##' @examples ##' -##' ## Create a NearestFeaturesParam object -##' p <- NearestFeaturesParam(kNN = 3) +##' ## Create a NearestPeaksParam object +##' p <- NearestPeaksParam(kNN = 3) ##' p ##' ##' ############################## -##' ## feature detection and alignment. +##' ## Chromatographi peak detection and grouping. ##' ## -##' ## Below we perform first a feature detection (using the matchedFilter -##' ## method) on some of the test files from the faahKO package followed by -##' ## a feature alignment using the "nearest" method. +##' ## Below we perform first a chromatographic peak detection (using the +##' ## matchedFilter method) on some of the test files from the faahKO package +##' ## followed by a peaks grouping using the "nearest" method. ##' library(faahKO) ##' library(MSnbase) ##' fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, @@ -1560,28 +1566,28 @@ NULL ##' ## Reading 2 of the KO samples ##' raw_data <- readMSData2(fls[1:2]) ##' -##' ## Perform the feature detection using the matchedFilter method. +##' ## Perform the peak detection using the matchedFilter method. ##' mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -##' res <- detectFeatures(raw_data, param = mfp) +##' res <- findChromPeaks(raw_data, param = mfp) ##' -##' head(features(res)) -##' ## The number of features identified per sample: -##' table(features(res)[, "sample"]) +##' head(chromPeaks(res)) +##' ## The number of peaks identified per sample: +##' table(chromPeaks(res)[, "sample"]) ##' -##' ## Performing the feature alignment -##' p <- NearestFeaturesParam() -##' res <- groupFeatures(res, param = p) +##' ## Performing the peak grouping +##' p <- NearestPeaksParam() +##' res <- groupChromPeaks(res, param = p) ##' -##' ## The results from the feature alignment: -##' featureGroups(res) +##' ## The results from the peak grouping: +##' featureDefinitions(res) ##' ##' ## Using the groupval method to extract a matrix with the intensities of -##' ## the feature groups per sample. +##' ## the features per sample. ##' head(groupval(res, value = "into")) ##' ##' ## The process history: ##' processHistory(res) -setClass("NearestFeaturesParam", +setClass("NearestPeaksParam", slots = c(sampleGroups = "ANY", mzVsRtBalance = "numeric", absMz = "numeric", @@ -1595,40 +1601,42 @@ setClass("NearestFeaturesParam", absRt = 15, kNN = 10), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@mzVsRtBalance) > 1 | any(object@mzVsRtBalance < 0)) - msg <- validMsg(msg, paste0("'mzVsRtBalance' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'mzVsRtBalance' has to be a ", + "positive numeric of length 1!")) if (length(object@absMz) > 1 | any(object@absMz < 0)) - msg <- validMsg(msg, paste0("'absMz' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'absMz' has to be a ", + "positive numeric of length 1!")) if (length(object@absRt) > 1 | any(object@absRt < 0)) - msg <- validMsg(msg, paste0("'absRt' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'absRt' has to be a ", + "positive numeric of length 1!")) if (length(object@kNN) > 1 | any(object@kNN < 0)) - msg <- validMsg(msg, paste0("'kNN' has to be a ", - "positive numeric of length 1!")) - if (is.null(msg)) - return(TRUE) - else - return(msg) + msg <- c(msg, paste0("'kNN' has to be a ", + "positive numeric of length 1!")) + if (length(msg)) + msg + else TRUE }) -##' @title Retention time correction methods. +##' @title Alignment: Retention time correction methods. ##' ##' @description The \code{adjustRtime} method(s) perform retention time -##' correction between chromatograms of different samples. These methods are -##' part of the modernized \code{xcms} user interface. +##' correction (alignment) between chromatograms of different samples. These +##' methods are part of the modernized \code{xcms} user interface. ##' -##' The implemented feature alignment methods are: +##' The implemented retention time adjustment methods are: ##' \describe{ -##' \item{featureGroups}{retention time correction based on aligment of feature -##' groups present in most/all samples. -##' See \code{\link{adjustRtime-featureGroups}} for more details.} -##' +##' \item{peakGroups}{retention time correction based on aligment of features +##' (peak groups) present in most/all samples. +##' See \code{\link{adjustRtime-peakGroups}} for more details.} +##' +##' \item{obiwarp}{alignment based on the complete mz-rt data. This method does +##' not require any identified peaks or defined features. See +##' \code{\link{adjustRtime-obiwarp}} for more details.} ##' } ##' @name adjustRtime ##' @family retention time correction methods @@ -1639,13 +1647,13 @@ NULL #> NULL ## Main retcor.peakgroups documentation. -##' @title Retention time correction based on alignment of house keeping feature +##' @title Retention time correction based on alignment of house keeping peak ##' groups ##' ##' @description This method performs retention time adjustment based on the -##' alignment of feature groups present in all/most samples (hence corresponding -##' to house keeping compounds). First the retention time deviation of these -##' feature groups is described by fitting either a polynomial +##' alignment of chromatographic peak groups present in all/most samples (hence +##' corresponding to house keeping compounds). First the retention time deviation +##' of these peak groups is described by fitting either a polynomial ##' (\code{smooth = "loess"}) or a linear (\code{smooth = "linear"}) model to the ##' data points. These models are subsequently used to adjust the retention time ##' of each spectrum in each sample. @@ -1653,27 +1661,28 @@ NULL ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the ##' \code{\link{group}} methods. All of the settings to the alignment algorithm -##' can be passed with a \code{FeatureGroupsParam} object. -##' -##' @param minFraction numeric(1) between 0 and 1 defining the minimum required -##' fraction of samples in which features for the feature group were identified. -##' Feature groups passing this criteria will aligned across samples and retention -##' times of individual spectra will be adjusted based on this alignment. For -##' \code{minFraction = 1} the feature group has to contain features in all -##' samples of the experiment. +##' can be passed with a \code{PeakGroupsParam} object. +##' +##' @param minFraction \code{numeric(1)} between 0 and 1 defining the minimum +##' required fraction of samples in which peaks for the peak group were +##' identified. Peak groups passing this criteria will aligned across samples +##' and retention times of individual spectra will be adjusted based on this +##' alignment. For \code{minFraction = 1} the peak group has to contain peaks +##' in all samples of the experiment. ##' -##' @param extraFeatures numeric(1) defining the maximal number of additional -##' features for all samples to be assigned to a feature group for retention time -##' correction. For a data set with 6 samples, \code{extraFeatures = 1} uses all -##' feature groups with a total feature count \code{<= 6 + 1}. The total feature -##' count is the total number of features being assigned to a feature group and -##' considers also multiple features within a sample being assigned to the group. +##' @param extraPeaks \code{numeric(1)} defining the maximal number of additional +##' peaks for all samples to be assigned to a peak group (i.e. feature) for +##' retention time correction. For a data set with 6 samples, +##' \code{extraPeaks = 1} uses all peak groups with a total peak count +##' \code{<= 6 + 1}. The total peak count is the total number of peaks being +##' assigned to a peak group and considers also multiple peaks within a sample +##' being assigned to the group. ##' ##' @param smooth character defining the function to be used, to interpolate -##' corrected retention times for all feature groups. Either \code{"loess"} or +##' corrected retention times for all peak groups. Either \code{"loess"} or ##' \code{"linear"}. ##' -##' @param span numeric(1) defining the degree of smoothing (if +##' @param span \code{numeric(1)} defining the degree of smoothing (if ##' \code{smooth = "loess"}). This parameter is passed to the internal call ##' to \code{\link{loess}}. ##' @@ -1683,10 +1692,10 @@ NULL ##' ##' @family retention time correction methods ##' -##' @seealso The \code{\link{do_adjustRtime_featureGroups}} core +##' @seealso The \code{\link{do_adjustRtime_peakGroups}} core ##' API function and \code{\link{retcor.peakgroups}} for the old user interface. ##' -##' @name adjustRtime-featureGroups +##' @name adjustRtime-peakGroups ##' ##' @author Colin Smith, Johannes Rainer ##' @@ -1698,51 +1707,51 @@ NULL NULL #> NULL -##' @description The \code{FeatureGroupsParam} class allows to specify all +##' @description The \code{PeakGroupsParam} class allows to specify all ##' settings for the retention time adjustment based on \emph{house keeping} -##' feature groups present in most samples. -##' Instances should be created with the \code{FeatureGroupsParam} constructor. +##' peak groups present in most samples. +##' Instances should be created with the \code{PeakGroupsParam} constructor. ##' -##' @slot .__classVersion__,minFraction,extraFeatures,smooth,span,family See corresponding parameter above. \code{.__classVersion__} stores +##' @slot .__classVersion__,minFraction,extraPeaks,smooth,span,family See corresponding parameter above. \code{.__classVersion__} stores ##' the version from the class. Slots values should exclusively be accessed ##' \emph{via} the corresponding getter and setter methods listed above. ##' -##' @rdname adjustRtime-featureGroups +##' @rdname adjustRtime-peakGroups ##' ##' @examples ##' ############################## -##' ## feature detection and alignment. +##' ## Chromatographic peak detection and grouping. ##' ## -##' ## Below we perform first a feature detection (using the matchedFilter +##' ## Below we perform first a peak detection (using the matchedFilter ##' ## method) on some of the test files from the faahKO package followed by -##' ## a feature alignment. +##' ## a peak grouping. ##' library(faahKO) -##' library(MSnbase) +##' library(xcms) ##' fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, ##' full.names = TRUE) ##' ##' ## Reading 2 of the KO samples ##' raw_data <- readMSData2(fls[1:2]) ##' -##' ## Perform the feature detection using the matchedFilter method. +##' ## Perform the peak detection using the matchedFilter method. ##' mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -##' res <- detectFeatures(raw_data, param = mfp) +##' res <- findChromPeaks(raw_data, param = mfp) ##' -##' head(features(res)) -##' ## The number of features identified per sample: -##' table(features(res)[, "sample"]) +##' head(chromPeaks(res)) +##' ## The number of peaks identified per sample: +##' table(chromPeaks(res)[, "sample"]) ##' -##' ## Performing the feature alignment using the "feature density" method. -##' p <- FeatureDensityParam(sampleGroups = c(1, 1)) -##' res <- groupFeatures(res, param = p) +##' ## Performing the peak grouping using the "peak density" method. +##' p <- PeakDensityParam(sampleGroups = c(1, 1)) +##' res <- groupChromPeaks(res, param = p) ##' -##' ## Perform the retention time adjustment using feature groups found in both +##' ## Perform the retention time adjustment using peak groups found in both ##' ## files. -##' fgp <- FeatureGroupsParam(minFraction = 1) +##' fgp <- PeakGroupsParam(minFraction = 1) ##' res <- adjustRtime(res, param = fgp) ##' ##' ## Any grouping information was dropped -##' hasAlignedFeatures(res) +##' hasFeatures(res) ##' ##' ## Plot the raw against the adjusted retention times. ##' plot(rtime(raw_data), rtime(res), pch = 16, cex = 0.25, col = fromFile(res)) @@ -1756,46 +1765,45 @@ NULL ##' ##' ## To extract the retention times grouped by sample/file: ##' rts <- rtime(res, bySample = TRUE) -setClass("FeatureGroupsParam", +setClass("PeakGroupsParam", slots = c(minFraction = "numeric", - extraFeatures = "numeric", + extraPeaks = "numeric", smooth = "character", span = "numeric", family = "character"), contains = "Param", prototype = prototype( minFraction = 0.9, - extraFeatures = 1, + extraPeaks = 1, smooth = "loess", span = 0.2, family = "gaussian" ), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@minFraction) > 1 | any(object@minFraction < 0) | any(object@minFraction > 1)) - msg <- validMsg(msg, paste0("'minFraction' has to be a single", - " number between 0 and 1!")) - if (length(object@extraFeatures) > 1 | - any(object@extraFeatures < 0)) - msg <- validMsg(msg, paste0("'extraFeatures' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'minFraction' has to be a single", + " number between 0 and 1!")) + if (length(object@extraPeaks) > 1 | + any(object@extraPeaks < 0)) + msg <- c(msg, paste0("'extraPeaks' has to be a ", + "positive numeric of length 1!")) if (length(object@span) > 1 | any(object@span < 0)) - msg <- validMsg(msg, paste0("'span' has to be a ", - "positive numeric of length 1!")) + msg <- c(msg, paste0("'span' has to be a ", + "positive numeric of length 1!")) if (length(object@smooth) > 1 | !all(object@smooth %in% c("loess", "linear"))) - msg <- validMsg(msg, paste0("'smooth' has to be either \"", - "loess\" or \"linear\"!")) + msg <- c(msg, paste0("'smooth' has to be either \"", + "loess\" or \"linear\"!")) if (length(object@family) > 1 | !all(object@family %in% c("gaussian", "symmetric"))) - msg <- validMsg(msg, paste0("'family' has to be either \"", - "gaussian\" or \"symmetric\"!")) - if (is.null(msg)) - return(TRUE) - else - return(msg) + msg <- c(msg, paste0("'family' has to be either \"", + "gaussian\" or \"symmetric\"!")) + if (length(msg)) + msg + else TRUE }) ##' @title Align retention times across samples using Obiwarp @@ -1805,23 +1813,24 @@ setClass("FeatureGroupsParam", ##' \url{http://obi-warp.sourceforge.net} but supports alignment of multiple ##' samples by aligning each against a \emph{center} sample. The alignment is ##' performed directly on the \code{\link{profile-matrix}} and can hence be -##' performed independently of the feature detection or feature grouping. +##' performed independently of the peak detection or peak grouping. ##' ##' @note These methods and classes are part of the updated and modernized ##' \code{xcms} user interface which will eventually replace the ##' \code{\link{retcor}} methods. All of the settings to the alignment algorithm ##' can be passed with a \code{ObiwarpParam} object. ##' -##' @param binSize numeric(1) defining the bin size (in mz dimension) to be used -##' for the \emph{profile matrix} generation. See \code{step} parameter in -##' \code{\link{profile-matrix}} documentation for more details. +##' @param binSize \code{numeric(1)} defining the bin size (in mz dimension) +##' to be used for the \emph{profile matrix} generation. See \code{step} +##' parameter in \code{\link{profile-matrix}} documentation for more details. ##' -##' @param centerSample integer(1) defining the index of the center sample in the -##' experiment. It defaults to \code{floor(median(1:length(fileNames(object))))}. +##' @param centerSample \code{integer(1)} defining the index of the center sample +##' in the experiment. It defaults to +##' \code{floor(median(1:length(fileNames(object))))}. ##' -##' @param response numeric(1) defining the \emph{responsiveness} of warping with -##' \code{response = 0} giving linear warping on start and end points and -##' \code{response = 100} warping using all bijective anchors. +##' @param response \code{numeric(1)} defining the \emph{responsiveness} of +##' warping with \code{response = 0} giving linear warping on start and end +##' points and \code{response = 100} warping using all bijective anchors. ##' ##' @param distFun character defining the distance function to be used. Allowed ##' values are \code{"cor"} (Pearson's correlation), \code{"cor_opt"} (calculate @@ -1829,28 +1838,28 @@ setClass("FeatureGroupsParam", ##' (covariance), \code{"prd"} (product) and \code{"euc"} (Euclidian distance). ##' The default value is \code{distFun = "cor_opt"}. ##' -##' @param gapInit numeric(1) defining the penalty for gap opening. The default -##' value for \code{gapInit} depends on the value of \code{distFun}: for +##' @param gapInit \code{numeric(1)} defining the penalty for gap opening. The +##' default value for \code{gapInit} depends on the value of \code{distFun}: for ##' \code{distFun = "cor"} and \code{distFun = "cor_opt"} it is \code{0.3}, for ##' \code{distFun = "cov"} and \code{distFun = "prd"} \code{0.0} and for ##' \code{distFun = "euc"} \code{0.9}. ##' -##' @param gapExtend numeric(1) defining the penalty for gap enlargement. The -##' default value for \code{gapExtend} depends on the value of \code{distFun}, +##' @param gapExtend \code{numeric(1)} defining the penalty for gap enlargement. +##' The default value for \code{gapExtend} depends on the value of \code{distFun}, ##' for \code{distFun = "cor"} and \code{distFun = "cor_opt"} it is \code{2.4}, ##' for \code{distFun = "cov"} \code{11.7}, for \code{distFun = "euc"} \code{1.8} ##' and for \code{distFun = "prd"} {7.8}. ##' -##' @param factorDiag numeric(1) defining the local weight applied to diagonal -##' moves in the alignment. +##' @param factorDiag \code{numeric(1)} defining the local weight applied to +##' diagonal moves in the alignment. ##' -##' @param factorGap numeric(1) defining the local weight for gap moves in the -##' alignment. +##' @param factorGap \code{numeric(1)} defining the local weight for gap moves +##' in the alignment. ##' -##' @param localAlignment logical(1) whether a local alignment should be +##' @param localAlignment \code{logical(1)} whether a local alignment should be ##' performed instead of the default global alignment. ##' -##' @param initPenalty numeric(1) defining the penalty for initiating an +##' @param initPenalty \code{numeric(1)} defining the penalty for initiating an ##' alignment (for local alignment only). ##' ##' @family retention time correction methods @@ -1903,9 +1912,10 @@ NULL ##' ############################## ##' ## Perform retention time correction on an XCMSnExp: ##' ## -##' ## Perform first the feature detection using the matchedFilter method. +##' ## Perform first the chromatographic peak detection using the matchedFilter +##' ## method. ##' mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -##' res <- detectFeatures(raw_data, param = mfp) +##' res <- findChromPeaks(raw_data, param = mfp) ##' ##' ## Performing the retention time adjustment using obiwarp. ##' res_2 <- adjustRtime(res, param = ObiwarpParam()) @@ -1913,9 +1923,9 @@ NULL ##' head(rtime(res_2)) ##' head(rtime(raw_data)) ##' -##' ## Also the retention times of the detected features were adjusted. -##' tail(features(res)) -##' tail(features(res_2)) +##' ## Also the retention times of the detected peaks were adjusted. +##' tail(chromPeaks(res)) +##' tail(chromPeaks(res_2)) setClass("ObiwarpParam", slots = c(binSize = "numeric", centerSample = "integer", @@ -1940,48 +1950,47 @@ setClass("ObiwarpParam", localAlignment = FALSE, initPenalty = 0), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@binSize) > 1 | any(object@binSize < 0)) - msg <- validMsg(msg, paste0("'binSize' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'binSize' has to be a positive", + " numeric of length 1!")) if (length(object@centerSample) > 1 | any(object@centerSample < 0)) - msg <- validMsg(msg, paste0("'centerSample' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'centerSample' has to be a positive", + " numeric of length 1!")) if (length(object@response) > 1 | any(object@response < 0) | any(object@response > 100)) - msg <- validMsg(msg, paste0("'response' has to be a single ", - " integer from 1 to 100!")) + msg <- c(msg, paste0("'response' has to be a single ", + " integer from 1 to 100!")) if (length(object@distFun) > 1 | any(!(object@distFun %in% c("cor", "cor_opt", "cov", "euc", "prd")))) - msg <- validMsg(msg, paste0("'distFun' has to be one of \"cor\"", - ", \"cor_opt\", \"cov\", \"euc\"", - " or \"prd\"!")) + msg <- c(msg, paste0("'distFun' has to be one of \"cor\"", + ", \"cor_opt\", \"cov\", \"euc\"", + " or \"prd\"!")) if (length(object@gapInit) > 1 | any(object@gapInit < 0)) - msg <- validMsg(msg, paste0("'gapInit' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'gapInit' has to be a positive", + " numeric of length 1!")) if (length(object@gapExtend) > 1 | any(object@gapExtend < 0)) - msg <- validMsg(msg, paste0("'gapExtend' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'gapExtend' has to be a positive", + " numeric of length 1!")) if (length(object@factorDiag) > 1 | any(object@factorDiag < 0)) - msg <- validMsg(msg, paste0("'factorDiag' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'factorDiag' has to be a positive", + " numeric of length 1!")) if (length(object@factorGap) > 1 | any(object@factorGap < 0)) - msg <- validMsg(msg, paste0("'factorGap' has to be a positive", - " numeric of length 1!")) + msg <- c(msg, paste0("'factorGap' has to be a positive", + " numeric of length 1!")) if (length(object@localAlignment) > 1) - msg <- validMsg(msg, paste0("'localAlignment' has to be a ", - "logical of length 1!")) + msg <- c(msg, paste0("'localAlignment' has to be a ", + "logical of length 1!")) if (length(object@initPenalty) > 1 | any(object@initPenalty < 0)) - msg <- validMsg(msg, paste0("'initPenalty' has to be a positive", - " numeric of length 1!")) - if (is.null(msg)) - return(TRUE) - else - return(msg) + msg <- c(msg, paste0("'initPenalty' has to be a positive", + " numeric of length 1!")) + if (length(msg)) + msg + else TRUE }) @@ -1991,68 +2000,70 @@ setClass("ObiwarpParam", ##' ##' @description The \code{MsFeatureData} class is designed to encapsule all ##' data related to the preprocessing of metabolomics data using the \code{xcms} -##' package, i.e. it contains a \code{matrix} with the features identified by the -##' feature detection, a \code{DataFrame} with the information on aligned -##' features across samples and a \code{list} with the adjusted retention times -##' per sample. +##' package, i.e. it contains a \code{matrix} with the chromatographic peaks +##' identified by the peak detection, a \code{DataFrame} with the definition on +##' grouped chromatographic peaks across samples and a \code{list} with the +##' adjusted retention times per sample. ##' ##' @rdname XCMSnExp-class setClass("MsFeatureData", contains = c("environment", "Versioned"), prototype = prototype(.xData = new.env(parent = emptyenv()))) -.XCMS_REQ_FEATS_COLS <- c("mz", "mzmin", "mzmax", "rt", "rtmin", - "rtmax", "into", "sample") -.XCMS_REQ_FEATG_COLS <- c("mzmed", "mzmin", "mzmax", "rtmed", "rtmin", "rtmax", - "featureidx") +.REQ_PEAKS_COLS <- c("mz", "mzmin", "mzmax", "rt", "rtmin", + "rtmax", "into", "sample") +.REQ_PEAKG_COLS <- c("mzmed", "mzmin", "mzmax", "rtmed", "rtmin", "rtmax", + "peakidx") ##' @aliases XCMSnExp ##' @title Data container storing xcms preprocessing results ##' ##' @description The \code{XCMSnExp} object is designed to contain all results -##' from metabolomics data preprocessing (feature detection, feature alignment -##' and retention time correction). The corresponding elements in the -##' \code{msFeatureData} slot are \code{"features"} (a \code{matrix}), -##' \code{"featureGroups"} (a \code{DataFrame}) and \code{"adjustedRtime"} (a -##' \code{list} of numeric vectors). Note that these should not be accessed -##' directly but rather \emph{via} their accessor methods. Along with the results, -##' the object contains the processing history that allow to track each -##' processing step along with the used settings. The object also directly -##' extends the \code{\link[MSnbase]{OnDiskMSnExp}} object hence allowing easy -##' access to the full data on which the feature detection was performed. +##' from metabolomics data preprocessing (chromatographic peak detection, peak +##' grouping (correspondence) and retention time correction). The corresponding +##' elements in the \code{msFeatureData} slot are \code{"chromPeaks"} +##' (a \code{matrix}), \code{"featureDefinitions"} (a \code{DataFrame}) and +##' \code{"adjustedRtime"} (a \code{list} of numeric vectors). Note that these +##' should not be accessed directly but rather \emph{via} their accessor methods. +##' Along with the results, the object contains the processing history that +##' allow to track each processing step along with the used settings. The object +##' also directly extends the \code{\link[MSnbase]{OnDiskMSnExp}} object hence +##' allowing easy access to the full data on which the peak detection was +##' performed. ##' ##' Objects from this class should not be created directly, they are returned as -##' result from the \code{\link{detectFeatures}} method. +##' result from the \code{\link{findChromPeaks}} method. ##' ##' \code{XCMSnExp} objects can be coerced into \code{\linkS4class{xcmsSet}} ##' objects using the \code{as} method. ##' -##' @note The \code{"features"} element in the \code{msFeatureData} slot is +##' @note The \code{"chromPeaks"} element in the \code{msFeatureData} slot is ##' equivalent to the \code{@peaks} slot of the \code{xcmsSet} object, the -##' \code{"featureGroups"} contains information from the \code{} +##' \code{"featureDefinitions"} contains information from the \code{@groups} and +##' \code{@groupidx} slots from an \code{xcmsSet} object. ##' ##' @slot .processHistory \code{list} with \code{XProcessHistory} objects ##' tracking all individual analysis steps that have been performed. ##' ##' @slot msFeatureData \code{MsFeatureData} class extending \code{environment} -##' and containing the results from a feature detection (element -##' \code{"features"}), feature alignment (element \code{"featureGroups"}) and -##' retention time correction (element \code{""}) steps. +##' and containing the results from a chromatographic peak detection (element +##' \code{"chromPeaks"}), peak grouping (element \code{"featureDefinitions"}) +##' and retention time correction (element \code{"adjustedRtime"}) steps. ##' -##' @param object For \code{adjustedRtime}, \code{featureGroups}, -##' \code{features}, \code{hasAdjustedRtime}, \code{hasAlignedFeatures} and -##' \code{hasDetectedFeatures} either a \code{MsFeatureData} or a \code{XCMSnExp} +##' @param object For \code{adjustedRtime}, \code{featureDefinitions}, +##' \code{chromPeaks}, \code{hasAdjustedRtime}, \code{hasFeatures} and +##' \code{hasChromPeaks} either a \code{MsFeatureData} or a \code{XCMSnExp} ##' object, for all other methods a \code{XCMSnExp} object. ##' ##' @param value For \code{adjustedRtime<-}: a \code{list} (length equal to the ##' number of samples) with numeric vectors representing the adjusted retention ##' times per scan. ##' -##' For \code{featureGroups<-}: a \code{DataFrame} with feature -##' alignment information. See return value for the \code{featureGroups} method -##' for the expected format. +##' For \code{featureDefinitions<-}: a \code{DataFrame} with peak +##' grouping information. See return value for the \code{featureDefinitions} +##' method for the expected format. ##' -##' For \code{features<-}: a \code{matrix} with information on -##' detected features. See return value for the \code{features} method for the +##' For \code{chromPeaks<-}: a \code{matrix} with information on +##' detected peaks. See return value for the \code{chromPeaks} method for the ##' expected format. ##' ##' @author Johannes Rainer @@ -2060,11 +2071,11 @@ setClass("MsFeatureData", contains = c("environment", "Versioned"), ##' @seealso \code{\linkS4class{xcmsSet}} for the old implementation. ##' @seealso \code{\link[MSnbase]{OnDiskMSnExp}}, \code{\link[MSnbase]{MSnExp}} ##' and \code{\link[MSnbase]{pSet}} for a complete list of inherited methods. -##' @seealso \code{\link{detectFeatures}} for available feature detection methods +##' @seealso \code{\link{findChromPeaks}} for available peak detection methods ##' returning a \code{XCMSnExp} object as a result. -##' @seealso \code{\link{groupFeatures}} for available feature grouping methods -##' and \code{\link{groupval,XCMSnExp-method}} for the method to extract feature -##' grouping results. +##' @seealso \code{\link{groupChromPeaks}} for available peak grouping +##' methods and \code{\link{featureDefinitions}} for the method to extract +##' the feature definitions representing the peak grouping results. ##' @seealso \code{\link{adjustRtime}} for retention time adjustment methods. ##' ##' @rdname XCMSnExp-class @@ -2075,24 +2086,24 @@ setClass("MsFeatureData", contains = c("environment", "Versioned"), ##' library(faahKO) ##' od <- readMSData2(c(system.file("cdf/KO/ko15.CDF", package = "faahKO"), ##' system.file("cdf/KO/ko16.CDF", package = "faahKO"))) -##' ## Now we perform a feature detection on this data set using the +##' ## Now we perform a chromatographic peak detection on this data set using the ##' ## matched filter method. We are tuning the settings such that it performs ##' ## faster. ##' mfp <- MatchedFilterParam(binSize = 4) -##' xod <- detectFeatures(od, param = mfp) +##' xod <- findChromPeaks(od, param = mfp) ##' -##' ## The results from the feature detection are now stored in the XCMSnExp +##' ## The results from the peak detection are now stored in the XCMSnExp ##' ## object ##' xod ##' -##' ## The detected features can be accessed with the features method. -##' head(features(xod)) +##' ## The detected peaks can be accessed with the chromPeaks method. +##' head(chromPeaks(xod)) ##' -##' ## The settings of the feature detection can be accessed with the -##' ## processHistory method +##' ## The settings of the chromatographic peak detection can be accessed with +##' ## the processHistory method ##' processHistory(xod) ##' -##' ## Also the parameter class for the feature detection can be accessed +##' ## Also the parameter class for the peak detection can be accessed ##' processParam(processHistory(xod)[[1]]) ##' ##' ## The XCMSnExp inherits all methods from the pSet and OnDiskMSnExp classes @@ -2120,16 +2131,16 @@ setClass("MsFeatureData", contains = c("environment", "Versioned"), ##' ## ##' ## XCMSnExp objects can be filtered by file, retention time, mz values or ##' ## MS level. For some of these filter preprocessing results (mostly -##' ## retention time correction and feature alignment results) will be dropped. +##' ## retention time correction and peak grouping results) will be dropped. ##' ## Below we filter the XCMSnExp object by file to extract the results for ##' ## only the second file. ##' xod_2 <- filterFile(xod, file = 2) ##' xod_2 ##' -##' ## Now the objects contains only the idenfified features for the second file -##' head(features(xod_2)) +##' ## Now the objects contains only the idenfified peaks for the second file +##' head(chromPeaks(xod_2)) ##' -##' head(features(xod)[features(xod)[, "sample"] == 2, ]) +##' head(chromPeaks(xod)[chromPeaks(xod)[, "sample"] == 2, ]) ##' ##' ########## ##' ## Coercing to an xcmsSet object @@ -2148,56 +2159,94 @@ setClass("XCMSnExp", ), contains = c("OnDiskMSnExp"), validity = function(object) { - msg <- validMsg(NULL, NULL) + msg <- character() if (length(object@.processHistory) > 0) { isOK <- unlist(lapply(object@.processHistory, function(z) { return(inherits(z, "ProcessHistory")) })) if (!all(isOK)) - msg <- validMsg(msg, paste0("Only 'ProcessHistory' ", - "objects are allowed in slot ", - ".processHistory!")) + msg <- c(msg, paste0("Only 'ProcessHistory' ", + "objects are allowed in slot ", + ".processHistory!")) } ## TODO @jo add checks: ## 1) call validMsFeatureData - msg <- validMsg(msg, validateMsFeatureData(object@msFeatureData)) - if (!is.null(msg)) return(msg) - ## 2) features[, "sample"] is within 1:number of samples - if (any(ls(object@msFeatureData) == "features")) { - if (!all(object@msFeatureData$features[, "sample"] %in% + msg <- c(msg, validateMsFeatureData(object@msFeatureData)) + if (length(msg)) return(msg) + ## 2) peaks[, "sample"] is within 1:number of samples + if (any(ls(object@msFeatureData) == "chromPeaks")) { + if (!all(object@msFeatureData$chromPeaks[, "sample"] %in% 1:length(fileNames(object)))) - msg <- validMsg(msg, paste0("The number of available ", - "samples does not match with ", - "the sample assignment of ", - "features in the 'features' ", - "element of the msFeatureData ", - "slot!")) + msg <- c(msg, paste0("The number of available ", + "samples does not match with ", + "the sample assignment of ", + "peaks in the 'chromPeaks' ", + "element of the msFeatureData ", + "slot!")) } ## 3) Check that the length of the adjustedRtime matches! if (any(ls(object@msFeatureData) == "adjustedRtime")) { rt <- rtime(object, bySample = TRUE) if (length(rt) != length(object@msFeatureData$adjustedRtime)) { - msg <- validMsg(msg, paste0("The number of numeric vectors", - " in the 'adjustedRtime' element", - " of the msFeatureData slot does", - " not match the number of", - " samples!")) + msg <- c(msg, paste0("The number of numeric vectors", + " in the 'adjustedRtime' element", + " of the msFeatureData slot does", + " not match the number of", + " samples!")) } else { if (any(lengths(rt) != lengths(object@msFeatureData$adjustedRtime))) - msg <- validMsg(msg, - paste0("The lengths of the numeric ", - "vectors in the 'adjustedRtime'", - " element of the msFeatureData ", - "slot does not match the number", - " of scans per sample!")) + msg <- c(msg, + paste0("The lengths of the numeric ", + "vectors in the 'adjustedRtime'", + " element of the msFeatureData ", + "slot does not match the number", + " of scans per sample!")) } } - ## 3) If we've got features, check that we have also a related + ## 3) If we've got peaks, check that we have also a related ## processing history step. - if (is.null(msg)) - return(TRUE) - else return(msg) + if (length(msg)) + msg + else TRUE } ) +##' @title Representation of chromatographic MS data +##' +##' @description The \code{Chromatogram} class is designed to store +##' chromatographic MS data, i.e. pairs of retention time and intensity values. +##' Instances of the class can be created with the \code{Chromatogram} +##' constructor function but in most cases the dedicated methods for +##' \code{\link{OnDiskMSnExp}} and \code{\link{XCMSnExp}} objects extracting +##' chromatograms should be used instead. +##' +##' @details The \code{mz}, \code{filterMz} are stored as a \code{numeric(2)} +##' representing a range even if the chromatogram represent the chromatogram for +##' a single ion (represented as a single mz value). Representing the \code{mz} +##' as a range allows this class also to be used for a total ion chromatogram +##' or base peak chromatogram. +##' +##' @rdname Chromatogram-class +##' @author Johannes Rainer +setClass("Chromatogram", + slots = c( + rtime = "numeric", + intensity = "numeric", + mz = "numeric", + filterMz = "numeric", + fromFile = "integer", + aggregationFun = "character" + ), + contains = "Versioned", + prototype = prototype( + rtime = numeric(), + intensity = numeric(), + mz = c(0, 0), + filterMz = c(0, 0), + fromFile = integer(), + aggregationFun = character() + ), + validity = function(object) + validChromatogram(object) + ) diff --git a/R/MPI.R b/R/MPI.R index 65fefbb97..f682023b7 100644 --- a/R/MPI.R +++ b/R/MPI.R @@ -42,14 +42,18 @@ findPeaksPar <- function(arg) { peaks <- do.call(method, args = c(list(object = xRaw), params)) - list(scantime=xRaw@scantime, - peaks=cbind(peaks, - sample = rep.int(myID, nrow(peaks))), + ## Ensure to remove data to avoid memory accumulation. + scanT <- xRaw@scantime + rm(xRaw) + gc() + list(scantime = scanT, + peaks = cbind(peaks, + sample = rep.int(myID, nrow(peaks))), date = procDate) } ############################################################ -## detectFeatures +## findChromPeaks ## ## Same as findPeaksPar but without the need to pass argument lists ## and read settings from the global options. @@ -58,7 +62,7 @@ findPeaksPar <- function(arg) { ## o readParams: parameter class to read the file; actually we would only ## need the scanrange, the includeMSn and the lockMassFreq here. ## o detectParams: parameter class for the peak detection. -detectFeaturesInFile <- function(args) { +findChromPeaksInFile <- function(args) { ## Placeholder } diff --git a/R/do_adjustRtime-functions.R b/R/do_adjustRtime-functions.R index 3a7442bdb..4bb108647 100644 --- a/R/do_adjustRtime-functions.R +++ b/R/do_adjustRtime-functions.R @@ -1,37 +1,33 @@ ## Retention time correction methods. #' @include DataClasses.R functions-MsFeatureData.R -## Needs: -## o features -## o feature groups -## o rtime - -##' @title Align spectrum retention times across samples using feature groups +##' @title Align spectrum retention times across samples using peak groups ##' found in most samples ##' ##' @description The function performs retention time correction by assessing -##' the retention time deviation across all samples using feature groups containg -##' features present in most/all samples. The retention time deviation -##' for these feature groups in each sample is described by fitting either a -##' polynomial (\code{smooth = "loess"}) or a linear (\code{smooth = "linear"}) -##' model to the data points. The models are subsequently used to adjust the -##' retention time for each spectrum in each sample. +##' the retention time deviation across all samples using peak groups (features) +##' containg chromatographic peaks present in most/all samples. The retention +##' time deviation for these features in each sample is described by fitting +##' either a polynomial (\code{smooth = "loess"}) or a linear +##' (\code{smooth = "linear"}) model to the data points. The models are +##' subsequently used to adjust the retention time for each spectrum in each +##' sample. ##' ##' @details The alignment bases on the presence of compounds that can be found ##' in all/most samples of an experiment. The retention times of individual -##' spectra are then adjusted based on the alignment of the feature groups +##' spectra are then adjusted based on the alignment of the features ##' corresponding to these \emph{house keeping compounds}. The paraneters -##' \code{minFraction} and \code{extraFeatures} can be used to fine tune which -##' feature groups should be used for the alignment (i.e. which feature groups +##' \code{minFraction} and \code{extraPeaks} can be used to fine tune which +##' features should be used for the alignment (i.e. which features ##' most likely correspond to the above mentioned house keeping compounds). ##' -##' @inheritParams adjustRtime-featureGroups +##' @inheritParams adjustRtime-peakGroups ##' -##' @param features a \code{matrix} or \code{data.frame} with the identified -##' features in the samples. +##' @param peaks a \code{matrix} or \code{data.frame} with the identified +##' chromatographic peaks in the samples. ##' -##' @param featureIndex a \code{list} of indices that provides the grouping -##' information of the features (across and within samples). +##' @param peakIndex a \code{list} of indices that provides the grouping +##' information of the chromatographic peaks (across and within samples). ##' ##' @param rtime A \code{list} of \code{numeric} vectors with the retention times ##' per file/sample. @@ -48,50 +44,50 @@ ##' Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite ##' Profiling Using Nonlinear Peak Alignment, Matching, and Identification" ##' \emph{Anal. Chem.} 2006, 78:779-787. -do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, - minFraction = 0.9, extraFeatures = 1, - smooth = c("loess", "linear"), span = 0.2, - family = c("gaussian", "symmetric")) { +do_adjustRtime_peakGroups <- function(peaks, peakIndex, rtime, + minFraction = 0.9, extraPeaks = 1, + smooth = c("loess", "linear"), span = 0.2, + family = c("gaussian", "symmetric")) { ## Check input. - if (missing(features) | missing(featureIndex) | missing(rtime)) - stop("Arguments 'features', 'featureIndex' and 'rtime' are required!") + if (missing(peaks) | missing(peakIndex) | missing(rtime)) + stop("Arguments 'peaks', 'peakIndex' and 'rtime' are required!") smooth <- match.arg(smooth) family <- match.arg(family) ## minFraction if (any(minFraction > 1) | any(minFraction < 0)) stop("'minFraction' has to be between 0 and 1!") - ## Check features: - OK <- .validFeatureMatrix(features) + ## Check peaks: + OK <- .validChromPeaksMatrix(peaks) if (is.character(OK)) stop(OK) - ## Check featureIndex: - if (any(!(unique(unlist(featureIndex)) %in% seq_len(nrow(features))))) - stop("Some indices listed in 'featureIndex' are outside of ", - "1:nrow(features)!") + ## Check peakIndex: + if (any(!(unique(unlist(peakIndex)) %in% seq_len(nrow(peaks))))) + stop("Some indices listed in 'peakIndex' are outside of ", + "1:nrow(peaks)!") ## Check rtime: in line with the total number of samples we've got in - ## features? + ## peaks? if (!is.list(rtime)) stop("'rtime' should be a list of numeric vectors with the retention ", "times of the spectra per sample!") if (!all(unlist(lapply(rtime, is.numeric), use.names = FALSE))) stop("'rtime' should be a list of numeric vectors with the retention ", "times of the spectra per sample!") - if (length(rtime) != max(features[, "sample"])) + if (length(rtime) != max(peaks[, "sample"])) stop("The length of 'rtime' does not match with the total number of ", - "samples according to the 'features' matrix!") + "samples according to the 'peaks' matrix!") nSamples <- length(rtime) ## Translate minFraction to number of allowed missing samples. missingSample <- nSamples - (nSamples * minFraction) - rt <- .getFeatureGroupsRtMatrix(features, featureIndex, nSamples, - missingSample, extraFeatures) + rt <- .getPeakGroupsRtMatrix(peaks, peakIndex, nSamples, + missingSample, extraPeaks) message("Performing retention time correction using ", nrow(rt), - " feature groups.") + " peak groups.") - ## Calculate the deviation of each feature group in each sample from its + ## Calculate the deviation of each peak group in each sample from its ## median rtdev <- rt - apply(rt, 1, median, na.rm = TRUE) @@ -99,12 +95,12 @@ do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, mingroups <- min(colSums(!is.na(rt))) if (mingroups < 4) { smooth <- "linear" - warning("Too few feature groups for 'loess', reverting to linear", + warning("Too few peak groups for 'loess', reverting to linear", " method") } else if (mingroups * span < 4) { span <- 4 / mingroups warning("Span too small for 'loess' and the available number of ", - "feature groups, resetting to ", round(span, 2)) + "peak groups, resetting to ", round(span, 2)) } } @@ -143,7 +139,7 @@ do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, warn.overcorrect <- TRUE } else { if (nrow(pts) < 2) { - stop("Not enough feature groups even for linear smoothing ", + stop("Not enough peak groups even for linear smoothing ", "available!") } ## Use lm instead? @@ -185,7 +181,7 @@ do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, ##' @examples ##' ##' ## Perform retention time correction: -##' ## feats is supposed to be the features matrix FOR A SINGLE SAMPLE, rtr and +##' ## feats is supposed to be the peaks matrix FOR A SINGLE SAMPLE, rtr and ##' ## rtc the raw and adjusted retention times of the spectras from the same ##' ## samples: ##' ## adjFts <- feats @@ -198,11 +194,11 @@ do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, } ##' Helper function to apply retention time adjustment to already identified -##' features in the features matrix of an XCMSnExp (or peaks matrix of an +##' peaks in the peaks matrix of an XCMSnExp (or peaks matrix of an ##' xcmsSet). ##' ##' @noRd -.applyRtAdjToFeatures <- function(x, rtraw, rtadj) { +.applyRtAdjToChromPeaks <- function(x, rtraw, rtadj) { if (!is.list(rtraw) | !is.list(rtadj)) stop("'rtraw' and 'rtadj' are supposed to be lists!") if (length(rtraw) != length(rtadj)) @@ -221,37 +217,37 @@ do_adjustRtime_featureGroups <- function(features, featureIndex, rtime, } ##' Simple helper function to create a matrix with retention times for well -##' aligned feature groups, each row containing the rt of a feature group, +##' aligned peak groups, each row containing the rt of a peak group, ##' columns being samples. ##' @details This function is called internally by the -##' do_adjustRtime_featureGroups function and the retcor.peakgroups method. +##' do_adjustRtime_peakGroups function and the retcor.peakgroups method. ##' @noRd -.getFeatureGroupsRtMatrix <- function(features, featureIndex, nSamples, - missingSample, extraFeatures) { - ## For each feature group: - ## o extract the retention time of the feature with the highest intensity. - ## o skip feature groups if they are not assigned a feature in at least a - ## minimum number of samples OR if have too many features from the same +.getPeakGroupsRtMatrix <- function(peaks, peakIndex, nSamples, + missingSample, extraPeaks) { + ## For each peak group: + ## o extract the retention time of the peak with the highest intensity. + ## o skip peak groups if they are not assigned a peak in at least a + ## minimum number of samples OR if have too many peaks from the same ## sample assigned to it. seq_samp <- seq_len(nSamples) - rt <- lapply(featureIndex, function(z) { - cur_fts <- features[z, c("rt", "into", "sample"), drop = FALSE] + rt <- lapply(peakIndex, function(z) { + cur_fts <- peaks[z, c("rt", "into", "sample"), drop = FALSE] ## Return NULL if we've got less samples that required or is the total - ## number of features is larger than a certain threshold. + ## number of peaks is larger than a certain threshold. ## Note that the original implementation is not completely correct! - ## nsamp > nsamp + extraFeatures might be correct. + ## nsamp > nsamp + extraPeaks might be correct. nsamp <- length(unique(cur_fts[, "sample"])) if (nsamp < (nSamples - missingSample) | - nrow(cur_fts) > (nsamp + extraFeatures)) + nrow(cur_fts) > (nsamp + extraPeaks)) return(NULL) cur_fts[] <- cur_fts[order(cur_fts[, 2], decreasing = TRUE), ] cur_fts[match(seq_samp, cur_fts[, 3]), 1] }) rt <- do.call(rbind, rt) ## Order them by median retention time. NOTE: this is different from the - ## original code, in which the feature groups are ordered by the median - ## retention time that is calculated over ALL features within the feature - ## group, not only to one feature selected for each sample (for multi - ## feature per sample assignments). + ## original code, in which the peak groups are ordered by the median + ## retention time that is calculated over ALL peaks within the peak + ## group, not only to one peak selected for each sample (for multi + ## peak per sample assignments). return(rt[order(rowMedians(rt, na.rm = TRUE)), , drop = FALSE]) } diff --git a/R/do_detectFeatures-functions.R b/R/do_findChromPeaks-functions.R similarity index 91% rename from R/do_detectFeatures-functions.R rename to R/do_findChromPeaks-functions.R index 2b96a4949..f117b33bd 100644 --- a/R/do_detectFeatures-functions.R +++ b/R/do_findChromPeaks-functions.R @@ -1,4 +1,5 @@ -## All low level (API) analysis functions for feature detection should go in here. +## All low level (API) analysis functions for chromatographic peak detection +## should go in here. #' @include c.R functions-binning.R cwTools.R ############################################################ @@ -13,10 +14,11 @@ ## Conclusion: ## o speed improvement can only come from internal methods called withihn. ## -##' @title Core API function for centWave feature detection +##' @title Core API function for centWave peak detection ##' -##' @description This function performs peak density and wavelet based feature -##' detection for high resolution LC/MS data in centroid mode [Tautenhahn 2008]. +##' @description This function performs peak density and wavelet based +##' chromatographic peak detection for high resolution LC/MS data in centroid +##' mode [Tautenhahn 2008]. ##' ##' @details This algorithm is most suitable for high resolution ##' LC/\{TOF,OrbiTrap,FTICR\}-MS data in centroid mode. In the first phase the @@ -30,7 +32,7 @@ ##' @note The \emph{centWave} was designed to work on centroided mode, thus it ##' is expected that such data is presented to the function. ##' -##' This function exposes core feature detection functionality of +##' This function exposes core chromatographic peak detection functionality of ##' the \emph{centWave} method. While this function can be called directly, ##' users will generally call the corresponding method for the data object ##' instead. @@ -43,25 +45,26 @@ ##' spectra/scans of the data representing the retention time of each scan. ##' @param valsPerSpect Numeric vector with the number of values for each ##' spectrum. -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @family core feature detection functions +##' @family core peak detection functions ##' @references ##' Ralf Tautenhahn, Christoph B\"{o}ttcher, and Steffen Neumann "Highly ##' sensitive feature detection for high resolution LC/MS" \emph{BMC Bioinformatics} ##' 2008, 9:504 ##' @return -##' A matrix, each row representing an identified feature, with columns: +##' A matrix, each row representing an identified chromatographic peak, +##' with columns: ##' \describe{ -##' \item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} -##' \item{rt}{Retention time of the feature's midpoint.} -##' \item{rtmin}{Minimum retention time of the feature.} -##' \item{rtmax}{Maximum retention time of the feature.} -##' \item{into}{Integrated (original) intensity of the feature.} -##' \item{intb}{Per-feature baseline corrected integrated feature intensity.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +##' \item{mzmin}{Minimum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} +##' \item{rt}{Retention time of the peak's midpoint.} +##' \item{rtmin}{Minimum retention time of the peak.} +##' \item{rtmax}{Maximum retention time of the peak.} +##' \item{into}{Integrated (original) intensity of the peak.} +##' \item{intb}{Per-peak baseline corrected integrated peak intensity.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{sn}{Signal to noise ratio, defined as \code{(maxo - baseline)/sd}, ##' \code{sd} being the standard deviation of local chromatographic noise.} ##' \item{egauss}{RMSE of Gaussian fit.} @@ -73,7 +76,7 @@ ##' \item{h}{Gaussian parameter h.} ##' \item{f}{Region number of the m/z ROI where the peak was localized.} ##' \item{dppm}{m/z deviation of mass trace across scanns in ppk.} -##' \item{scale}{Scale on which the feature was localized.} +##' \item{scale}{Scale on which the peak was localized.} ##' \item{scpos}{Peak position found by wavelet analysis (scan number).} ##' \item{scmin}{Left peak limit found by wavelet analysis (scan number).} ##' \item{scmax}{Right peak limit found by wavelet analysis (scan numer).} @@ -88,7 +91,7 @@ ##' fs <- system.file('cdf/KO/ko15.CDF', package = "faahKO") ##' xr <- xcmsRaw(fs, profstep = 0) ##' -##' ## Extracting the data from the xcmsRaw for do_detectFeatures_centWave +##' ## Extracting the data from the xcmsRaw for do_findChromPeaks_centWave ##' mzVals <- xr@env$mz ##' intVals <- xr@env$intensity ##' ## Define the values per spectrum: @@ -97,10 +100,10 @@ ##' ## Calling the function. We're using a large value for noise to speed up ##' ## the call in the example performance - in a real use case we would either ##' ## set the value to a reasonable value or use the default value. -##' res <- do_detectFeatures_centWave(mz = mzVals, int = intVals, +##' res <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, ##' scantime = xr@scantime, valsPerSpect = valsPerSpect, noise = 10000) ##' head(res) -do_detectFeatures_centWave <- function(mz, int, scantime, valsPerSpect, +do_findChromPeaks_centWave <- function(mz, int, scantime, valsPerSpect, ppm = 25, peakwidth = c(20, 50), snthresh = 10, @@ -293,7 +296,7 @@ do_detectFeatures_centWave <- function(mz, int, scantime, valsPerSpect, ## cat('\n Detecting chromatographic peaks ... \n % finished: ') ## lp <- -1 - message("Detecting features in ", length(roiList), + message("Detecting chromatographic peaks in ", length(roiList), " regions of interest ...", appendLF = FALSE) for (f in 1:lf) { @@ -645,21 +648,21 @@ do_detectFeatures_centWave <- function(mz, int, scantime, valsPerSpect, ############################################################ ## massifquant ## -##' @title Core API function for massifquant feature detection +##' @title Core API function for massifquant peak detection ##' -##' @description Massifquant is a Kalman filter (KF)-based feature -##' detection for XC-MS data in centroid mode. The identified features +##' @description Massifquant is a Kalman filter (KF)-based chromatographic peak +##' detection for XC-MS data in centroid mode. The identified peaks ##' can be further refined with the \emph{centWave} method (see -##' \code{\link{do_detectFeatures_centWave}} for details on centWave) +##' \code{\link{do_findChromPeaks_centWave}} for details on centWave) ##' by specifying \code{withWave = TRUE}. ##' ##' @details This algorithm's performance has been tested rigorously ##' on high resolution LC/{OrbiTrap, TOF}-MS data in centroid mode. -##' Simultaneous kalman filters identify features and calculate their +##' Simultaneous kalman filters identify peaks and calculate their ##' area under the curve. The default parameters are set to operate on ##' a complex LC-MS Orbitrap sample. Users will find it useful to do some ##' simple exploratory data analysis to find out where to set a minimum -##' intensity, and identify how many scans an average feature spans. The +##' intensity, and identify how many scans an average peak spans. The ##' \code{consecMissedLimit} parameter has yielded good performance on ##' Orbitrap data when set to (\code{2}) and on TOF data it was found best ##' to be at (\code{1}). This may change as the algorithm has yet to be @@ -669,25 +672,26 @@ do_detectFeatures_centWave <- function(mz, int, scantime, valsPerSpect, ##' The \code{ppm} and \code{checkBack} parameters have shown less influence ##' than the other parameters and exist to give users flexibility and ##' better accuracy. -##' @inheritParams do_detectFeatures_centWave -##' @inheritParams featureDetection-centWave -##' @inheritParams featureDetection-massifquant +##' @inheritParams do_findChromPeaks_centWave +##' @inheritParams findChromPeaks-centWave +##' @inheritParams findChromPeaks-massifquant ##' @return -##' A matrix, each row representing an identified feature, with columns: +##' A matrix, each row representing an identified chromatographic peak, +##' with columns: ##' \describe{ -##' \item{mz}{Intensity weighted mean of m/z values of the features across +##' \item{mz}{Intensity weighted mean of m/z values of the peaks across ##' scans.} -##' \item{mzmin}{Minumum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} -##' \item{rtmin}{Minimum retention time of the feature.} -##' \item{rtmax}{Maximum retention time of the feature.} -##' \item{rt}{Retention time of the feature's midpoint.} -##' \item{into}{Integrated (original) intensity of the feature.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{mzmin}{Minumum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} +##' \item{rtmin}{Minimum retention time of the peak.} +##' \item{rtmax}{Maximum retention time of the peak.} +##' \item{rt}{Retention time of the peak's midpoint.} +##' \item{into}{Integrated (original) intensity of the peak.} +##' \item{maxo}{Maximum intensity of the peak.} ##' } ##' If \code{withWave} is set to \code{TRUE}, the result is the same as -##' returned by the \code{\link{do_detectFeatures_centWave}} method. -##' @family core feature detection functions +##' returned by the \code{\link{do_findChromPeaks_centWave}} method. +##' @family core peak detection functions ##' @seealso \code{\link{massifquant}} for the standard user interface method. ##' @references ##' Conley CJ, Smith R, Torgrip RJ, Taylor RM, Tautenhahn R and Prince JT @@ -708,11 +712,11 @@ do_detectFeatures_centWave <- function(mz, int, scantime, valsPerSpect, ##' ## Define the values per spectrum: ##' valsPerSpect <- diff(c(xraw@scanindex, length(mzVals))) ##' -##' ## Perform the feature detection using massifquant -##' res <- do_detectFeatures_massifquant(mz = mzVals, int = intVals, +##' ## Perform the peak detection using massifquant +##' res <- do_findChromPeaks_massifquant(mz = mzVals, int = intVals, ##' scantime = xraw@scantime, valsPerSpect = valsPerSpect) ##' head(res) -do_detectFeatures_massifquant <- function(mz, +do_findChromPeaks_massifquant <- function(mz, int, scantime, valsPerSpect, @@ -770,7 +774,7 @@ do_detectFeatures_massifquant <- function(mz, ppm = ppm) message("OK") if (withWave) { - featlist <- do_detectFeatures_centWave(mz = mz, int = int, + featlist <- do_findChromPeaks_centWave(mz = mz, int = int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, @@ -795,7 +799,7 @@ do_detectFeatures_massifquant <- function(mz, return(nopeaks) } - ## Get the max intensity for each feature. + ## Get the max intensity for each peak. maxo <- lapply(massifquantROIs, function(z) { raw <- .rawMat(mz = mz, int = int, scantime = scantime, valsPerSpect = valsPerSpect, @@ -858,18 +862,18 @@ do_detectFeatures_massifquant <- function(mz, ## impute: none (=bin), binlin, binlinbase, intlin ## baseValue default: min(int)/2 (smallest value in the whole data set). ## -##' @title Core API function for matchedFilter feature detection +##' @title Core API function for matchedFilter peak detection ##' -##' @description This function identifies features in the chromatographic +##' @description This function identifies peaks in the chromatographic ##' time domain as described in [Smith 2006]. The intensity values are ##' binned by cutting The LC/MS data into slices (bins) of a mass unit ##' (\code{binSize} m/z) wide. Within each bin the maximal intensity is -##' selected. The feature detection is then performed in each bin by +##' selected. The peak detection is then performed in each bin by ##' extending it based on the \code{steps} parameter to generate slices ##' comprising bins \code{current_bin - steps +1} to \code{current_bin + steps - 1}. ##' Each of these slices is then filtered with matched filtration using -##' a second-derative Gaussian as the model feature/peak shape. After filtration -##' features are detected using a signal-to-ration cut-off. For more details +##' a second-derative Gaussian as the model peak shape. After filtration +##' peaks are detected using a signal-to-ration cut-off. For more details ##' and illustrations see [Smith 2006]. ##' ##' @details The intensities are binned by the provided m/z values within each @@ -881,30 +885,31 @@ do_detectFeatures_massifquant <- function(mz, ##' \code{\link{binYonX}} and \code{\link{imputeLinInterpol}} methods. ##' ##' @note -##' This function exposes core feature detection functionality of +##' This function exposes core peak detection functionality of ##' the \emph{matchedFilter} method. While this function can be called directly, ##' users will generally call the corresponding method for the data object ##' instead (e.g. the \code{link{findPeaks.matchedFilter}} method). ##' -##' @inheritParams do_detectFeatures_centWave -##' @inheritParams featureDetection-centWave +##' @inheritParams do_findChromPeaks_centWave +##' @inheritParams findChromPeaks-centWave ##' @inheritParams imputeLinInterpol -##' @inheritParams featureDetection-matchedFilter +##' @inheritParams findChromPeaks-matchedFilter ##' -##' @return A matrix, each row representing an identified feature, with columns: +##' @return A matrix, each row representing an identified chromatographic peak, +##' with columns: ##' \describe{ -##' \item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} -##' \item{rt}{Retention time of the feature's midpoint.} -##' \item{rtmin}{Minimum retention time of the feature.} -##' \item{rtmax}{Maximum retention time of the feature.} -##' \item{into}{Integrated (original) intensity of the feature.} +##' \item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +##' \item{mzmin}{Minimum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} +##' \item{rt}{Retention time of the peak's midpoint.} +##' \item{rtmin}{Minimum retention time of the peak.} +##' \item{rtmax}{Maximum retention time of the peak.} +##' \item{into}{Integrated (original) intensity of the peak.} ##' \item{intf}{Integrated intensity of the filtered peak.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{maxf}{Maximum intensity of the filtered peak.} -##' \item{i}{Rank of feature in merged EIC (\code{<= max}).} -##' \item{sn}{Signal to noise ratio of the feature} +##' \item{i}{Rank of peak in merged EIC (\code{<= max}).} +##' \item{sn}{Signal to noise ratio of the peak} ##' } ##' @references ##' Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and @@ -912,7 +917,7 @@ do_detectFeatures_massifquant <- function(mz, ##' Profiling Using Nonlinear Peak Alignment, Matching, and Identification" ##' \emph{Anal. Chem.} 2006, 78:779-787. ##' @author Colin A Smith, Johannes Rainer -##' @family core feature detection functions +##' @family core peak detection functions ##' @seealso \code{\link{binYonX}} for a binning function, ##' \code{\link{imputeLinInterpol}} for the interpolation of missing values. ##' \code{\link{matchedFilter}} for the standard user interface method. @@ -922,16 +927,16 @@ do_detectFeatures_massifquant <- function(mz, ##' fs <- system.file('cdf/KO/ko15.CDF', package = "faahKO") ##' xr <- xcmsRaw(fs) ##' -##' ## Extracting the data from the xcmsRaw for do_detectFeatures_centWave +##' ## Extracting the data from the xcmsRaw for do_findChromPeaks_centWave ##' mzVals <- xr@env$mz ##' intVals <- xr@env$intensity ##' ## Define the values per spectrum: ##' valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) ##' -##' res <- do_detectFeatures_matchedFilter(mz = mzVals, int = intVals, +##' res <- do_findChromPeaks_matchedFilter(mz = mzVals, int = intVals, ##' scantime = xr@scantime, valsPerSpect = valsPerSpect) ##' head(res) -do_detectFeatures_matchedFilter <- function(mz, +do_findChromPeaks_matchedFilter <- function(mz, int, scantime, valsPerSpect, @@ -1130,7 +1135,7 @@ do_detectFeatures_matchedFilter <- function(mz, } ## ############################################################ -## ## Same as do_detectFeatures_matchedFilter except: +## ## Same as do_findChromPeaks_matchedFilter except: ## ## ## ## o Using the binYtoX and imputeLinInterpol instead of the ## ## profBin* methods. @@ -1708,9 +1713,9 @@ do_detectFeatures_matchedFilter <- function(mz, ## MSW ## ##' @title Core API function for single-spectrum non-chromatography MS data -##' feature detection +##' peak detection ##' -##' @description This function performs feature detection in mass spectrometry +##' @description This function performs peak detection in mass spectrometry ##' direct injection spectrum using a wavelet based algorithm. ##' ##' @details This is a wrapper around the peak picker in Bioconductor's @@ -1719,33 +1724,33 @@ do_detectFeatures_matchedFilter <- function(mz, ##' \code{\link[MassSpecWavelet]{tuneInPeakInfo}} functions. See the ##' \emph{xcmsDirect} vignette for more information. ##' -##' @inheritParams do_detectFeatures_centWave -##' @inheritParams featureDetection-centWave +##' @inheritParams do_findChromPeaks_centWave +##' @inheritParams findChromPeaks-centWave ##' @param ... Additional parameters to be passed to the ##' \code{\link[MassSpecWavelet]{peakDetectionCWT}} function. ##' ##' @return -##' A matrix, each row representing an identified feature, with columns: +##' A matrix, each row representing an identified peak, with columns: ##' \describe{ -##' \item{mz}{m/z value of the feature at the centroid position.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} +##' \item{mz}{m/z value of the peak at the centroid position.} +##' \item{mzmin}{Minimum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} ##' \item{rt}{Always \code{-1}.} ##' \item{rtmin}{Always \code{-1}.} ##' \item{rtmax}{Always \code{-1}.} -##' \item{into}{Integrated (original) intensity of the feature.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{into}{Integrated (original) intensity of the peak.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{intf}{Always \code{NA}.} -##' \item{maxf}{Maximum MSW-filter response of the feature.} +##' \item{maxf}{Maximum MSW-filter response of the peak.} ##' \item{sn}{Signal to noise ratio.} ##' } ##' -##' @family core feature detection functions +##' @family core peak detection functions ##' @seealso ##' \code{\link{MSW}} for the standard user interface ##' method. \code{\link[MassSpecWavelet]{peakDetectionCWT}} from the ##' \code{MassSpecWavelet} package. ##' @author Joachim Kutzera, Steffen Neumann, Johannes Rainer -do_detectFeatures_MSW <- function(mz, int, snthresh = 3, +do_findPeaks_MSW <- function(mz, int, snthresh = 3, verboseColumns = FALSE, ...) { ## Input argument checking. if (missing(int)) @@ -1967,7 +1972,7 @@ do_detectFeatures_MSW <- function(mz, int, snthresh = 3, ## This one might be too cumbersome to do it for plain vectors. It would be ideal ## for MSnExp objects though. ## -## do_detectFeatures_MS1 <- function(mz, int, scantime, valsPerSpect) { +## do_findChromPeaks_MS1 <- function(mz, int, scantime, valsPerSpect) { ## ## Checks: do I have ## } @@ -1977,7 +1982,7 @@ do_detectFeatures_MSW <- function(mz, int, snthresh = 3, ## xcmsPeaks, ppm=25, ## maxcharge=3, maxiso=5, mzIntervalExtension=TRUE) { ## if(nrow(xcmsPeaks) == 0){ -## warning("Warning: There are no features (parameter >xcmsPeaks<) for the prediction of isotope ROIs !\n") +## warning("Warning: There are no peaks (parameter >xcmsPeaks<) for the prediction of isotope ROIs !\n") ## return(list()) ## } ## if(class(xcmsPeaks) != "xcmsPeaks") @@ -2036,7 +2041,7 @@ do_detectFeatures_MSW <- function(mz, int, snthresh = 3, ## } ## Tuned from the original code. -##' @param features. \code{matrix} or \code{data.frame} with features for which +##' @param peaks. \code{matrix} or \code{data.frame} with peaks for which ##' isotopes should be predicted. Required columns are \code{"mz"}, ##' \code{"mzmin"}, \code{"mzmax"}, \code{"scmin"}, \code{"scmax"}, ##' \code{"intb"} and \code{"scale"}. @@ -2045,18 +2050,18 @@ do_detectFeatures_MSW <- function(mz, int, snthresh = 3, ##' \code{"mzmax"}, \code{"scmin"}, \code{"scmax"}, \code{"length"} (always -1), ##' \code{"intensity"} (always -1) and \code{"scale"}. ##' @noRd -do_define_isotopes <- function(features., maxCharge = 3, maxIso = 5, +do_define_isotopes <- function(peaks., maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE) { req_cols <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "scale") - if (is.null(dim(features.))) - stop("'features.' has to be a matrix or data.frame!") - if (!all(req_cols %in% colnames(features.))) { - not_there <- req_cols[!(req_cols %in% colnames(features.))] - stop("'features.' lacks required columns ", + if (is.null(dim(peaks.))) + stop("'peaks.' has to be a matrix or data.frame!") + if (!all(req_cols %in% colnames(peaks.))) { + not_there <- req_cols[!(req_cols %in% colnames(peaks.))] + stop("'peaks.' lacks required columns ", paste0("'", not_there, "'", collapse = ","), "!") } - if (is.data.frame(features.)) - features. <- as.matrix(features.) + if (is.data.frame(peaks.)) + peaks. <- as.matrix(peaks.) isotopeDistance <- 1.0033548378 charges <- 1:maxCharge @@ -2064,8 +2069,8 @@ do_define_isotopes <- function(features., maxCharge = 3, maxIso = 5, isotopePopulationMz <- unique(as.numeric(matrix(isos, ncol = 1) %*% (isotopeDistance / charges))) - ## split the features into a list. - roiL <- split(features.[, req_cols, drop = FALSE], f = 1:nrow(features.)) + ## split the peaks into a list. + roiL <- split(peaks.[, req_cols, drop = FALSE], f = 1:nrow(peaks.)) newRois <- lapply(roiL, function(z) { if (mzIntervalExtension) @@ -2085,22 +2090,22 @@ do_define_isotopes <- function(features., maxCharge = 3, maxIso = 5, return(do.call(rbind, newRois)) } -##' param @features. see do_define_isotopes +##' param @peaks. see do_define_isotopes ##' @param polarity character(1) defining the polarity, either \code{"positive"} ##' or \code{"negative"}. ##' @return see do_define_isotopes. ##' @noRd -do_define_adducts <- function(features., polarity = "positive") { +do_define_adducts <- function(peaks., polarity = "positive") { req_cols <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "scale") - if (is.null(dim(features.))) - stop("'features' has to be a matrix or data.frame!") - if (!all(req_cols %in% colnames(features.))) { - not_there <- req_cols[!(req_cols %in% colnames(features.))] - stop("'features' lacks required columns ", + if (is.null(dim(peaks.))) + stop("'peaks.' has to be a matrix or data.frame!") + if (!all(req_cols %in% colnames(peaks.))) { + not_there <- req_cols[!(req_cols %in% colnames(peaks.))] + stop("'peaks.' lacks required columns ", paste0("'", not_there, "'", collapse = ","), "!") } - if (is.data.frame(features.)) - features. <- as.matrix(features.) + if (is.data.frame(peaks.)) + peaks. <- as.matrix(peaks.) ## considered adduct distances ## reference: Huang N.; Siegel M.M.1; Kruppa G.H.; Laukien F.H.; J Am Soc ## Mass Spectrom 1999, 10, 1166–1173; Automation of a Fourier transform ion @@ -2239,7 +2244,7 @@ do_define_adducts <- function(features., polarity = "positive") { ) req_cols <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "scale") - roiL <- split(features.[, req_cols, drop = FALSE], f = 1:nrow(features.)) + roiL <- split(peaks.[, req_cols, drop = FALSE], f = 1:nrow(peaks.)) newRois <- lapply(roiL, function(z) { mzDiff <- unlist(lapply(adductPopulationMz, function(x) { @@ -2299,44 +2304,44 @@ do_findKalmanROI <- function(mz, int, scantime, valsPerSpect, } ############################################################ -## do_detectFeatyres_centWaveWithPredIsoROIs +## do_findChromPeaks_centWaveWithPredIsoROIs ## 1) Run a centWave. -## 2) Predict isotope ROIs for the identified features. +## 2) Predict isotope ROIs for the identified peaks. ## 3) centWave on the predicted isotope ROIs. -## 4) combine both lists of identified features removing overlapping ones by -## keeping the feature with the largest signal intensity. -##' @title Core API function for two-step centWave feature detection with feature isotopes +## 4) combine both lists of identified peaks removing overlapping ones by +## keeping the peak with the largest signal intensity. +##' @title Core API function for two-step centWave peak detection with isotopes ##' -##' @description The \code{do_detectFeatures_centWaveWithPredIsoROIs} performs a -##' two-step centWave based feature detection: features are identified using -##' centWave followed by a prediction of the location of the identified features' -##' isotopes in the mz-retention time space. These locations are fed as +##' @description The \code{do_findChromPeaks_centWaveWithPredIsoROIs} performs a +##' two-step centWave based peak detection: chromatographic peaks are identified +##' using centWave followed by a prediction of the location of the identified +##' peaks' isotopes in the mz-retention time space. These locations are fed as ##' \emph{regions of interest} (ROIs) to a subsequent centWave run. All non -##' overlapping features from these two feature detection runs are reported as -##' the final list of identified features. +##' overlapping peaks from these two peak detection runs are reported as +##' the final list of identified peaks. ##' ##' @details For more details on the centWave algorithm see ##' \code{\link{centWave}}. ##' -##' @inheritParams featureDetection-centWave -##' @inheritParams featureDetection-centWaveWithPredIsoROIs -##' @inheritParams do_detectFeatures_centWave +##' @inheritParams findChromPeaks-centWave +##' @inheritParams findChromPeaks-centWaveWithPredIsoROIs +##' @inheritParams do_findChromPeaks_centWave ##' -##' @family core feature detection functions +##' @family core peak detection functions ##' @return -##' A matrix, each row representing an identified feature. All non-overlapping -##' features identified in both centWave runs are reported. +##' A matrix, each row representing an identified chromatographic peak. All +##' non-overlapping peaks identified in both centWave runs are reported. ##' The matrix columns are: ##' \describe{ -##' \item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} -##' \item{rt}{Retention time of the feature's midpoint.} -##' \item{rtmin}{Minimum retention time of the feature.} -##' \item{rtmax}{Maximum retention time of the feature.} -##' \item{into}{Integrated (original) intensity of the feature.} -##' \item{intb}{Per-feature baseline corrected integrated feature intensity.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{mz}{Intensity weighted mean of m/z values of the peaks across scans.} +##' \item{mzmin}{Minimum m/z of the peaks.} +##' \item{mzmax}{Maximum m/z of the peaks.} +##' \item{rt}{Retention time of the peak's midpoint.} +##' \item{rtmin}{Minimum retention time of the peak.} +##' \item{rtmax}{Maximum retention time of the peak.} +##' \item{into}{Integrated (original) intensity of the peak.} +##' \item{intb}{Per-peak baseline corrected integrated peak intensity.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{sn}{Signal to noise ratio, defined as \code{(maxo - baseline)/sd}, ##' \code{sd} being the standard deviation of local chromatographic noise.} ##' \item{egauss}{RMSE of Gaussian fit.} @@ -2348,14 +2353,14 @@ do_findKalmanROI <- function(mz, int, scantime, valsPerSpect, ##' \item{h}{Gaussian parameter h.} ##' \item{f}{Region number of the m/z ROI where the peak was localized.} ##' \item{dppm}{m/z deviation of mass trace across scanns in ppk.} -##' \item{scale}{Scale on which the feature was localized.} +##' \item{scale}{Scale on which the peak was localized.} ##' \item{scpos}{Peak position found by wavelet analysis (scan number).} ##' \item{scmin}{Left peak limit found by wavelet analysis (scan number).} ##' \item{scmax}{Right peak limit found by wavelet analysis (scan numer).} ##' } -##' @rdname do_detectFeatures_centWaveWithPredIsoROIs +##' @rdname do_findChromPeaks_centWaveWithPredIsoROIs ##' @author Hendrik Treutler, Johannes Rainer -do_detectFeatures_centWaveWithPredIsoROIs <- +do_findChromPeaks_centWaveWithPredIsoROIs <- function(mz, int, scantime, valsPerSpect, ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, fitgauss = FALSE, noise = 0, @@ -2364,11 +2369,11 @@ do_detectFeatures_centWaveWithPredIsoROIs <- maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, polarity = "unknown") { ## Input argument checking: most of it will be done in - ## do_detectFeatures_centWave + ## do_findChromPeaks_centWave polarity <- match.arg(polarity, c("positive", "negative", "unknown")) ## 1) First centWave - feats_1 <- do_detectFeatures_centWave(mz = mz, int = int, + feats_1 <- do_findChromPeaks_centWave(mz = mz, int = int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, @@ -2383,7 +2388,7 @@ do_detectFeatures_centWaveWithPredIsoROIs <- roiList = roiList, firstBaselineCheck = firstBaselineCheck, roiScales = roiScales) - return(do_detectFeatures_addPredIsoROIs(mz = mz, int = int, + return(do_findChromPeaks_addPredIsoROIs(mz = mz, int = int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, @@ -2396,63 +2401,63 @@ do_detectFeatures_centWaveWithPredIsoROIs <- fitgauss = fitgauss, noise = noise, verboseColumns = verboseColumns, - features. = feats_1, + peaks. = feats_1, maxCharge = maxCharge, maxIso = maxIso, mzIntervalExtension = mzIntervalExtension, polarity = polarity)) } -##' @description The \code{do_detectFeatures_centWaveAddPredIsoROIs} performs -##' centWave based feature detection based in regions of interest (ROIs) -##' representing predicted isotopes for the features submitted with argument -##' \code{features.}. The function returns a matrix with the identified features -##' consisting of all input features and features representing predicted isotopes +##' @description The \code{do_findChromPeaks_centWaveAddPredIsoROIs} performs +##' centWave based peak detection based in regions of interest (ROIs) +##' representing predicted isotopes for the peaks submitted with argument +##' \code{peaks.}. The function returns a matrix with the identified peaks +##' consisting of all input peaks and peaks representing predicted isotopes ##' of these (if found by the centWave algorithm). ##' -##' @param features. A matrix or \code{xcmsPeaks} object such as one returned by -##' a call to \code{link{do_detectFeatures_centWave}} or +##' @param peaks. A matrix or \code{xcmsPeaks} object such as one returned by +##' a call to \code{link{do_findChromPeaks_centWave}} or ##' \code{link{findPeaks.centWave}} (both with \code{verboseColumns = TRUE}) -##' with the features for which isotopes should be predicted and used for an -##' additional feature detectoin using the centWave method. Required columns are: +##' with the peaks for which isotopes should be predicted and used for an +##' additional peak detectoin using the centWave method. Required columns are: ##' \code{"mz"}, \code{"mzmin"}, \code{"mzmax"}, \code{"scmin"}, \code{"scmax"}, ##' \code{"scale"} and \code{"into"}. ##' -##' @param snthresh For \code{do_detectFeatures_addPredIsoROIs}: +##' @param snthresh For \code{do_findChromPeaks_addPredIsoROIs}: ##' numeric(1) defining the signal to noise threshold for the centWave algorithm. -##' For \code{do_detectFeatures_centWaveWithPredIsoROIs}: numeric(1) defining the +##' For \code{do_findChromPeaks_centWaveWithPredIsoROIs}: numeric(1) defining the ##' signal to noise threshold for the initial (first) centWave run. ##' -##' @inheritParams featureDetection-centWave -##' @inheritParams do_detectFeatures_centWave +##' @inheritParams findChromPeaks-centWave +##' @inheritParams do_findChromPeaks_centWave ##' -##' @rdname do_detectFeatures_centWaveWithPredIsoROIs -do_detectFeatures_addPredIsoROIs <- +##' @rdname do_findChromPeaks_centWaveWithPredIsoROIs +do_findChromPeaks_addPredIsoROIs <- function(mz, int, scantime, valsPerSpect, ppm = 25, peakwidth = c(20, 50), snthresh = 6.25, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, fitgauss = FALSE, noise = 0, - verboseColumns = FALSE, features. = NULL, + verboseColumns = FALSE, peaks. = NULL, maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, polarity = "unknown") { ## Input argument checking: most of it will be done in - ## do_detectFeatures_centWave + ## do_findChromPeaks_centWave polarity <- match.arg(polarity, c("positive", "negative", "unknown")) ## These variables might at some point be added as function args. addNewIsotopeROIs <- TRUE addNewAdductROIs <- FALSE ## 2) predict isotope and/or adduct ROIs - f_mod <- features. + f_mod <- peaks. ## Extend the mzmin and mzmax if needed. - tittle <- features.[, "mz"] * (ppm / 2) / 1E6 - expand_mz <- (features.[, "mzmax"] - features.[, "mzmin"]) < (tittle * 2) + tittle <- peaks.[, "mz"] * (ppm / 2) / 1E6 + expand_mz <- (peaks.[, "mzmax"] - peaks.[, "mzmin"]) < (tittle * 2) if (any(expand_mz)) { - f_mod[expand_mz, "mzmin"] <- features.[expand_mz, "mz"] - + f_mod[expand_mz, "mzmin"] <- peaks.[expand_mz, "mz"] - tittle[expand_mz] - f_mod[expand_mz, "mzmax"] <- features.[expand_mz, "mz"] + tittle[expand_mz] + f_mod[expand_mz, "mzmax"] <- peaks.[expand_mz, "mz"] + tittle[expand_mz] } ## Add predicted ROIs if (addNewIsotopeROIs) { - iso_ROIs <- do_define_isotopes(features. = f_mod, + iso_ROIs <- do_define_isotopes(peaks. = f_mod, maxCharge = maxCharge, maxIso = maxIso, mzIntervalExtension = mzIntervalExtension) @@ -2462,7 +2467,7 @@ do_detectFeatures_addPredIsoROIs <- "length", "intensity", "scale") } if (addNewAdductROIs) { - add_ROIs <- do_define_adducts(features. = f_mod, polarity = polarity) + add_ROIs <- do_define_adducts(peaks. = f_mod, polarity = polarity) } else { add_ROIs <- matrix(nrow = 0, ncol = 8) colnames(iso_ROIs) <- c("mz", "mzmin", "mzmax", "scmin", "scmax", @@ -2471,7 +2476,7 @@ do_detectFeatures_addPredIsoROIs <- newROIs <- rbind(iso_ROIs, add_ROIs) rm(f_mod) if (nrow(newROIs) == 0) - return(features.) + return(peaks.) ## Remove ROIs that are out of mz range: mz_range <- range(mz) newROIs <- newROIs[newROIs[, "mzmin"] >= mz_range[1] & @@ -2489,14 +2494,14 @@ do_detectFeatures_addPredIsoROIs <- newROIs <- newROIs[keep_me, , drop = FALSE] if (nrow(newROIs) == 0) { - warning("No isotope or adduct ROIs for the identified features with a ", + warning("No isotope or adduct ROIs for the identified peaks with a ", "valid signal found!") - return(features.) + return(peaks.) } ## 3) centWave using the identified ROIs. roiL <- split(as.data.frame(newROIs), f = 1:nrow(newROIs)) - feats_2 <- do_detectFeatures_centWave(mz = mz, int = int, + feats_2 <- do_findChromPeaks_centWave(mz = mz, int = int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, @@ -2529,30 +2534,30 @@ do_detectFeatures_addPredIsoROIs <- ## Comparing each ROI with each peak; slightly modified from the original ## code in which we prevent calling apply followed by two lapply. removeROIs <- rep(FALSE, nrow(feats_2)) - removeFeats <- rep(FALSE, nrow(features.)) + removeFeats <- rep(FALSE, nrow(peaks.)) overlapProportionThreshold <- 0.01 for (i in 1:nrow(feats_2)) { - ## Compare ROI i with all features (peaks) and check if its + ## Compare ROI i with all peaks (peaks) and check if its ## overlapping ## mz roiMzCenter <- (feats_2[i, "mzmin"] + feats_2[i, "mzmax"]) / 2 - peakMzCenter <- (features.[, "mzmin"] + features.[, "mzmax"]) / 2 + peakMzCenter <- (peaks.[, "mzmin"] + peaks.[, "mzmax"]) / 2 roiMzRadius <- (feats_2[i, "mzmax"] - feats_2[i, "mzmin"]) / 2 - peakMzRadius <- (features.[, "mzmax"] - features.[, "mzmin"]) / 2 + peakMzRadius <- (peaks.[, "mzmax"] - peaks.[, "mzmin"]) / 2 overlappingMz <- abs(peakMzCenter - roiMzCenter) <= (roiMzRadius + peakMzRadius) ## rt roiRtCenter <- (feats_2[i, "rtmin"] + feats_2[i, "rtmax"]) / 2 - peakRtCenter <- (features.[, "rtmin"] + features.[, "rtmax"]) / 2 + peakRtCenter <- (peaks.[, "rtmin"] + peaks.[, "rtmax"]) / 2 roiRtRadius <- (feats_2[i, "rtmax"] - feats_2[i, "rtmin"]) / 2 - peakRtRadius <- (features.[, "rtmax"] - features.[, "rtmin"]) / 2 + peakRtRadius <- (peaks.[, "rtmax"] - peaks.[, "rtmin"]) / 2 overlappingRt <- abs(peakRtCenter - roiRtCenter) <= (roiRtRadius + peakRtRadius) is_overlapping <- overlappingMz & overlappingRt ## Now determine whether we remove the ROI or the peak, depending ## on the raw signal intensity. if (any(is_overlapping)) { - if (any(features.[is_overlapping, "into"] > feats_2[i, "into"])) { + if (any(peaks.[is_overlapping, "into"] > feats_2[i, "into"])) { removeROIs[i] <- TRUE } else { removeFeats[is_overlapping] <- TRUE @@ -2560,13 +2565,13 @@ do_detectFeatures_addPredIsoROIs <- } } feats_2 <- feats_2[!removeROIs, , drop = FALSE] - features. <- features.[!removeFeats, , drop = FALSE] + peaks. <- peaks.[!removeFeats, , drop = FALSE] } if (!verboseColumns) - features. <- features.[ , c("mz", "mzmin", "mzmax", "rt", "rtmin", - "rtmax", "into", "intb", "maxo", "sn")] + peaks. <- peaks.[ , c("mz", "mzmin", "mzmax", "rt", "rtmin", + "rtmax", "into", "intb", "maxo", "sn")] if (nrow(feats_2) == 0) - return(features.) + return(peaks.) else - return(rbind(features., feats_2)) + return(rbind(peaks., feats_2)) } diff --git a/R/do_groupFeatures-functions.R b/R/do_groupChromPeaks-functions.R similarity index 63% rename from R/do_groupFeatures-functions.R rename to R/do_groupChromPeaks-functions.R index d62dd6a4b..e8b00d66a 100644 --- a/R/do_groupFeatures-functions.R +++ b/R/do_groupChromPeaks-functions.R @@ -1,49 +1,49 @@ -## Alignment functions. +## Correspondence functions. #' @include functions-Params.R -##' @title Core API function for feature density based feature alignment +##' @title Core API function for peak density based chromatographic peak +##' grouping ##' -##' @description The \code{do_groupFeatures_density} function performs feature -##' alignment based on the density (distribution) of features, found in different -##' samples, along the retention time axis in slices of overlapping mz ranges. +##' @description The \code{do_groupChromPeaks_density} function performs +##' chromatographic peak grouping based on the density (distribution) of peaks, +##' found in different samples, along the retention time axis in slices of +##' overlapping mz ranges. ##' ##' @details For overlapping slices along the mz dimension, the function -##' calculates the density distribution of identified features along the -##' retention time axis and groups features from the same or different samples +##' calculates the density distribution of identified peaks along the +##' retention time axis and groups peaks from the same or different samples ##' that are close to each other. See [Smith 2006] for more details. ##' ##' @note The default settings might not be appropriate for all LC/GC-MS setups, ##' especially the \code{bw} and \code{binSize} parameter should be adjusted ##' accordingly. ##' -##' @param features A \code{matrix} or \code{data.frame} with the mz values and -##' retention times of the identified features in all samples of an experiment. -##' Required columns are \code{"mz"}, \code{"rt"} and \code{"sample"}. The latter -##' should contain \code{numeric} values representing the index of the sample in -##' which the feature was found. +##' @param peaks A \code{matrix} or \code{data.frame} with the mz values and +##' retention times of the identified chromatographic peaks in all samples of an +##' experiment. Required columns are \code{"mz"}, \code{"rt"} and +##' \code{"sample"}. The latter should contain \code{numeric} values representing +##' the index of the sample in which the peak was found. ##' -##' @inheritParams groupFeatures-density +##' @inheritParams groupChromPeaks-density ##' -##' @return A \code{list} with elements \code{"featureGroups"} and -##' \code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -##' representing an aligned feature group and with columns: +##' @return A \code{list} with elements \code{"featureDefinitions"} and +##' \code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +##' representing a (mz-rt) feature (i.e. a peak group) with columns: ##' \describe{ -##' \item{"mzmed"}{median of the features' apex mz values.} -##' \item{"mzmin"}{smallest mz value of all features' apex within the feature -##' group.} -##' \item{"mzmax"}{largest mz value of all features' apex within the feature -##' group.} -##' \item{"rtmed"}{the median of the features' retention times.} -##' \item{"rtmin"}{the smallest retention time of the features in the group.} -##' \item{"rtmax"}{the largest retention time of the features in the group.} -##' \item{"npeaks"}{the total number of features assigned to the feature group. +##' \item{"mzmed"}{median of the peaks' apex mz values.} +##' \item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +##' \item{"mzmax"}{largest mz value of all peaks' apex within the feature.} +##' \item{"rtmed"}{the median of the peaks' retention times.} +##' \item{"rtmin"}{the smallest retention time of the peaks in the group.} +##' \item{"rtmax"}{the largest retention time of the peaks in the group.} +##' \item{"npeaks"}{the total number of peaks assigned to the feature. ##' Note that this number can be larger than the total number of samples, since -##' multiple features from the same sample could be assigned to a group.} +##' multiple peaks from the same sample could be assigned to a feature.} ##' } -##' \code{"featureIndex"} is a \code{list} with the indices of all features in a -##' feature group in the \code{features} input matrix. +##' \code{"peakIndex"} is a \code{list} with the indices of all peaks in a +##' feature in the \code{peaks} input matrix. ##' -##' @family core feature alignment algorithms +##' @family core peak grouping algorithms ##' ##' @references ##' Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and @@ -58,34 +58,34 @@ ##' library(faahKO) ##' data(faahko) ##' -##' ## Extract the matrix with the identified features from the xcmsSet: +##' ## Extract the matrix with the identified peaks from the xcmsSet: ##' fts <- peaks(faahko) ##' -##' ## Perform the feature alignment with default settings: -##' res <- do_groupFeatures_density(fts, sampleGroups = sampclass(faahko)) +##' ## Perform the peak grouping with default settings: +##' res <- do_groupChromPeaks_density(fts, sampleGroups = sampclass(faahko)) ##' -##' ## The feature groups: -##' head(res$featureGroups) +##' ## The feature definitions: +##' head(res$featureDefinitions) ##' -##' ## The assignment of features from the input matrix to the feature groups -##' head(res$featureIndex) -do_groupFeatures_density <- function(features, sampleGroups, - bw = 30, minFraction = 0.5, minSamples = 1, - binSize = 0.25, maxFeatures = 50) { +##' ## The assignment of peaks from the input matrix to the features +##' head(res$peakIndex) +do_groupChromPeaks_density <- function(peaks, sampleGroups, + bw = 30, minFraction = 0.5, minSamples = 1, + binSize = 0.25, maxFeatures = 50) { if (missing(sampleGroups)) stop("Parameter 'sampleGroups' is missing! This should be a vector of ", "length equal to the number of samples specifying the group ", "assignment of the samples.") - if (missing(features)) + if (missing(peaks)) stop("Parameter 'peaks' is missing!") - if (!is.matrix(features) | is.data.frame(features)) - stop("Peaks has to be a 'matrix' or a 'data.frame'!") + if (!is.matrix(peaks) | is.data.frame(peaks)) + stop("'peaks' has to be a 'matrix' or a 'data.frame'!") ## Check that we've got all required columns .reqCols <- c("mz", "rt", "sample") - if (!all(.reqCols %in% colnames(features))) + if (!all(.reqCols %in% colnames(peaks))) stop("Required columns ", - paste0("'", .reqCols[!.reqCols %in% colnames(features)],"'", - collapse = ", "), " not found in 'features' parameter") + paste0("'", .reqCols[!.reqCols %in% colnames(peaks)],"'", + collapse = ", "), " not found in 'peaks' parameter") sampleGroups <- as.character(sampleGroups) sampleGroupNames <- unique(sampleGroups) @@ -93,21 +93,21 @@ do_groupFeatures_density <- function(features, sampleGroups, nSampleGroups <- length(sampleGroupTable) ## Check that sample groups matches with sample column. - if (max(features[, "sample"]) > length(sampleGroups)) - stop("Sample indices in 'features' are larger than there are sample", + if (max(peaks[, "sample"]) > length(sampleGroups)) + stop("Sample indices in 'peaks' are larger than there are sample", " groups specified with 'sampleGroups'!") - ## Order features matrix by mz - featureOrder <- order(features[, "mz"]) - features <- features[featureOrder, .reqCols, drop = FALSE] - rownames(features) <- NULL - rtRange <- range(features[, "rt"]) + ## Order peaks matrix by mz + peakOrder <- order(peaks[, "mz"]) + peaks <- peaks[peakOrder, .reqCols, drop = FALSE] + rownames(peaks) <- NULL + rtRange <- range(peaks[, "rt"]) - ## Define the mass slices and the index in the features matrix with an mz + ## Define the mass slices and the index in the peaks matrix with an mz ## value >= mass[i]. - mass <- seq(features[1, "mz"], features[nrow(features), "mz"] + binSize, + mass <- seq(peaks[1, "mz"], peaks[nrow(peaks), "mz"] + binSize, by = binSize / 2) - masspos <- findEqualGreaterM(features[,"mz"], mass) + masspos <- findEqualGreaterM(peaks[,"mz"], mass) groupmat <- matrix(nrow = 512, ncol = 7 + nSampleGroups) groupindex <- vector("list", 512) @@ -123,7 +123,7 @@ do_groupFeatures_density <- function(features, sampleGroups, endIdx <- masspos[i + 2] - 1 if (endIdx - startIdx < 0) next - curMat <- features[startIdx:endIdx, , drop = FALSE] + curMat <- peaks[startIdx:endIdx, , drop = FALSE] den <- density(curMat[, "rt"], bw = bw, from = densFrom, to = densTo) maxden <- max(den$y) deny <- den$y @@ -135,7 +135,7 @@ do_groupFeatures_density <- function(features, sampleGroups, deny[grange[1]:grange[2]] <- 0 gidx <- which(curMat[,"rt"] >= den$x[grange[1]] & curMat[,"rt"] <= den$x[grange[2]]) - ## Determine the sample group of the samples in which the features + ## Determine the sample group of the samples in which the peaks ## were detected and check if they correspond to the required limits. tt <- table(sampleGroups[unique(curMat[gidx, "sample"])]) if (!any(tt / sampleGroupTable[names(tt)] >= minFraction & @@ -159,7 +159,7 @@ do_groupFeatures_density <- function(features, sampleGroups, groupmat[num, 5:6] <- range(curMat[gidx, "rt"]) groupmat[num, 7] <- length(gidx) groupmat[num, 7 + seq(along = gcount)] <- gcount - groupindex[[num]] <- sort(featureOrder[(startIdx:endIdx)[gidx]]) + groupindex[[num]] <- sort(peakOrder[(startIdx:endIdx)[gidx]]) } } @@ -179,13 +179,13 @@ do_groupFeatures_density <- function(features, sampleGroups, drop = FALSE], uorder) - return(list(featureGroups = groupmat[uindex, , drop = FALSE], - featureIndex = groupindex[uindex])) + return(list(featureDefinitions = groupmat[uindex, , drop = FALSE], + peakIndex = groupindex[uindex])) } ## Just to check if we could squeeze a little bit more out using parallel ## processing... -do_groupFeatures_density_par <- function(features, sampleGroups, +do_groupChromPeaks_density_par <- function(peaks, sampleGroups, bw = 30, minFraction = 0.5, minSamples = 1, binSize = 0.25, maxFeatures = 50) { @@ -193,50 +193,50 @@ do_groupFeatures_density_par <- function(features, sampleGroups, stop("Parameter 'sampleGroups' is missing! This should be a vector of ", "length equal to the number of samples specifying the group ", "assignment of the samples.") - if (missing(features)) + if (missing(peaks)) stop("Parameter 'peaks' is missing!") - if (!is.matrix(features) | is.data.frame(features)) + if (!is.matrix(peaks) | is.data.frame(peaks)) stop("Peaks has to be a 'matrix' or a 'data.frame'!") ## Check that we've got all required columns .reqCols <- c("mz", "rt", "sample") - if (!all(.reqCols %in% colnames(features))) + if (!all(.reqCols %in% colnames(peaks))) stop("Required columns ", - paste0("'", .reqCols[!.reqCols %in% colnames(features)],"'", - collapse = ", "), " not found in 'features' parameter") + paste0("'", .reqCols[!.reqCols %in% colnames(peaks)],"'", + collapse = ", "), " not found in 'peaks' parameter") sampleGroups <- as.character(sampleGroups) sampleGroupNames <- unique(sampleGroups) sampleGroupTable <- table(sampleGroups) nSampleGroups <- length(sampleGroupTable) - ## Order features matrix by mz - featureOrder <- order(features[, "mz"]) - features <- features[featureOrder, .reqCols, drop = FALSE] - rownames(features) <- NULL - rtRange <- range(features[, "rt"]) + ## Order peaks matrix by mz + peakOrder <- order(peaks[, "mz"]) + peaks <- peaks[peakOrder, .reqCols, drop = FALSE] + rownames(peaks) <- NULL + rtRange <- range(peaks[, "rt"]) - ## Define the mass slices and the index in the features matrix with an mz + ## Define the mass slices and the index in the peaks matrix with an mz ## value >= mass[i]. - mass <- seq(features[1, "mz"], features[nrow(features), "mz"] + binSize, + mass <- seq(peaks[1, "mz"], peaks[nrow(peaks), "mz"] + binSize, by = binSize / 2) - masspos <- findEqualGreaterM(features[,"mz"], mass) + masspos <- findEqualGreaterM(peaks[,"mz"], mass) groupmat <- matrix(nrow = 512, ncol = 7 + nSampleGroups) groupindex <- vector("list", 512) - ## Create the list of feature data subsets. + ## Create the list of peak data subsets. ftsL <- vector("list", length(mass)) for (i in seq_len(length(mass) - 2)) { startIdx <- masspos[i] endIdx <- masspos[i + 2] - 1 - ftsL[[i]] <- cbind(features[startIdx:endIdx, , drop = FALSE], + ftsL[[i]] <- cbind(peaks[startIdx:endIdx, , drop = FALSE], idx = startIdx:endIdx) } ftsL <- ftsL[lengths(ftsL) > 0] ## Here we can run bplapply: res <- bplapply(ftsL, function(z, rtr, bw, maxF, sampleGrps, sampleGroupTbl, minFr, minSmpls, - sampleGroupNms, featureOrdr) { + sampleGroupNms, peakOrdr) { den <- density(z[, "rt"], bw = bw, from = rtr[1] - 3 * bw, to = rtr[2] + 3 * bw) maxden <- max(den$y) @@ -249,7 +249,7 @@ do_groupFeatures_density_par <- function(features, sampleGroups, deny[grange[1]:grange[2]] <- 0 gidx <- which(z[,"rt"] >= den$x[grange[1]] & z[,"rt"] <= den$x[grange[2]]) - ## Determine the sample group of the samples in which the features + ## Determine the sample group of the samples in which the peaks ## were detected and check if they correspond to the required limits. tt <- table(sampleGrps[unique(z[gidx, "sample"])]) if (!any(tt / sampleGroupTbl[names(tt)] >= minFr & @@ -266,7 +266,7 @@ do_groupFeatures_density_par <- function(features, sampleGroups, range(z[gidx, "rt"]), length(gidx), gcount) - tmpL2[[snum]] <- sort(featureOrdr[z[, "idx"][gidx]]) + tmpL2[[snum]] <- sort(peakOrdr[z[, "idx"][gidx]]) } tmpL <- tmpL[lengths(tmpL) > 0] tmpL2 <- tmpL2[lengths(tmpL2) > 0] @@ -275,7 +275,7 @@ do_groupFeatures_density_par <- function(features, sampleGroups, }, rtr = rtRange, bw = bw, maxF = maxFeatures, sampleGrps = sampleGroups, sampleGroupTbl = sampleGroupTable, minFr = minFraction, minSmpls = minSamples, sampleGroupNms = sampleGroupNames, - featureOrdr = featureOrder) + peakOrdr = peakOrder) res <- res[lengths(res) > 0] ## Now we have to process that list of results. @@ -298,61 +298,59 @@ do_groupFeatures_density_par <- function(features, sampleGroups, drop = FALSE], uorder) - return(list(featureGroups = groupmat[uindex, , drop = FALSE], - featureIndex = groupidx[uindex])) + return(list(featureDefinitions = groupmat[uindex, , drop = FALSE], + peakIndex = groupidx[uindex])) } -##' @title Core API function for feature alignment using mzClust +##' @title Core API function for peak grouping using mzClust ##' -##' @description The \code{do_groupFeatures_mzClust} function performs high -##' resolution alignment on single spectra samples. +##' @description The \code{do_groupPeaks_mzClust} function performs high +##' resolution correspondence on single spectra samples. ##' -##' @inheritParams groupFeatures-density -##' @inheritParams do_groupFeatures_density -##' @inheritParams groupFeatures-mzClust +##' @inheritParams groupChromPeaks-density +##' @inheritParams do_groupChromPeaks_density +##' @inheritParams groupChromPeaks-mzClust ##' -##' @return A \code{list} with elements \code{"featureGroups"} and -##' \code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -##' representing an aligned feature group and with columns: +##' @return A \code{list} with elements \code{"featureDefinitions"} and +##' \code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +##' representing an (mz-rt) feature (i.e. peak group) with columns: ##' \describe{ -##' \item{"mzmed"}{median of the features' apex mz values.} -##' \item{"mzmin"}{smallest mz value of all features' apex within the feature -##' group.} -##' \item{"mzmax"}{largest mz value of all features' apex within the feature -##' group.} +##' \item{"mzmed"}{median of the peaks' apex mz values.} +##' \item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +##' \item{"mzmax"}{largest mz value of all peaks' apex within the feature.} ##' \item{"rtmed"}{always \code{-1}.} ##' \item{"rtmin"}{always \code{-1}.} ##' \item{"rtmax"}{always \code{-1}.} -##' \item{"npeaks"}{the total number of features assigned to the feature group. +##' \item{"npeaks"}{the total number of peaks assigned to the feature. ##' Note that this number can be larger than the total number of samples, since -##' multiple features from the same sample could be assigned to a group.} +##' multiple peaks from the same sample could be assigned to a group.} ##' } -##' \code{"featureIndex"} is a \code{list} with the indices of all features in a -##' feature group in the \code{features} input matrix. +##' \code{"peakIndex"} is a \code{list} with the indices of all peaks in a +##' peak group in the \code{peaks} input matrix. ##' -##' @family core feature alignment algorithms +##' @family core peak grouping algorithms ##' ##' @references Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill ##' and David F. Grant\cr \emph{Alignment of high resolution mass spectra: ##' development of a heuristic approach for metabolomics}.\cr Metabolomics, ##' Vol. 2, No. 2, 75-83 (2006) -do_groupFeatures_mzClust <- function(features, sampleGroups, ppm = 20, - absMz = 0, minFraction = 0.5, - minSamples = 1) { +do_groupPeaks_mzClust <- function(peaks, sampleGroups, ppm = 20, + absMz = 0, minFraction = 0.5, + minSamples = 1) { if (missing(sampleGroups)) stop("Parameter 'sampleGroups' is missing! This should be a vector of ", "length equal to the number of samples specifying the group ", "assignment of the samples.") - if (missing(features)) + if (missing(peaks)) stop("Parameter 'peaks' is missing!") - if (!is.matrix(features) | is.data.frame(features)) + if (!is.matrix(peaks) | is.data.frame(peaks)) stop("Peaks has to be a 'matrix' or a 'data.frame'!") ## Check that we've got all required columns .reqCols <- c("mz", "sample") - if (!all(.reqCols %in% colnames(features))) + if (!all(.reqCols %in% colnames(peaks))) stop("Required columns ", - paste0("'", .reqCols[!.reqCols %in% colnames(features)],"'", - collapse = ", "), " not found in 'features' parameter") + paste0("'", .reqCols[!.reqCols %in% colnames(peaks)],"'", + collapse = ", "), " not found in 'peaks' parameter") if (!is.factor(sampleGroups)) sampleGroups <- factor(sampleGroups, levels = unique(sampleGroups)) sampleGroupNames <- levels(sampleGroups) @@ -361,12 +359,12 @@ do_groupFeatures_mzClust <- function(features, sampleGroups, ppm = 20, ##sampleGroups <- as.numeric(sampleGroups) ## Check that sample groups matches with sample column. - if (max(features[, "sample"]) > length(sampleGroups)) - stop("Sample indices in 'features' are larger than there are sample", + if (max(peaks[, "sample"]) > length(sampleGroups)) + stop("Sample indices in 'peaks' are larger than there are sample", " groups specified with 'sampleGroups'!") - ##features <- features[, .reqCols, drop = FALSE] - grps <- mzClustGeneric(features[, .reqCols, drop = FALSE], + ##peaks <- peaks[, .reqCols, drop = FALSE] + grps <- mzClustGeneric(peaks[, .reqCols, drop = FALSE], sampclass = sampleGroups, mzppm = ppm, mzabs = absMz, @@ -384,57 +382,56 @@ do_groupFeatures_mzClust <- function(features, sampleGroups, ppm = 20, grpmat[, 4:ncol(grpmat), drop = FALSE]) colnames(grpmat) <- c(cns[1:3], c("rtmed", "rtmin", "rtmax"), cns[4:length(cns)]) - return(list(featureGroups = grpmat, featureIndex = grps$idx)) + return(list(featureDefinitions = grpmat, peakIndex = grps$idx)) } -##' @title Core API function for feature alignment using a nearest neighbor approach +##' @title Core API function for chromatic peak grouping using a nearest +##' neighbor approach ##' -##' @description The \code{do_groupFeatures_nearest} function groups features -##' across samples by creating a master feature list and assigning corresponding -##' features from all samples to each feature group. The method is inspired by -##' the alignment algorithm of mzMine [Katajamaa 2006]. +##' @description The \code{do_groupChromPeaks_nearest} function groups peaks +##' across samples by creating a master peak list and assigning corresponding +##' peaks from all samples to each peak group (i.e. feature). The method is +##' inspired by the correspondence algorithm of mzMine [Katajamaa 2006]. ##' -##' @inheritParams do_groupFeatures_density -##' @inheritParams groupFeatures-nearest +##' @inheritParams do_groupChromPeaks_density +##' @inheritParams groupChromPeaks-nearest ##' -##' @return A \code{list} with elements \code{"featureGroups"} and -##' \code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -##' representing an aligned feature group and with columns: +##' @return A \code{list} with elements \code{"featureDefinitions"} and +##' \code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +##' representing an (mz-rt) feature (i.e. peak group) with columns: ##' \describe{ -##' \item{"mzmed"}{median of the features' apex mz values.} -##' \item{"mzmin"}{smallest mz value of all features' apex within the feature -##' group.} -##' \item{"mzmax"}{largest mz value of all features' apex within the feature -##' group.} -##' \item{"rtmed"}{the median of the features' retention times.} -##' \item{"rtmin"}{the smallest retention time of the features in the group.} -##' \item{"rtmax"}{the largest retention time of the features in the group.} -##' \item{"npeaks"}{the total number of features assigned to the feature group.} +##' \item{"mzmed"}{median of the peaks' apex mz values.} +##' \item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +##' \item{"mzmax"}{largest mz value of all peaks' apex within the feature.} +##' \item{"rtmed"}{the median of the peaks' retention times.} +##' \item{"rtmin"}{the smallest retention time of the peaks in the feature.} +##' \item{"rtmax"}{the largest retention time of the peaks in the feature.} +##' \item{"npeaks"}{the total number of peaks assigned to the feature.} ##' } -##' \code{"featureIndex"} is a \code{list} with the indices of all features in a -##' feature group in the \code{features} input matrix. +##' \code{"peakIndex"} is a \code{list} with the indices of all peaks in a +##' feature in the \code{peaks} input matrix. ##' -##' @family core feature alignment algorithms +##' @family core peak grouping algorithms ##' ##' @references Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for ##' processing and visualization of mass spectrometry based molecular profile ##' data. \emph{Bioinformatics} 2006, 22:634-636. -do_groupFeatures_nearest <- function(features, sampleGroups, mzVsRtBalance = 10, - absMz = 0.2, absRt = 15, kNN = 10) { +do_groupChromPeaks_nearest <- function(peaks, sampleGroups, mzVsRtBalance = 10, + absMz = 0.2, absRt = 15, kNN = 10) { if (missing(sampleGroups)) stop("Parameter 'sampleGroups' is missing! This should be a vector of ", "length equal to the number of samples specifying the group ", "assignment of the samples.") - if (missing(features)) + if (missing(peaks)) stop("Parameter 'peaks' is missing!") - if (!is.matrix(features) | is.data.frame(features)) + if (!is.matrix(peaks) | is.data.frame(peaks)) stop("Peaks has to be a 'matrix' or a 'data.frame'!") ## Check that we've got all required columns .reqCols <- c("mz", "rt", "sample") - if (!all(.reqCols %in% colnames(features))) + if (!all(.reqCols %in% colnames(peaks))) stop("Required columns ", - paste0("'", .reqCols[!.reqCols %in% colnames(features)],"'", - collapse = ", "), " not found in 'features' parameter") + paste0("'", .reqCols[!.reqCols %in% colnames(peaks)],"'", + collapse = ", "), " not found in 'peaks' parameter") if (!is.factor(sampleGroups)) sampleGroups <- factor(sampleGroups, levels = unique(sampleGroups)) sampleGroupNames <- levels(sampleGroups) @@ -443,14 +440,14 @@ do_groupFeatures_nearest <- function(features, sampleGroups, mzVsRtBalance = 10, ## sampleGroups == classlabel ## nSampleGroups == gcount - ## features == peakmat + ## peaks == peakmat - features <- features[, .reqCols, drop = FALSE] + peaks <- peaks[, .reqCols, drop = FALSE] parameters <- list(mzVsRTBalance = mzVsRtBalance, mzcheck = absMz, rtcheck = absRt, knn = kNN) - ptable <- table(features[,"sample"]) + ptable <- table(peaks[,"sample"]) pord <- ptable[order(ptable, decreasing = TRUE)] sid <- as.numeric(names(pord)) pn <- as.numeric(pord) @@ -460,11 +457,11 @@ do_groupFeatures_nearest <- function(features, sampleGroups, mzVsRtBalance = 10, ## chunk it needs to process). mplenv <- new.env(parent = .GlobalEnv) mplenv$mplist <- matrix(0, pn[1], length(sid)) - mplenv$mplist[, sid[1]] <- which(features[,"sample"] == sid[1]) - mplenv$mplistmean <- data.frame(features[which(features[,"sample"] == sid[1]), + mplenv$mplist[, sid[1]] <- which(peaks[,"sample"] == sid[1]) + mplenv$mplistmean <- data.frame(peaks[which(peaks[,"sample"] == sid[1]), c("mz", "rt")]) - mplenv$peakmat <- features - assign("peakmat", features, envir = mplenv) ## double assignment? + mplenv$peakmat <- peaks + assign("peakmat", peaks, envir = mplenv) ## double assignment? sapply(sid[2:length(sid)], function(sample, mplenv){ message("Processing sample number ", sample, " ... ", appendLF = FALSE) @@ -473,8 +470,8 @@ do_groupFeatures_nearest <- function(features, sampleGroups, mzVsRtBalance = 10, ## clusterEvalQ(cl, library(RANN)) ## parSapply(cl, 2:length(samples), function(sample,mplenv, object){ ## might slightly improve on this for loop. - ## Calculating for each row (peak) the mean mz or rt for features - ## assigned yet to this feature group. + ## Calculating for each row (peak) the mean mz or rt for peaks + ## assigned yet to this peak group. for (mml in seq(mplenv$mplist[,1])) { mplenv$mplistmean[mml, "mz"] <- mean(mplenv$peakmat[mplenv$mplist[mml, ], "mz"]) @@ -543,30 +540,30 @@ do_groupFeatures_nearest <- function(features, sampleGroups, mzVsRtBalance = 10, colnames(groupmat) <- c("mzmed", "mzmin", "mzmax", "rtmed", "rtmin", "rtmax", "npeaks", sampleGroupNames) groupindex <- vector("list", nrow(mplenv$mplist)) - ## Variable to count samples for a feature + ## Variable to count samples for a peak sampCounts <- rep_len(0, nSampleGroups) names(sampCounts) <- sampleGroupNames ## gcount <- integer(nSampleGroups) ## Can we vectorize that below somehow? for (i in 1:nrow(mplenv$mplist)) { - groupmat[i, "mzmed"] <- median(features[mplenv$mplist[i, ], "mz"]) - groupmat[i, c("mzmin", "mzmax")] <- range(features[mplenv$mplist[i, ], "mz"]) - groupmat[i, "rtmed"] <- median(features[mplenv$mplist[i, ], "rt"]) - groupmat[i, c("rtmin", "rtmax")] <- range(features[mplenv$mplist[i, ], "rt"]) + groupmat[i, "mzmed"] <- median(peaks[mplenv$mplist[i, ], "mz"]) + groupmat[i, c("mzmin", "mzmax")] <- range(peaks[mplenv$mplist[i, ], "mz"]) + groupmat[i, "rtmed"] <- median(peaks[mplenv$mplist[i, ], "rt"]) + groupmat[i, c("rtmin", "rtmax")] <- range(peaks[mplenv$mplist[i, ], "rt"]) - groupmat[i, "npeaks"] <- length(which(features[mplenv$mplist[i, ]] > 0)) + groupmat[i, "npeaks"] <- length(which(peaks[mplenv$mplist[i, ]] > 0)) ## Now summarizing the number of samples in which the peak was identified sampCounts[] <- 0 - tbl <- table(sampleGroups[features[mplenv$mplist[i, ], "sample"]]) + tbl <- table(sampleGroups[peaks[mplenv$mplist[i, ], "sample"]]) sampCounts[names(tbl)] <- as.numeric(tbl) groupmat[i, 7 + seq_len(nSampleGroups)] <- sampCounts - ## gnum <- sampleGroups[unique(features[mplenv$mplist[i, ], "sample"])] + ## gnum <- sampleGroups[unique(peaks[mplenv$mplist[i, ], "sample"])] ## for (j in seq(along = gcount)) ## gcount[j] <- sum(gnum == j) ## groupmat[i, 7 + seq(along = gcount)] <- gcount groupindex[[i]] <- mplenv$mplist[i, (which(mplenv$mplist[i,]>0))] } - return(list(featureGroups = groupmat, featureIndex = groupindex)) + return(list(featureDefinitions = groupmat, peakIndex = groupindex)) } diff --git a/R/functions-Chromatogram.R b/R/functions-Chromatogram.R new file mode 100644 index 000000000..6f31a6749 --- /dev/null +++ b/R/functions-Chromatogram.R @@ -0,0 +1,89 @@ +#' @include DataClasses.R +.SUPPORTED_AGG_FUN_CHROM <- c("sum", "max", "min", "mean") +names(.SUPPORTED_AGG_FUN_CHROM) <- + c("Total ion chromatogram (TIC).", "Base peak chromatogram (BPC).", + "Intensity representing the minimum intensity across the mz range.", + "Intensity representing the mean intensity across the mz range.") + +##' @title Validation function for Chromatogram objects +##' +##' @description This function can be used instead of the \code{validObject} to +##' check if the chromatogram is valid, without having to call the validity +##' method on all super classes. +##' +##' @param object A \code{Chromatogram} object. +##' +##' @return \code{TRUE} if the \code{object} is valid and the error messages +##' otherwise (i.e. a \code{character}). +##' @author Johannes Rainer +##' @noRd +validChromatogram <- function(object) { + msg <- validMsg(NULL, NULL) + if (length(object@rtime) != length(object@intensity)) + msg <- validMsg(msg, "Length of 'rt' and 'intensity' have to match!") + if (is.unsorted(object@mz)) + msg <- validMsg(msg, "'mz' has to be increasingly ordered!") + if (is.unsorted(object@rtime)) + msg <- validMsg(msg, paste0("'rtime' has to be increasingly ordered!")) + if (length(object@mz) > 0 & length(object@mz) != 2) + msg <- validMsg(msg, paste0("'mz' is supposed to contain the ", + "minimum and maximum mz values for the ", + "chromatogram.")) + if (length(object@filterMz) > 0 & length(object@filterMz) != 2) + msg <- validMsg(msg, paste0("'filterMz' is supposed to contain the ", + "minimum and maximum mz values of the filter", + " used to create the chromatogram.")) + if (length(object@fromFile) > 1 | any(object@fromFile < 0)) + msg <- validMsg(msg, paste0("'fromFile' is supposed to be a single ", + "positive integer!")) + if (length(object@aggregationFun) > 1) + msg <- validMsg(msg, "Length of 'aggregationFun' has to be 1!") + if (length(object@aggregationFun)) { + if (!object@aggregationFun %in% .SUPPORTED_AGG_FUN_CHROM) + msg <- validMsg(msg, paste0("Invalid value for 'aggregationFun'! ", + "only ", + paste0("'", .SUPPORTED_AGG_FUN_CHROM,"'", + collapse = ","), " are allowed!")) + } + if (is.null(msg)) TRUE + else msg +} + +##' @description \code{Chromatogram}: create an instance of the +##' \code{Chromatogram} class. +##' +##' @param rtime \code{numeric} with the retention times (length has to be equal +##' to the length of \code{intensity}). +##' +##' @param intensity \code{numeric} with the intensity values (length has to be +##' equal to the length of \code{rtime}). +##' +##' @param mz \code{numeric(2)} representing the mz value range (min, max) +##' on which the chromatogram was created. This is supposed to contain the +##' \emph{real} range of mz values in contrast to the \code{filterMz} below. +##' If not applicable use \code{mzrange = c(0, 0)}. +##' +##' @param filterMz \code{numeric(2)} representing the mz value range (min, +##' max) that was used to filter the original object on mz dimension. If not +##' applicable use \code{filterMz = c(0, 0)}. +##' +##' @param fromFile \code{integer(1)} the index of the file within the +##' \code{\link{OnDiskMSnExp}} or \code{\link{XCMSnExp}} from which the +##' chromatogram was extracted. +##' +##' @param aggregationFun \code{character} string specifying the function that +##' was used to aggregate intensity values for the same retention time across the +##' mz range. Supported are \code{"sum"} (total ion chromatogram), \code{"max"} +##' (base peak chromatogram), \code{"min"} and \code{"mean"}. +##' +##' @slot rtime,intensity,mzrange,filterMzrange,fromFile,aggregationFun See corresponding parameter above. +##' +##' @rdname Chromatogram-class +Chromatogram <- function(rtime = numeric(), intensity = numeric(), + mz = c(0, 0), filterMz = c(0, 0), + fromFile = integer(), + aggregationFun = character()) { + return(new("Chromatogram", rtime = rtime, intensity = intensity, + mz = range(mz), filterMz = range(filterMz), + fromFile = as.integer(fromFile), aggregationFun = aggregationFun)) +} diff --git a/R/functions-MsFeatureData.R b/R/functions-MsFeatureData.R index 9c854f122..6df12c801 100644 --- a/R/functions-MsFeatureData.R +++ b/R/functions-MsFeatureData.R @@ -1,160 +1,165 @@ ## Functions for MsFeatureData classes. #' @include DataClasses.R -##' Validates a 'feature' matrix or data.frame and ensures that it contains all +##' Validates a 'chromPeaks' matrix or data.frame and ensures that it contains all ##' required columns and that all columns are of numeric data type. ##' @return \code{TRUE} or a \code{character} with the error message. ##' @noRd -.validFeatureMatrix <- function(x) { - msg <- validMsg(NULL, NULL) +.validChromPeaksMatrix <- function(x) { + msg <- character() if (length(x)) { if (!(is.matrix(x) | is.data.frame(x))) - return(paste0("'features' has to be a matrix or a data.frame!")) - hasReqCols <- .XCMS_REQ_FEATS_COLS %in% colnames(x) + return(paste0("'chromPeaks' has to be a matrix or a data.frame!")) + hasReqCols <- .REQ_PEAKS_COLS %in% colnames(x) if (any(!hasReqCols)) return(paste0("Required columns ", - paste0("'", .XCMS_REQ_FEATS_COLS[!hasReqCols], + paste0("'", .REQ_PEAKS_COLS[!hasReqCols], "'", collapse = ", "), " not", - " present in 'features' matrix!")) + " present in 'chromPeaks' matrix!")) ## Check data.types - all have to be numeric. - typeOK <- apply(x[, .XCMS_REQ_FEATS_COLS, drop = FALSE], MARGIN = 2, + typeOK <- apply(x[, .REQ_PEAKS_COLS, drop = FALSE], MARGIN = 2, is.numeric) if (any(!typeOK)) return(paste0("Values in column(s) ", paste0("'", names(typeOK)[!typeOK], "'", collapse = ", ")), - " of the 'features' matrix are not numeric!") + " of the 'chromPeaks' matrix are not numeric!") } return(TRUE) } ##' @description Performs a validation check of all elements within the object: -##' 1) Allowed are: features (matrix), featureGroups (DataFrame) and +##' 1) Allowed are: chromPeaks (matrix), featureDefinitions (DataFrame) and ##' adjustedRtime (list). ##' @author Johannes Rainer ##' @return \code{TRUE} if object is valid, or a message with the error message. ##' @noRd validateMsFeatureData <- function(x) { - msg <- validMsg(NULL, NULL) + msg <- character() ks <- ls(x) if (length(ks)) { - validKeys <- ks %in% c("features", "featureGroups", "adjustedRtime") + validKeys <- ks %in% c("chromPeaks", "featureDefinitions", + "adjustedRtime") if (!all(validKeys)) { - msg <- validMsg(msg, paste0("Only elements named 'features', ", - "'featureGroups' and 'adjustedRtime' ", - "are allowed but I got ", - paste0("'", ks[!validKeys],"'"))) + msg <- c(msg, paste0("Only elements named 'chromPeaks', ", + "'featureDefinitions' and 'adjustedRtime' ", + "are allowed but I got ", + paste0("'", ks[!validKeys],"'"))) } - haveFts <- any(ks == "features") + haveFts <- any(ks == "chromPeaks") if (haveFts) { - OK <- .validFeatureMatrix(x$features) + OK <- .validChromPeaksMatrix(x$chromPeaks) if (is.character(OK)) - msg <- validMsg(msg, OK) + msg <- c(msg, OK) } - haveFGs <- any(ks == "featureGroups") + haveFGs <- any(ks == "featureDefinitions") if (haveFGs) { - if (is(x$featureGroups, "DataFrame")) { + if (is(x$featureDefinitions, "DataFrame")) { ## Check required columns. - hasReqCols <- .XCMS_REQ_FEATG_COLS %in% colnames(x$featureGroups) + hasReqCols <- .REQ_PEAKG_COLS %in% colnames(x$featureDefinitions) if (any(!hasReqCols)) { - msg <- validMsg(msg, - paste0("Required columns ", - paste0("'", .XCMS_REQ_FEATG_COLS[!hasReqCols], - "'", collapse = ", "), " not", - " present in 'featureGroups'!")) + msg <- c(msg, + paste0("Required columns ", + paste0("'", .REQ_PEAKG_COLS[!hasReqCols], + "'", collapse = ", "), " not", + " present in 'featureDefinitions'!")) } else { ## Check content! - if (!is(x$featureGroups$featureidx, "list")) - msg <- validMsg(msg, - paste0("Column 'featureidx' in '", - "featureGroups' is not a list!")) - for (col in .XCMS_REQ_FEATG_COLS[-length(.XCMS_REQ_FEATG_COLS)]) { - if (!is.numeric(x$featureGroups[, col])) - msg <- validMsg(msg, paste0("Column '", col, "' has", - " to be numeric!")) + if (!is(x$featureDefinitions$peakidx, "list")) + msg <- c(msg, + paste0("Column 'peakidx' in '", + "featureDefinitions' is not a list!")) + for (col in .REQ_PEAKG_COLS[-length(.REQ_PEAKG_COLS)]) { + if (!is.numeric(x$featureDefinitions[, col])) + msg <- c(msg, paste0("Column '", col, "' has", + " to be numeric!")) } if (haveFts) { - ## Check that indices are within 1:nrow(x$features) - if (!all(unlist(x$featureGroups$featureidx) %in% - 1:nrow(x$features))) - msg <- validMsg(msg, - paste0("Some of the indices in column", - " 'featureidx' of element ", - "'featureGroups' do not match ", - "rows of the 'features' matrix!")) + ## Check that indices are within 1:nrow(x$chromPeaks) + if (!all(unlist(x$featureDefinitions$peakidx) %in% + 1:nrow(x$chromPeaks))) + msg <- c(msg, + paste0("Some of the indices in column", + " 'peakidx' of element ", + "'featureDefinitionss' do not match ", + "rows of the 'chromPeaks' matrix!")) } } } else { - msg <- validMsg(msg, paste0("The 'featureGroups' element has to", - " be of type 'DataFrame' and not '", - class(x$featureGroups), "'!")) + msg <- c(msg, paste0("The 'featureDefinitionss' element has to", + " be of type 'DataFrame' and not '", + class(x$featureDefinitions), "'!")) } if (!haveFts) { - msg <- validMsg(msg, paste0("Can not have element 'featureGroups'", - " without element 'features'!")) + msg <- c(msg, paste0("Can not have element 'featureDefinitions'", + " without element 'chromPeaks'!")) } } haveRts <- any(ks == "adjustedRtime") if (haveRts) { - if (!haveFts) - msg <- validMsg(msg, paste0("Can not have element 'adjustedRtime'", - " without element 'features'!")) + ## Not true, since obiwarp works without peaks. + ## if (!haveFts) + ## msg <- c(msg, paste0("Can not have element 'adjustedRtime'", + ## " without element 'chromPeaks'!")) ## adjustedRtime has to be a list of numerics. if (!is.list(x$adjustedRtime)) { - msg <- validMsg(msg, paste0("The 'alignedRtime' element has to ", - "be of type 'list' and not '", - class(x$adjustedRtime), "'!")) + msg <- c(msg, paste0("The 'alignedRtime' element has to ", + "be of type 'list' and not '", + class(x$adjustedRtime), "'!")) } else { areNum <- unlist(lapply(x$adjustedRtime, function(z) { return(is.numeric(z)) })) if (!all(areNum)) - msg <- validMsg(msg, paste0("The 'alignedRtime' element has", - " to be a list of numeric ", - "vectors!")) + msg <- c(msg, paste0("The 'alignedRtime' element has", + " to be a list of numeric ", + "vectors!")) } } } - if (is.null(msg)) - return(TRUE) - else return(msg) + ## if (length(msg) == 0) + ## return(TRUE) + ## else return(msg) + return(msg) } -##' @description Filter features and sync them with with the present -##' filterGroups, i.e. update their featureidx column or remove them. +##' @description Filter chromPeaks and sync them with with the present +##' filterGroups, i.e. update their peakidx column or remove them. ##' ##' @param x A \code{MsFeatureData} or an \code{XCMSnExp} object. -##' @param idx \code{numeric} with the indices of the features to keep. +##' @param idx \code{numeric} with the indices of the chromatographic peaks to +##' keep. ##' ##' @return A \code{MsFeatureData}. ##' @author Johannes Rainer ##' @noRd -.filterFeatures <- function(x, idx) { +.filterChromPeaks <- function(x, idx) { if (missing(idx)) return(x) - if (!hasDetectedFeatures(x)) + if (!hasChromPeaks(x)) return(x) - fts <- features(x) + fts <- chromPeaks(x) idx <- sort(idx) if (!all(idx %in% 1:nrow(fts))) - stop("All indices in 'idx' have to be within 1 and nrow of the feature", + stop("All indices in 'idx' have to be within 1 and nrow of the peak", " matrix.") new_e <- new("MsFeatureData") - features(new_e) <- fts[idx, , drop = FALSE] - if (hasAlignedFeatures(x)) { - af <- featureGroups(x) + chromPeaks(new_e) <- fts[idx, , drop = FALSE] + if (hasFeatures(x)) { + af <- featureDefinitions(x) af <- split(af, 1:nrow(af)) afL <- lapply(af, function(z) { - if(all(z$featureidx[[1]] %in% idx)) { - z$featureidx <- list(match(z$featureidx[[1]], idx)) + if(all(z$peakidx[[1]] %in% idx)) { + z$peakidx <- list(match(z$peakidx[[1]], idx)) return(z) } else { return(NULL) } }) af <- do.call(rbind, afL) - featureGroups(new_e) <- af + if (length(af) > 0) + featureDefinitions(new_e) <- af } if (hasAdjustedRtime(x)) { if (is(x, "XCMSnExp")) diff --git a/R/functions-OnDiskMSnExp.R b/R/functions-OnDiskMSnExp.R index e163a9a47..aaeb21c25 100644 --- a/R/functions-OnDiskMSnExp.R +++ b/R/functions-OnDiskMSnExp.R @@ -1,44 +1,47 @@ ## Functions for MSnbase's OnDiskMSnExp objects -#' @include do_detectFeatures-functions.R DataClasses.R +#' @include do_findChromPeaks-functions.R DataClasses.R ##' @param x an OnDiskMSnExp representing the whole experiment. -##' @param method The feature detection method to be used. Can be "centWave" etc. +##' @param method The (chromatographic) peak detection method to be used. Can be +##' "centWave" etc. ##' @param param A class extending Param containing all parameters for the -##' feature detection method. +##' peak detection method. ##' ##' @return a list of length 2, \code{peaks} containing a matrix with the -##' identified peaks and \code{date} the time stamp when the feature detection +##' identified peaks and \code{date} the time stamp when the peak detection ##' was started. ##' @noRd -detectFeatures_OnDiskMSnExp <- function(object, method = "centWave", +findChromPeaks_OnDiskMSnExp <- function(object, method = "centWave", param) { if (missing(param)) stop("'param' has to be specified!") ## pass the spectra to the _Spectrum_list function - return(detectFeatures_Spectrum_list(x = spectra(object), method = method, + return(findChromPeaks_Spectrum_list(x = spectra(object), method = method, param = param, rt = rtime(object))) } -##' Run the feature detection on a list of Spectrum1 objects from the same +##' Run the peak detection on a list of Spectrum1 objects from the same ##' file ##' ##' @param x A list of Spectrum1 objects of a sample. -##' @param method The feature detection method to be used. Can be "centWave" etc. +##' @param method The peak detection method to be used. Can be "centWave" etc. ##' @param param A class extending Param containing all parameters for the -##' feature detection method. +##' peak detection method. ##' @param rt Numeric with the retention times for the spectra. If not provided ##' it is extracted from the spectra. ##' @return a list of length 2, \code{peaks} containing a matrix with the -##' identified peaks and \code{date} the time stamp when the feature detection +##' identified peaks and \code{date} the time stamp when the peak detection ##' was started. ##' @author Johannes Rainer ##' @noRd -detectFeatures_Spectrum_list <- function(x, method = "centWave", param, rt) { +findChromPeaks_Spectrum_list <- function(x, method = "centWave", param, rt) { method <- match.arg(method, c("centWave", "massifquant", "matchedFilter", "MSW", "centWaveWithPredIsoROIs")) - method <- paste0("do_detectFeatures_", method) + method <- paste0("do_findChromPeaks_", method) + if (method == "MSW") + method <- paste0("do_findPeaks_", method) if (missing(param)) stop("'param' has to be specified!") ## Check if the spectra are orderd by rt. @@ -60,17 +63,17 @@ detectFeatures_Spectrum_list <- function(x, method = "centWave", param, rt) { } ## That's a special case since we don't expect to have rt available for this. -detectFeatures_MSW_OnDiskMSnExp <- function(object, method = "MSW", +findPeaks_MSW_OnDiskMSnExp <- function(object, method = "MSW", param) { if (missing(param)) stop("'param' has to be specified!") ## pass the spectra to the _Spectrum_list function - return(detectFeatures_MSW_Spectrum_list(x = spectra(object), method = method, + return(findPeaks_MSW_Spectrum_list(x = spectra(object), method = method, param = param)) } -detectFeatures_MSW_Spectrum_list <- function(x, method = "MSW", param) { +findPeaks_MSW_Spectrum_list <- function(x, method = "MSW", param) { method <- match.arg(method, c("MSW")) - method <- paste0("do_detectFeatures_", method) + method <- paste0("do_findPeaks_", method) if (missing(param)) stop("'param' has to be specified!") mzs <- lapply(x, mz) @@ -118,9 +121,9 @@ detectFeatures_MSW_Spectrum_list <- function(x, method = "MSW", param) { } ##' @description Processes the result list returned by an lapply/bplapply to -##' detectFeatures_Spectrum_list or detectFeatures_OnDiskMSnExp and returns a +##' findChromPeaks_Spectrum_list or findChromPeaks_OnDiskMSnExp and returns a ##' list with two elements: \code{$peaks} the peaks matrix of identified -##' features and \code{$procHist} a list of ProcessHistory objects (empty if +##' peaks and \code{$procHist} a list of ProcessHistory objects (empty if ##' \code{getProcHist = FALSE}). ##' @param x See description above. ##' @param getProcHist Wheter ProcessHistory objects should be returned too. @@ -143,14 +146,14 @@ detectFeatures_MSW_Spectrum_list <- function(x, method = "MSW", param) { pks[[i]] <- cbind(x[[i]]$peaks, sample = rep.int(i, n_pks)) } if (getProcHist) - phList[[i]] <- ProcessHistory(info. = paste0("Feature detection in '", - basename(fnames[i]), - "': ", n_pks, - " features identified."), - date. = x[[i]]$date, - type. = .PROCSTEP.FEATURE.DETECTION, - fileIndex. = i - ) + phList[[i]] <- ProcessHistory( + info. = paste0("Chromatographic peak detection in '", + basename(fnames[i]), "': ", n_pks, + " peaks identified."), + date. = x[[i]]$date, + type. = .PROCSTEP.PEAK.DETECTION, + fileIndex. = i + ) } return(list(peaks = pks, procHist = phList)) } @@ -310,6 +313,9 @@ detectFeatures_MSW_Spectrum_list <- function(x, method = "MSW", param) { } message("OK") return(rtadj) + ## Related to issue #122: try to resemble the rounding done in the + ## recor.obiwarp method. + ## return(round(rtadj, 2)) }, cntr = centerObject, cntrPr = profCtr, parms = param) ## Add also the rtime of the center sample: adjRt <- vector("list", nSamples) diff --git a/R/functions-Params.R b/R/functions-Params.R index 259f255a5..2f40eebc2 100644 --- a/R/functions-Params.R +++ b/R/functions-Params.R @@ -39,10 +39,10 @@ ## CentWaveParam ##' @return The \code{CentWaveParam} function returns a \code{CentWaveParam} -##' class instance with all of the settings specified for feature detection by -##' the centWave method. +##' class instance with all of the settings specified for chromatographic peak +##' detection by the centWave method. ##' -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave CentWaveParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, mzdiff = -0.001, fitgauss = FALSE, @@ -62,9 +62,9 @@ CentWaveParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, ##' @return The \code{MatchedFilterParam} function returns a ##' \code{MatchedFilterParam} class instance with all of the settings specified -##' for feature detection by the centWave method. +##' for chromatographic detection by the \emph{matchedFilter} method. ##' -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter MatchedFilterParam <- function(binSize = 0.1, impute = "none", baseValue = numeric(), distance = numeric(), fwhm = 30, sigma = fwhm / 2.3548, @@ -80,10 +80,10 @@ MatchedFilterParam <- function(binSize = 0.1, impute = "none", ## MassifquantParam ##' @return The \code{MassifquantParam} function returns a \code{MassifquantParam} -##' class instance with all of the settings specified for feature detection by -##' the centWave method. +##' class instance with all of the settings specified for chromatographic peak +##' detection by the \emph{massifquant} method. ##' -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant MassifquantParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, mzdiff = -0.001, fitgauss = FALSE, @@ -102,7 +102,7 @@ MassifquantParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, ############################################################ ## MSWParam -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' ##' @param scales Numeric defining the scales of the continuous wavelet ##' transform (CWT). @@ -136,10 +136,10 @@ MassifquantParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, ##' \code{MassSpecWavelet} package. ##' ##' @return The \code{MSWParam} function returns a \code{MSWParam} -##' class instance with all of the settings specified for feature detection by -##' the centWave method. +##' class instance with all of the settings specified for peak detection by +##' the \emph{MSW} method. ##' -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW MSWParam <- function(snthresh = 3, verboseColumns = FALSE, scales = c(1, seq(2, 30, 2), seq(32, 64, 4)), nearbyPeak = TRUE, peakScaleRange = 5, @@ -161,10 +161,10 @@ MSWParam <- function(snthresh = 3, verboseColumns = FALSE, ##' @return The \code{CentWavePredIsoParam} function returns a ##' \code{CentWavePredIsoParam} class instance with all of the settings -##' specified for the two-step centWave-based feature detection considering also -##' feature isotopes. +##' specified for the two-step centWave-based peak detection considering also +##' isotopes. ##' -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs CentWavePredIsoParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, mzdiff = -0.001, fitgauss = FALSE, @@ -185,17 +185,17 @@ CentWavePredIsoParam <- function(ppm = 25, peakwidth = c(20, 50), snthresh = 10, ############################################################ -## FeatureDensityParam +## PeakDensityParam -##' @return The \code{FeatureDensityParam} function returns a -##' \code{FeatureDensityParam} class instance with all of the settings -##' specified for feature alignment based on feature densities. +##' @return The \code{PeakDensityParam} function returns a +##' \code{PeakDensityParam} class instance with all of the settings +##' specified for chromatographic peak alignment based on peak densities. ##' -##' @rdname groupFeatures-density -FeatureDensityParam <- function(sampleGroups = numeric(), bw = 30, +##' @rdname groupChromPeaks-density +PeakDensityParam <- function(sampleGroups = numeric(), bw = 30, minFraction = 0.5, minSamples = 1, binSize = 0.25, maxFeatures = 50) { - return(new("FeatureDensityParam", sampleGroups = sampleGroups, bw = bw, + return(new("PeakDensityParam", sampleGroups = sampleGroups, bw = bw, minFraction = minFraction, minSamples = minSamples, binSize = binSize, maxFeatures = maxFeatures)) } @@ -205,9 +205,9 @@ FeatureDensityParam <- function(sampleGroups = numeric(), bw = 30, ##' @return The \code{MzClustParam} function returns a ##' \code{MzClustParam} class instance with all of the settings -##' specified for high resolution single spectra feature alignment. +##' specified for high resolution single spectra peak alignment. ##' -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust MzClustParam <- function(sampleGroups = numeric(), ppm = 20, absMz = 0, minFraction = 0.5, minSamples = 1) { return(new("MzClustParam", sampleGroups = sampleGroups, ppm = ppm, @@ -217,35 +217,35 @@ MzClustParam <- function(sampleGroups = numeric(), ppm = 20, absMz = 0, ############################################################ -## NearestFeaturesParam +## NearestPeaksParam -##' @return The \code{NearestFeaturesParam} function returns a -##' \code{NearestFeaturesParam} class instance with all of the settings -##' specified for high resolution single spectra feature alignment. +##' @return The \code{NearestPeaksParam} function returns a +##' \code{NearestPeaksParam} class instance with all of the settings +##' specified for peak alignment based on peak proximity. ##' -##' @rdname groupFeatures-nearest -NearestFeaturesParam <- function(sampleGroups = numeric(), mzVsRtBalance = 10, - absMz = 0.2, absRt = 15, kNN = 10) { - return(new("NearestFeaturesParam", sampleGroups = sampleGroups, +##' @rdname groupChromPeaks-nearest +NearestPeaksParam <- function(sampleGroups = numeric(), mzVsRtBalance = 10, + absMz = 0.2, absRt = 15, kNN = 10) { + return(new("NearestPeaksParam", sampleGroups = sampleGroups, mzVsRtBalance = mzVsRtBalance, absMz = absMz, absRt = absRt, kNN = kNN)) } ############################################################ -## FeatureGroupsParam +## PeakGroupsParam -##' @return The \code{FeatureGroupsParam} function returns a -##' \code{FeatureGroupsParam} class instance with all of the settings +##' @return The \code{PeakGroupsParam} function returns a +##' \code{PeakGroupsParam} class instance with all of the settings ##' specified for retention time adjustment based on \emph{house keeping} -##' feature groups. +##' features/peak groups. ##' -##' @rdname adjustRtime-featureGroups -FeatureGroupsParam <- function(minFraction = 0.9, extraFeatures = 1, +##' @rdname adjustRtime-peakGroups +PeakGroupsParam <- function(minFraction = 0.9, extraPeaks = 1, smooth = "loess", span = 0.2, family = "gaussian") { - return(new("FeatureGroupsParam", minFraction = minFraction, - extraFeatures = extraFeatures, smooth = smooth, span = span, + return(new("PeakGroupsParam", minFraction = minFraction, + extraPeaks = extraPeaks, smooth = smooth, span = span, family = family)) } diff --git a/R/functions-XCMSnExp.R b/R/functions-XCMSnExp.R index faa541e55..6c020d3e7 100644 --- a/R/functions-XCMSnExp.R +++ b/R/functions-XCMSnExp.R @@ -46,16 +46,16 @@ dropProcessHistoriesList <- function(x, type, num = -1) { if (any(msLevel(from) > 1)) stop("Coercing an XCMSnExp with MS level > 1 is not yet supported!") xs <- new("xcmsSet") - ## @peaks <- features - if (hasDetectedFeatures(from)) - xs@peaks <- features(from) - ## @groups <- part of featureGroups - ## @groupidx <- featureGroups(x)$featureidx - if (hasAlignedFeatures(from)){ - fgs <- featureGroups(from) + ## @peaks <- chromPeaks + if (hasChromPeaks(from)) + xs@peaks <- chromPeaks(from) + ## @groups <- part of featureDefinitions + ## @groupidx <- featureDefinitions(x)$peakidx + if (hasFeatures(from)){ + fgs <- featureDefinitions(from) xs@groups <- S4Vectors::as.matrix(fgs[, -ncol(fgs)]) rownames(xs@groups) <- NULL - xs@groupidx <- fgs$featureidx + xs@groupidx <- fgs$peakidx } ## @rt combination from rtime(x) and adjustedRtime(x) rts <- list() @@ -77,7 +77,7 @@ dropProcessHistoriesList <- function(x, type, num = -1) { profStep <- 0.1 profParam <- list() ## If we've got any MatchedFilterParam we can take the values from there - ph <- processHistory(from, type = .PROCSTEP.FEATURE.DETECTION) + ph <- processHistory(from, type = .PROCSTEP.PEAK.DETECTION) if (length(ph)) { if (is(ph[[1]], "XProcessHistory")) { prm <- processParam(ph[[1]]) @@ -182,7 +182,7 @@ dropProcessHistoriesList <- function(x, type, num = -1) { fns <- fileNames(x) if (is(x, "XCMSnExp")) { ## Now, the filterRt might get heavy for XCMSnExp objects if we're - ## filtering also the features and featureGroups! + ## filtering also the chromatographic peaks and features! msfd <- new("MsFeatureData") if (hasAdjustedRtime(x)) { ## just copy over the retention time. @@ -190,8 +190,8 @@ dropProcessHistoriesList <- function(x, type, num = -1) { } lockEnvironment(msfd, bindings = TRUE) x@msFeatureData <- msfd - ## with an XCMSnExp without features and featureGroups filterRt should be - ## faster. + ## with an XCMSnExp without chrom. peaks and features filterRt + ## should be faster. } subs <- filterMz(filterRt(x, rt = rtrange), mz = mzrange) if (base::length(subs) == 0) { @@ -204,3 +204,86 @@ dropProcessHistoriesList <- function(x, type, num = -1) { ## WARN: fromFile reported within the Spectra might not be correct!!! return(res) } + +##' @description Extract a chromatogram from an \code{OnDiskMSnExp} or +##' \code{XCMSnExp} subsetting to the provided retention time range +##' (\code{rt}) and using the function \code{aggregationFun} to aggregate +##' intensity values for the same retention time across the mz range +##' (\code{mz}). +##' +##' @param x An \code{OnDiskMSnExp} or \code{XCMSnExp} object. +##' +##' @param rt \code{numeric(2)} providing the lower and upper retention time. It +##' is also possible to submit a \code{numeric(1)} in which case \code{range} is +##' called on it to transform it to a \code{numeric(2)}. +##' +##' @param mz \code{numeric(2)} providing the lower and upper mz value for +##' the mz range. It is also possible to submit a \code{numeric(1)} in which case +##' \code{range} is called on it to transform it to a \code{numeric(2)}. +##' +##' @param aggregationFun The function to be used to aggregate intensity values +##' across the mz range for the same retention time. +##' +##' @param ... Additional arguments to be passed to the object's \code{rtime} +##' call. +##' +##' @return A \code{list} with the \code{Chromatogram} objects. If no data was +##' present for the specified \code{rtrange} and \code{mzrange} the function +##' returns a \code{list} of length \code{0}. +##' +##' @author Johannes Rainer +##' @noRd +.extractChromatogram <- function(x, rt, mz, aggregationFun = "sum", ...) { + if (!any(.SUPPORTED_AGG_FUN_CHROM == aggregationFun)) + stop("'aggregationFun' should be one of ", + paste0("'", .SUPPORTED_AGG_FUN_CHROM, "'", collapse = ", ")) + if (!missing(rt)) { + rt <- range(rt, na.rm = TRUE) + if (length(rt) != 2) + stop("'rt' has to be a numeric of length 2!") + } + if (!missing(mz)) { + mz <- range(mz, na.rm = TRUE) + if (length(mz) != 2) + stop("'mz' has to be a numeric of length 2!") + fmzr <- mz + } else fmzr <- c(0, 0) + ## Subset the object based on rt and mz range. + subs <- filterMz(filterRt(x, rt = rt), mz = mz) + if (length(subs) == 0) { + return(list()) + } + ## Now, call spectrapply on the object to return the data we need from each + ## Spectrum: the aggregated intensity values per spectrum and the mz value + ## range. + res <- spectrapply(subs, FUN = function(z) { + if (!z@peaksCount) + return(list()) + return(c(range(z@mz), do.call(aggregationFun, list(z@intensity)))) + }) + ## Do I want to drop the names? + not_empty <- base::which(base::lengths(res) > 0) + if (length(not_empty)) { + res <- split(res[not_empty], f = fromFile(subs)[not_empty]) + rtm <- split(rtime(subs)[not_empty], f = fromFile(subs)[not_empty]) + ## We want to have one Chromatogram per file. + ## Let's use a simple for loop here - no need for an mapply (yet). + resL <- vector("list", length(res)) + for (i in 1:length(res)) { + allVals <- unlist(res[[i]], use.names = FALSE) + idx <- seq(3, length(allVals), by = 3) + mzr <- range(allVals[-idx], na.rm = TRUE, finite = TRUE) + ## Or should we drop the names completely? + ints <- allVals[idx] + names(ints) <- names(rtm[[i]]) + resL[[i]] <- Chromatogram(rtime = rtm[[i]], + intensity = ints, mz = mzr, + filterMz = fmzr, + fromFile = as.integer(names(res)[i]), + aggregationFun = aggregationFun) + } + return(resL) + } else { + return(list()) + } +} diff --git a/R/functions-utils.R b/R/functions-utils.R index 24c3947c8..51efc12a3 100644 --- a/R/functions-utils.R +++ b/R/functions-utils.R @@ -37,7 +37,7 @@ valueCount2ScanIndex <- function(valCount){ ##' to be used mainly in the transition phase from xcms to xcms version 3. ##' @details The functions/methods that will be affected by this are: ##' \itemize{ -##' \item \code{\link{do_detectFeatures_matchedFilter}} +##' \item \code{\link{do_findChromPeaks_matchedFilter}} ##' } ##' @param x logical(1) to specify whether or not original ##' old code should be used in corresponding functions. If not provided the diff --git a/R/functions-xcmsSet.R b/R/functions-xcmsSet.R index 789e758d1..f3c130667 100644 --- a/R/functions-xcmsSet.R +++ b/R/functions-xcmsSet.R @@ -1,5 +1,5 @@ ## Functions for xcmsSet objects. -#' @include DataClasses.R do_detectFeatures-functions.R +#' @include DataClasses.R do_findChromPeaks-functions.R ## The "constructor" ## The "new" xcmsSet method using BiocParallel. @@ -146,7 +146,7 @@ xcmsSet <- function(files = NULL, snames = NULL, sclass = NULL, ## Error identifying features in <>: Error:... -> info + error isOK <- bpok(res) if (all(!isOK)) - stop("Feature detection failed for all files!", + stop("Chromatographic peak detection failed for all files!", " The first error was: ", res[[1]]) if (any(!isOK)) { ## Use scantime from a working file one of the failing ones. @@ -170,24 +170,24 @@ xcmsSet <- function(files = NULL, snames = NULL, sclass = NULL, warning("Only 1 peak found in sample ", snames[i], ".") else if (nrow(pks) < 5) warning("Only ", nrow(pks), " found in sample ", snames[i], ".") - proclist[[i]] <- ProcessHistory(info. = paste0("Feature detection in '", + proclist[[i]] <- ProcessHistory(info. = paste0("Peak detection in '", basename(files[i]), "': ", nrow(pks), - " features identified."), + " peaks identified."), date. = res[[i]]$date, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex. = i) } else { scntlist[[i]] <- scnt peaklist[[i]] <- NULL proclist[[i]] <- ProcessHistory(info. = paste0("Error identifying", - " features in '", + " peaks in '", basename(files[i]), "': ", res[[i]]), error. = res[[i]], - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex. = i) - warning("Feature detection failed in '", files[i], "':", res[[i]]) + warning("Peak detection failed in '", files[i], "':", res[[i]]) } } ## peaklist <- lapply(res, function(x) x$peaks) diff --git a/R/methods-Chromatogram.R b/R/methods-Chromatogram.R new file mode 100644 index 000000000..8971b1d52 --- /dev/null +++ b/R/methods-Chromatogram.R @@ -0,0 +1,108 @@ +#' @include DataClasses.R functions-Chromatogram.R + +setMethod("initialize", "Chromatogram", function(.Object, ...) { + classVersion(.Object)["Chromatogram"] <- "0.0.1" + callNextMethod(.Object, ...) +}) + + +##' @rdname Chromatogram-class +setMethod("show", "Chromatogram", function(object) { + cat("Object of class: ", class(object), "\n", sep = "") + if (length(object@aggregationFun)) + cat(names(.SUPPORTED_AGG_FUN_CHROM)[.SUPPORTED_AGG_FUN_CHROM == + object@aggregationFun], "\n") + cat("length of object: ", length(object@rtime), "\n", sep = "") + cat("from file: ", object@fromFile, "\n", sep = "") + cat("mz range: [", object@mz[1], ", ", object@mz[2], "]\n", sep = "") + rtr <- range(object@rtime) + cat("rt range: [", rtr[1], ", ", rtr[2], "]\n", sep = "") +}) + +## Methods: + +## rtime +##' @description \code{rtime} returns the retention times for the rentention time +##' - intensity pairs stored in the chromatogram. +##' +##' @param object A \code{Chromatogram} object. +##' +##' @rdname Chromatogram-class +setMethod("rtime", "Chromatogram", function(object) { + return(object@rtime) +}) + +## intensity +##' @description \code{intensity} returns the intensity for the rentention time +##' - intensity pairs stored in the chromatogram. +##' +##' @rdname Chromatogram-class +setMethod("intensity", "Chromatogram", function(object) { + return(object@intensity) +}) + +## mz +##' @description \code{mz} get or set the mz range of the +##' chromatogram. +##' +##' @param filter For \code{mz}: whether the mz range used to filter the +##' original object should be returned (\code{filter = TRUE}), or the mz range +##' calculated on the real data (\code{filter = FALSE}). +##' +##' @rdname Chromatogram-class +setMethod("mzrange", "Chromatogram", function(object, filter = FALSE) { + if (filter) + return(object@filterMz) + return(object@mz) +}) +## ##' @rdname Chromatogram-class +## setReplaceMethod("mz", "CentWaveParam", function(object, value) { +## object@mzrange <- value +## if (validObject(object)) +## return(object) +## }) + +## aggregationFun +##' @aliases aggregationFun +##' @description \code{aggregationFun,aggregationFun<-} get or set the +##' aggregation function. +##' +##' @rdname Chromatogram-class +setMethod("aggregationFun", "Chromatogram", function(object) { + return(object@aggregationFun) +}) +## ##' @rdname Chromatogram-class +## setReplaceMethod("aggregationFun", "CentWaveParam", function(object, value) { +## object@aggregationFun <- value +## if (validObject(object)) +## return(object) +## }) + +## fromFile +##' @description \code{fromFile} returns the value from the \code{fromFile} slot. +##' +##' @rdname Chromatogram-class +setMethod("fromFile", "Chromatogram", function(object) { + return(object@fromFile) +}) + +## length +##' @description \code{length} returns the length (number of retention time - +##' intensity pairs) of the chromatogram. +##' +##' @param x For \code{as.data.frame} and \code{length}: a \code{Chromatogram} +##' object. +##' +##' @rdname Chromatogram-class +setMethod("length", "Chromatogram", function(x) { + return(length(x@rtime)) +}) + +## as.data.frame +##' @description \code{as.data.frame} returns the \code{rtime} and +##' \code{intensity} values from the object as \code{data.frame}. +##' +##' @rdname Chromatogram-class +setMethod("as.data.frame", "Chromatogram", function(x) { + return(data.frame(rtime = x@rtime, intensity = x@intensity)) +}) diff --git a/R/methods-MsFeatureData.R b/R/methods-MsFeatureData.R index 446b024f9..254eccc2f 100644 --- a/R/methods-MsFeatureData.R +++ b/R/methods-MsFeatureData.R @@ -21,8 +21,8 @@ setMethod("show", "MsFeatureData", function(object) { } }) -## features: getter and setter for the features matrix. -## featureGroups: getter and setter for the featureGroups DataFrame. +## (features) chromPeaks: getter and setter for the chromatographic peaks matrix. +## (featureDefinitions) featureDefinitions: getter and setter for the features DataFrame. ## adjustedRtime: getter and setter for the adjustedRtime list. @@ -33,15 +33,15 @@ setMethod("hasAdjustedRtime", "MsFeatureData", function(object) { }) ##' @rdname XCMSnExp-class -setMethod("hasAlignedFeatures", "MsFeatureData", function(object) { - return(!is.null(object$featureGroups)) - ## return(any(ls(object) == "featureGroups")) +setMethod("hasFeatures", "MsFeatureData", function(object) { + return(!is.null(object$featureDefinitions)) + ## return(any(ls(object) == "featureDefinitions")) }) ##' @rdname XCMSnExp-class -setMethod("hasDetectedFeatures", "MsFeatureData", function(object) { - return(!is.null(object$features)) - ## return(any(ls(object) == "features")) +setMethod("hasChromPeaks", "MsFeatureData", function(object) { + return(!is.null(object$chromPeaks)) + ## return(any(ls(object) == "chromPeaks")) }) ##' @rdname XCMSnExp-class @@ -66,41 +66,41 @@ setMethod("dropAdjustedRtime", "MsFeatureData", function(object) { }) ##' @rdname XCMSnExp-class -setMethod("featureGroups", "MsFeatureData", function(object) { - if (hasAlignedFeatures(object)) - return(object$featureGroups) +setMethod("featureDefinitions", "MsFeatureData", function(object) { + if (hasFeatures(object)) + return(object$featureDefinitions) warning("No aligned feature information available.") return(NULL) }) ##' @rdname XCMSnExp-class -setReplaceMethod("featureGroups", "MsFeatureData", function(object, value) { - object$featureGroups <- value +setReplaceMethod("featureDefinitions", "MsFeatureData", function(object, value) { + object$featureDefinitions <- value if (validObject(object)) return(object) }) ##' @rdname XCMSnExp-class -setMethod("dropFeatureGroups", "MsFeatureData", function(object) { - if (hasAlignedFeatures(object)) - rm(list = "featureGroups", envir = object) +setMethod("dropFeatureDefinitions", "MsFeatureData", function(object) { + if (hasFeatures(object)) + rm(list = "featureDefinitions", envir = object) return(object) }) ##' @rdname XCMSnExp-class -setMethod("features", "MsFeatureData", function(object) { - if (hasDetectedFeatures(object)) - return(object$features) - warning("No detected features available.") +setMethod("chromPeaks", "MsFeatureData", function(object) { + if (hasChromPeaks(object)) + return(object$chromPeaks) + warning("No chromatographic peaks available.") return(NULL) }) ##' @rdname XCMSnExp-class -setReplaceMethod("features", "MsFeatureData", function(object, value) { - object$features <- value +setReplaceMethod("chromPeaks", "MsFeatureData", function(object, value) { + object$chromPeaks <- value if (validObject(object)) return(object) }) ##' @rdname XCMSnExp-class -setMethod("dropFeatures", "MsFeatureData", function(object) { - if (hasDetectedFeatures(object)) - rm(list = "features", envir = object) +setMethod("dropChromPeaks", "MsFeatureData", function(object) { + if (hasChromPeaks(object)) + rm(list = "chromPeaks", envir = object) return(object) }) diff --git a/R/methods-OnDiskMSnExp.R b/R/methods-OnDiskMSnExp.R index 397741a56..896ad202d 100644 --- a/R/methods-OnDiskMSnExp.R +++ b/R/methods-OnDiskMSnExp.R @@ -1,16 +1,16 @@ ## Methods for MSnbase's OnDiskMSnExp and MSnExp objects. -#' @include DataClasses.R functions-OnDiskMSnExp.R do_detectFeatures-functions.R +#' @include DataClasses.R functions-OnDiskMSnExp.R do_findChromPeaks-functions.R ## Main roxygen documentation for the centWace feature detection is in ## DataClasses, before the definition of the CentWaveParam class. -## The centWave feature detection method for OnDiskMSnExp: -##' @title Feature detection using the centWave method +## The centWave peak detection method for OnDiskMSnExp: +##' @title Chromatographic peak detection using the centWave method ##' -##' @description The \code{detectFeatures,OnDiskMSnExp,CentWaveParam} method -##' performs feature detection using the \emph{centWave} algorithm on all -##' samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +##' @description The \code{detectChromPeaks,OnDiskMSnExp,CentWaveParam} method +##' performs chromatographic peak detection using the \emph{centWave} algorithm +##' on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. ##' \code{\link[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. @@ -20,7 +20,7 @@ ##' the parallel processing mode using the \code{\link[BiocParallel]{register}} ##' method from the \code{BiocParallel} package. ##' -##' @param object For \code{detectFeatures}: Either an +##' @param object For \code{findChromPeaks}: Either an ##' \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} ##' object containing the MS- and all other experiment-relevant data. ##' @@ -32,25 +32,25 @@ ##' @param BPPARAM A parameter class specifying if and how parallel processing ##' should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. ##' See documentation of the \code{BiocParallel} for more details. If parallel -##' processing is enables, feature detection is performed in parallel on several +##' processing is enables, peak detection is performed in parallel on several ##' of the input samples. ##' ##' @param return.type Character specifying what type of object the method should -##' return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +##' return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or ##' \code{"xcmsSet"}. ##' -##' @return For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -##' \code{\link{XCMSnExp}} object with the results of the feature detection. +##' @return For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +##' \code{\link{XCMSnExp}} object with the results of the peak detection. ##' If \code{return.type = "list"} a list of length equal to the number of -##' samples with matrices specifying the identified features/peaks. +##' samples with matrices specifying the identified peaks. ##' If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -##' with the results of the feature detection. +##' with the results of the peak detection. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature detection. +##' the peak detection. ##' -##' @rdname featureDetection-centWave -setMethod("detectFeatures", +##' @rdname findChromPeaks-centWave +setMethod("findChromPeaks", signature(object = "OnDiskMSnExp", param = "CentWaveParam"), function(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") { return.type <- match.arg(return.type, c("XCMSnExp", "list", @@ -63,10 +63,10 @@ setMethod("detectFeatures", warning("Your data appears to be not centroided! CentWave", " works best on data in centroid mode.") ## (1) split the object per file. - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(lapply(1:length(fileNames(object)), filterFile, object = object), - FUN = detectFeatures_OnDiskMSnExp, + FUN = findChromPeaks_OnDiskMSnExp, method = "centWave", param = param) ## (3) collect the results. res <- .processResultList(resList, @@ -77,13 +77,13 @@ setMethod("detectFeatures", ## that later, but for now seems reasonable to have it in one, ## since we're calling the method once on all. xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex = 1:length(fileNames(object))) object <- as(object, "XCMSnExp") object@.processHistory <- list(xph) - if (hasAdjustedRtime(object) | hasAlignedFeatures(object)) + if (hasAdjustedRtime(object) | hasFeatures(object)) object@msFeatureData <- new("MsFeatureData") - features(object) <- do.call(rbind, res$peaks) + chromPeaks(object) <- do.call(rbind, res$peaks) if (validObject(object)) return(object) } @@ -105,17 +105,17 @@ setMethod("detectFeatures", }) -## The centWave feature detection method for MSnExp: -##' @title Feature detection using the centWave method +## The centWave peak detection method for MSnExp: +##' @title Chromatographic peak detection using the centWave method ##' -##' @description The \code{detectFeatures,MSnExp,CentWaveParam} method performs -##' feature detection using the \emph{centWave} algorithm on all samples from +##' @description The \code{findChromPeaks,MSnExp,CentWaveParam} method performs +##' peak detection using the \emph{centWave} algorithm on all samples from ##' an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and ##' intensity values of all spectra hence no additional data input from the ##' original files is required. ##' -##' @rdname featureDetection-centWave -setMethod("detectFeatures", +##' @rdname findChromPeaks-centWave +setMethod("findChromPeaks", signature(object = "MSnExp", param = "CentWaveParam"), function(object, param, BPPARAM = bpparam(), return.type = "list") { return.type <- match.arg(return.type, c("list", "xcmsSet")) @@ -127,16 +127,17 @@ setMethod("detectFeatures", ## filterFile is pretty slow on MSnExp. ms1_idx <- which(unname(msLevel(object)) == 1) if (length(ms1_idx) == 0) - stop("No MS1 spectra available for feature detection!") + stop("No MS1 spectra available for chromatographic peak", + " detection!") ## Check if the data is centroided if (!isCentroided(object[[ms1_idx[1]]])) warning("Your data appears to be not centroided! CentWave", " works best on data in centroid mode.") spect_list <- split(spectra(object)[ms1_idx], fromFile(object)[ms1_idx]) - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(spect_list, function(z) { - detectFeatures_Spectrum_list(z, + findChromPeaks_Spectrum_list(z, method = "centWave", param = param) }, BPPARAM = BPPARAM) @@ -161,11 +162,11 @@ setMethod("detectFeatures", } }) -## The matchedFilter feature detection method for OnDiskMSnExp: +## The matchedFilter peak detection method for OnDiskMSnExp: ##' @title Peak detection in the chromatographic time domain ##' -##' @description The \code{detectFeatures,OnDiskMSnExp,MatchedFilterParam} -##' method performs feature detection using the \emph{matchedFilter} algorithm +##' @description The \code{findChromPeaks,OnDiskMSnExp,MatchedFilterParam} +##' method performs peak detection using the \emph{matchedFilter} algorithm ##' on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. ##' \code{\link[MSnbase]{OnDiskMSnExp}} objects encapsule all experiment specific ##' data and load the spectra data (mz and intensity values) on the fly from the @@ -176,7 +177,7 @@ setMethod("detectFeatures", ##' the parallel processing mode using the \code{\link[BiocParallel]{register}} ##' method from the \code{BiocParallel} package. -##' @param object For \code{detectFeatures}: Either an +##' @param object For \code{findChromPeaks}: Either an ##' \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} ##' object containing the MS- and all other experiment-relevant data. ##' @@ -185,20 +186,20 @@ setMethod("detectFeatures", ##' @param param An \code{MatchedFilterParam} object containing all settings for ##' the matchedFilter algorithm. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @return For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -##' \code{\link{XCMSnExp}} object with the results of the feature detection. +##' @return For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +##' \code{\link{XCMSnExp}} object with the results of the peak detection. ##' If \code{return.type = "list"} a list of length equal to the number of -##' samples with matrices specifying the identified features/peaks. +##' samples with matrices specifying the identified peaks. ##' If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -##' with the results of the feature detection. +##' with the results of the peak detection. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature detection. +##' the chromatographic peak detection. ##' -##' @rdname featureDetection-matchedFilter -setMethod("detectFeatures", +##' @rdname findChromPeaks-matchedFilter +setMethod("findChromPeaks", signature(object = "OnDiskMSnExp", param = "MatchedFilterParam"), function(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") { return.type <- match.arg(return.type, c("XCMSnExp", "list", @@ -207,10 +208,10 @@ setMethod("detectFeatures", ## Restrict to MS1 data. object <- filterMsLevel(object, msLevel. = 1) ## (1) split the object per file. - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(lapply(1:length(fileNames(object)), filterFile, object = object), - FUN = detectFeatures_OnDiskMSnExp, + FUN = findChromPeaks_OnDiskMSnExp, method = "matchedFilter", param = param) ## (3) collect the results. res <- .processResultList(resList, @@ -221,13 +222,13 @@ setMethod("detectFeatures", ## that later, but for now seems reasonable to have it in one, ## since we're calling the method once on all. xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex = 1:length(fileNames(object))) object <- as(object, "XCMSnExp") object@.processHistory <- list(xph) - if (hasAdjustedRtime(object) | hasAlignedFeatures(object)) + if (hasAdjustedRtime(object) | hasFeatures(object)) object@msFeatureData <- new("MsFeatureData") - features(object) <- do.call(rbind, res$peaks) + chromPeaks(object) <- do.call(rbind, res$peaks) if (validObject(object)) return(object) } @@ -250,24 +251,25 @@ setMethod("detectFeatures", ##' @title Peak detection in the chromatographic time domain ##' -##' @description The \code{detectFeatures,MSnExp,MatchedFilterParam} method -##' performs feature detection using the \emph{matchedFilter} method on all +##' @description The \code{findChromPeaks,MSnExp,MatchedFilterParam} method +##' performs peak detection using the \emph{matchedFilter} method on all ##' samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain ##' mz and intensity values of all spectra hence no additional ##' data input from the original files is required. ##' -##' @rdname featureDetection-matchedFilter -setMethod("detectFeatures", +##' @rdname findChromPeaks-matchedFilter +setMethod("findChromPeaks", signature(object = "MSnExp", param = "MatchedFilterParam"), function(object, param, BPPARAM = bpparam(), return.type = "list") { return.type <- match.arg(return.type, c("list", "xcmsSet")) ms1_idx <- which(unname(msLevel(object)) == 1) if (length(ms1_idx) == 0) - stop("No MS1 spectra available for feature detection!") + stop("No MS1 spectra available for chromatographic peak", + " detection!") spect_list <- split(spectra(object)[ms1_idx], fromFile(object)[ms1_idx]) resList <- bplapply(spect_list, function(z) { - detectFeatures_Spectrum_list(z, + findChromPeaks_Spectrum_list(z, method = "matchedFilter", param = param) }, BPPARAM = BPPARAM) @@ -292,12 +294,12 @@ setMethod("detectFeatures", }) ## massifquant -## The massifquant feature detection method for OnDiskMSnExp: -##' @title Feature detection using the massifquant method +## The massifquant peak detection method for OnDiskMSnExp: +##' @title Chromatographic peak detection using the massifquant method ##' -##' @description The \code{detectFeatures,OnDiskMSnExp,MassifquantParam} -##' method performs feature detection using the \emph{massifquant} algorithm -##' on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +##' @description The \code{findChromPeaks,OnDiskMSnExp,MassifquantParam} +##' method performs chromatographic peak detection using the \emph{massifquant} +##' algorithm on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. ##' \code{\link[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. @@ -307,7 +309,7 @@ setMethod("detectFeatures", ##' the parallel processing mode using the \code{\link[BiocParallel]{register}} ##' method from the \code{BiocParallel} package. ##' -##' @param object For \code{detectFeatures}: Either an +##' @param object For \code{findChromPeaks}: Either an ##' \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} ##' object containing the MS- and all other experiment-relevant data. ##' @@ -316,20 +318,20 @@ setMethod("detectFeatures", ##' @param param An \code{MassifquantParam} object containing all settings for ##' the massifquant algorithm. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @return For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -##' \code{\link{XCMSnExp}} object with the results of the feature detection. +##' @return For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +##' \code{\link{XCMSnExp}} object with the results of the peak detection. ##' If \code{return.type = "list"} a list of length equal to the number of -##' samples with matrices specifying the identified features/peaks. +##' samples with matrices specifying the identified peaks. ##' If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -##' with the results of the feature detection. +##' with the results of the peak detection. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature detection. +##' the peak detection. ##' -##' @rdname featureDetection-massifquant -setMethod("detectFeatures", +##' @rdname findChromPeaks-massifquant +setMethod("findChromPeaks", signature(object = "OnDiskMSnExp", param = "MassifquantParam"), function(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") { return.type <- match.arg(return.type, c("XCMSnExp", "list", @@ -338,10 +340,10 @@ setMethod("detectFeatures", ## Restrict to MS1 data. object <- filterMsLevel(object, msLevel. = 1) ## (1) split the object per file. - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peaks detection. resList <- bplapply(lapply(1:length(fileNames(object)), filterFile, object = object), - FUN = detectFeatures_OnDiskMSnExp, + FUN = findChromPeaks_OnDiskMSnExp, method = "massifquant", param = param) ## (3) collect the results. res <- .processResultList(resList, @@ -352,13 +354,13 @@ setMethod("detectFeatures", ## that later, but for now seems reasonable to have it in one, ## since we're calling the method once on all. xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex = 1:length(fileNames(object))) object <- as(object, "XCMSnExp") object@.processHistory <- list(xph) - if (hasAdjustedRtime(object) | hasAlignedFeatures(object)) + if (hasAdjustedRtime(object) | hasFeatures(object)) object@msFeatureData <- new("MsFeatureData") - features(object) <- do.call(rbind, res$peaks) + chromPeaks(object) <- do.call(rbind, res$peaks) if (validObject(object)) return(object) } @@ -380,26 +382,27 @@ setMethod("detectFeatures", }) -##' @title Feature detection using the massifquant method +##' @title Chromatographic peak detection using the massifquant method ##' -##' @description The \code{detectFeatures,MSnExp,MassifquantParam} method -##' performs feature detection using the \emph{massifquant} method on all -##' samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain -##' mz and intensity values of all spectra hence no additional +##' @description The \code{findChromPeaks,MSnExp,MassifquantParam} method +##' performs chromatographic peak detection using the \emph{massifquant} method +##' on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects +##' contain mz and intensity values of all spectra hence no additional ##' data input from the original files is required. ##' -##' @rdname featureDetection-massifquant -setMethod("detectFeatures", +##' @rdname findChromPeaks-massifquant +setMethod("findChromPeaks", signature(object = "MSnExp", param = "MassifquantParam"), function(object, param, BPPARAM = bpparam(), return.type = "list") { return.type <- match.arg(return.type, c("list", "xcmsSet")) ms1_idx <- which(unname(msLevel(object)) == 1) if (length(ms1_idx) == 0) - stop("No MS1 spectra available for feature detection!") + stop("No MS1 spectra available for chromatographic peak", + " detection!") spect_list <- split(spectra(object)[ms1_idx], fromFile(object)[ms1_idx]) resList <- bplapply(spect_list, function(z) { - detectFeatures_Spectrum_list(z, + findChromPeaks_Spectrum_list(z, method = "massifquant", param = param) }, BPPARAM = BPPARAM) @@ -425,11 +428,11 @@ setMethod("detectFeatures", ## MSW -## The MSW feature detection method for OnDiskMSnExp: -##' @title Single-spectrum non-chromatography MS data feature detection +## The MSW peak detection method for OnDiskMSnExp: +##' @title Single-spectrum non-chromatography MS data peak detection ##' -##' @description The \code{detectFeatures,OnDiskMSnExp,MSWParam} -##' method performs feature detection in single-spectrum non-chromatography MS +##' @description The \code{findChromPeaks,OnDiskMSnExp,MSWParam} +##' method performs peak detection in single-spectrum non-chromatography MS ##' data using functionality from the \code{MassSpecWavelet} package on all ##' samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. ##' \code{\link[MSnbase]{OnDiskMSnExp}} objects encapsule all experiment specific @@ -441,7 +444,7 @@ setMethod("detectFeatures", ##' the parallel processing mode using the \code{\link[BiocParallel]{register}} ##' method from the \code{BiocParallel} package. ##' -##' @param object For \code{detectFeatures}: Either an +##' @param object For \code{findChromPeaks}: Either an ##' \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} ##' object containing the MS- and all other experiment-relevant data. ##' @@ -450,20 +453,20 @@ setMethod("detectFeatures", ##' @param param An \code{MSWParam} object containing all settings for ##' the algorithm. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @return For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -##' \code{\link{XCMSnExp}} object with the results of the feature detection. +##' @return For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +##' \code{\link{XCMSnExp}} object with the results of the peak detection. ##' If \code{return.type = "list"} a list of length equal to the number of -##' samples with matrices specifying the identified features/peaks. +##' samples with matrices specifying the identified peaks. ##' If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -##' with the results of the feature detection. +##' with the results of the detection. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature detection. +##' the peak detection. ##' -##' @rdname featureDetection-MSW -setMethod("detectFeatures", +##' @rdname findPeaks-MSW +setMethod("findChromPeaks", signature(object = "OnDiskMSnExp", param = "MSWParam"), function(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") { return.type <- match.arg(return.type, c("XCMSnExp", "list", @@ -473,10 +476,10 @@ setMethod("detectFeatures", ## Restrict to MS1 data. object <- filterMsLevel(object, msLevel. = 1) ## (1) split the object per file. - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(lapply(1:length(fileNames(object)), filterFile, object = object), - FUN = detectFeatures_MSW_OnDiskMSnExp, + FUN = findPeaks_MSW_OnDiskMSnExp, method = "MSW", param = param) ## (3) collect the results. res <- .processResultList(resList, @@ -487,13 +490,13 @@ setMethod("detectFeatures", ## that later, but for now seems reasonable to have it in one, ## since we're calling the method once on all. xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex = 1:length(fileNames(object))) object <- as(object, "XCMSnExp") object@.processHistory <- list(xph) - if (hasAdjustedRtime(object) | hasAlignedFeatures(object)) + if (hasAdjustedRtime(object) | hasFeatures(object)) object@msFeatureData <- new("MsFeatureData") - features(object) <- do.call(rbind, res$peaks) + chromPeaks(object) <- do.call(rbind, res$peaks) if (validObject(object)) return(object) } @@ -514,29 +517,30 @@ setMethod("detectFeatures", } }) -##' @title Single-spectrum non-chromatography MS data feature detection +##' @title Single-spectrum non-chromatography MS data peak detection ##' -##' @description The \code{detectFeatures,MSnExp,MSWParam} method -##' performs feature detection in single-spectrum non-chromatography MS +##' @description The \code{findChromPeaks,MSnExp,MSWParam} method +##' performs peak detection in single-spectrum non-chromatography MS ##' data using functionality from the \code{MassSpecWavelet} package on all ##' samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain ##' mz and intensity values of all spectra hence no additional ##' data input from the original files is required. ##' -##' @rdname featureDetection-MSW -setMethod("detectFeatures", +##' @rdname findPeaks-MSW +setMethod("findChromPeaks", signature(object = "MSnExp", param = "MSWParam"), function(object, param, BPPARAM = bpparam(), return.type = "list") { return.type <- match.arg(return.type, c("list", "xcmsSet")) ms1_idx <- which(unname(msLevel(object)) == 1) if (length(ms1_idx) == 0) - stop("No MS1 spectra available for feature detection!") + stop("No MS1 spectra available for chromatographic peak", + " detection!") spect_list <- split(spectra(object)[ms1_idx], fromFile(object)[ms1_idx]) resList <- bplapply(spect_list, function(z) { - detectFeatures_MSW_Spectrum_list(z, - method = "MSW", - param = param) + findPeaks_MSW_Spectrum_list(z, + method = "MSW", + param = param) }, BPPARAM = BPPARAM) res <- .processResultList(resList, getProcHist = return.type != "list", @@ -558,35 +562,35 @@ setMethod("detectFeatures", } }) -## The centWave with predicted isotope feature detection method for OnDiskMSnExp: -##' @title Two-step centWave feature detection considering also feature isotopes +## The centWave with predicted isotope peak detection method for OnDiskMSnExp: +##' @title Two-step centWave peak detection considering also isotopes ##' -##' @description The \code{detectFeatures,OnDiskMSnExp,CentWavePredIsoParam} method -##' performs a two-step centWave-based feature detection on all samples from an -##' \code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. +##' @description The \code{findChromPeaks,OnDiskMSnExp,CentWavePredIsoParam} method +##' performs a two-step centWave-based chromatographic peak detection on all +##' samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +##' \code{\link[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. ##' ##' @details Parallel processing (one process per sample) is supported and can ##' be configured either by the \code{BPPARAM} parameter or by globally defining ##' the parallel processing mode using the \code{\link[BiocParallel]{register}} ##' method from the \code{BiocParallel} package. ##' -##' @inheritParams featureDetection-centWave +##' @inheritParams findChromPeaks-centWave ##' -##' @return For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -##' \code{\link{XCMSnExp}} object with the results of the feature detection. +##' @return For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +##' \code{\link{XCMSnExp}} object with the results of the peak detection. ##' If \code{return.type = "list"} a list of length equal to the number of -##' samples with matrices specifying the identified features/peaks. +##' samples with matrices specifying the identified peaks. ##' If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -##' with the results of the feature detection. +##' with the results of the peak detection. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature detection. +##' the peak detection. ##' -##' @rdname featureDetection-centWaveWithPredIsoROIs -setMethod("detectFeatures", +##' @rdname findChromPeaks-centWaveWithPredIsoROIs +setMethod("findChromPeaks", signature(object = "OnDiskMSnExp", param = "CentWavePredIsoParam"), function(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") { return.type <- match.arg(return.type, c("XCMSnExp", "list", @@ -599,10 +603,10 @@ setMethod("detectFeatures", warning("Your data appears to be not centroided! CentWave", " works best on data in centroid mode.") ## (1) split the object per file. - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(lapply(1:length(fileNames(object)), filterFile, object = object), - FUN = detectFeatures_OnDiskMSnExp, + FUN = findChromPeaks_OnDiskMSnExp, method = "centWaveWithPredIsoROIs", param = param) ## (3) collect the results. res <- .processResultList(resList, @@ -613,13 +617,13 @@ setMethod("detectFeatures", ## that later, but for now seems reasonable to have it in one, ## since we're calling the method once on all. xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.DETECTION, + type. = .PROCSTEP.PEAK.DETECTION, fileIndex = 1:length(fileNames(object))) object <- as(object, "XCMSnExp") object@.processHistory <- list(xph) - if (hasAdjustedRtime(object) | hasAlignedFeatures(object)) + if (hasAdjustedRtime(object) | hasFeatures(object)) object@msFeatureData <- new("MsFeatureData") - features(object) <- do.call(rbind, res$peaks) + chromPeaks(object) <- do.call(rbind, res$peaks) if (validObject(object)) return(object) } @@ -641,17 +645,17 @@ setMethod("detectFeatures", }) -## The centWave with predicted isotope feature detection method for MSnExp: -##' @title Two-step centWave feature detection considering also feature isotopes +## The centWave with predicted isotope peak detection method for MSnExp: +##' @title Two-step centWave peak detection considering also isotopes ##' -##' @description The \code{detectFeatures,MSnExp,CentWavePredIsoParam} method -##' performs a two-step centWave-based feature detection on all samples from +##' @description The \code{findChromPeaks,MSnExp,CentWavePredIsoParam} method +##' performs a two-step centWave-based peak detection on all samples from ##' an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and ##' intensity values of all spectra hence no additional data input from the ##' original files is required. ##' -##' @rdname featureDetection-centWaveWithPredIsoROIs -setMethod("detectFeatures", +##' @rdname findChromPeaks-centWaveWithPredIsoROIs +setMethod("findChromPeaks", signature(object = "MSnExp", param = "CentWavePredIsoParam"), function(object, param, BPPARAM = bpparam(), return.type = "list") { return.type <- match.arg(return.type, c("list", "xcmsSet")) @@ -663,16 +667,17 @@ setMethod("detectFeatures", ## filterFile is pretty slow on MSnExp. ms1_idx <- which(unname(msLevel(object)) == 1) if (length(ms1_idx) == 0) - stop("No MS1 spectra available for feature detection!") + stop("No MS1 spectra available for chromatographic peak", + " detection!") ## Check if the data is centroided if (!isCentroided(object[[ms1_idx[1]]])) warning("Your data appears to be not centroided! CentWave", " works best on data in centroid mode.") spect_list <- split(spectra(object)[ms1_idx], fromFile(object)[ms1_idx]) - ## (2) use bplapply to do the feature detection. + ## (2) use bplapply to do the peak detection. resList <- bplapply(spect_list, function(z) { - detectFeatures_Spectrum_list(z, + findChromPeaks_Spectrum_list(z, method = "centWaveWithPredIsoROIs", param = param) }, BPPARAM = BPPARAM) @@ -778,3 +783,14 @@ setMethod("adjustRtime", res <- res[featureNames(object)] return(res) }) + + +#' @rdname extractChromatograms-method +#' @noRd +setMethod("extractChromatograms", + signature(object = "OnDiskMSnExp"), + function(object, rt, mz, aggregationFun = "sum") { + return(.extractChromatogram(x = object, rt = rt, mz = mz, + aggregationFun = aggregationFun, + adjusted = FALSE)) + }) diff --git a/R/methods-Params.R b/R/methods-Params.R index 56addf024..531edec32 100644 --- a/R/methods-Params.R +++ b/R/methods-Params.R @@ -25,9 +25,9 @@ setMethod("initialize", "CentWaveParam", function(.Object, ...) { callNextMethod(.Object, ...) }) -## ##' @rdname featureDetection-centWave +## ##' @rdname findChromPeaks-centWave ## setMethod("print", "CentWaveParam", function(x, ...) show(x)) -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("show", "CentWaveParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -49,11 +49,11 @@ setMethod("show", "CentWaveParam", function(object) { ##' @aliases ppm ##' @description \code{ppm},\code{ppm<-}: getter and setter for the \code{ppm} ##' slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("ppm", "CentWaveParam", function(object){ return(object@ppm)}) ##' @aliases ppm<- ##' @param value The value for the slot. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("ppm", "CentWaveParam", function(object, value) { object@ppm <- value if (validObject(object)) @@ -63,11 +63,11 @@ setReplaceMethod("ppm", "CentWaveParam", function(object, value) { ##' @aliases peakwidth ##' @description \code{peakwidth},\code{peakwidth<-}: getter and setter for the ##' \code{peakwidth} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("peakwidth", "CentWaveParam", function(object) return(object@peakwidth)) ##' @aliases peakwidth<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("peakwidth", "CentWaveParam", function(object, value) { object@peakwidth <- value if (validObject(object)) @@ -77,11 +77,11 @@ setReplaceMethod("peakwidth", "CentWaveParam", function(object, value) { ##' @aliases snthresh ##' @description \code{snthresh},\code{snthresh<-}: getter and setter for the ##' \code{snthresh} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("snthresh", "CentWaveParam", function(object) return(object@snthresh)) ##' @aliases snthresh<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("snthresh", "CentWaveParam", function(object, value) { object@snthresh <- value if (validObject(object)) @@ -91,11 +91,11 @@ setReplaceMethod("snthresh", "CentWaveParam", function(object, value) { ##' @aliases prefilter ##' @description \code{prefilter},\code{prefilter<-}: getter and setter for the ##' \code{prefilter} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("prefilter", "CentWaveParam", function(object) return(object@prefilter)) ##' @aliases prefilter<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("prefilter", "CentWaveParam", function(object, value) { object@prefilter <- value if (validObject(object)) @@ -105,11 +105,11 @@ setReplaceMethod("prefilter", "CentWaveParam", function(object, value) { ##' @aliases mzCenterFun ##' @description \code{mzCenterFun},\code{mzCenterFun<-}: getter and setter for the ##' \code{mzCenterFun} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("mzCenterFun", "CentWaveParam", function(object) return(object@mzCenterFun)) ##' @aliases mzCenterFun<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("mzCenterFun", "CentWaveParam", function(object, value) { object@mzCenterFun <- value if (validObject(object)) @@ -120,11 +120,11 @@ setReplaceMethod("mzCenterFun", "CentWaveParam", function(object, value) { ##' \code{integrate} slot of the object. ##' @param f For \code{integrate}: a \code{CentWaveParam} object. ##' -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("integrate", signature(f = "CentWaveParam"), function(f) return(f@integrate)) ##' @aliases integrate<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("integrate", "CentWaveParam", function(object, value) { object@integrate <- as.integer(value) if (validObject(object)) @@ -134,11 +134,11 @@ setReplaceMethod("integrate", "CentWaveParam", function(object, value) { ##' @aliases mzdiff ##' @description \code{mzdiff},\code{mzdiff<-}: getter and setter for the ##' \code{mzdiff} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("mzdiff", "CentWaveParam", function(object) return(object@mzdiff)) ##' @aliases mzdiff<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("mzdiff", "CentWaveParam", function(object, value) { object@mzdiff <- value if (validObject(object)) @@ -148,11 +148,11 @@ setReplaceMethod("mzdiff", "CentWaveParam", function(object, value) { ##' @aliases fitgauss ##' @description \code{fitgauss},\code{fitgauss<-}: getter and setter for the ##' \code{fitgauss} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("fitgauss", "CentWaveParam", function(object) return(object@fitgauss)) ##' @aliases fitgauss<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("fitgauss", "CentWaveParam", function(object, value) { object@fitgauss <- value if (validObject(object)) @@ -162,11 +162,11 @@ setReplaceMethod("fitgauss", "CentWaveParam", function(object, value) { ##' @aliases noise ##' @description \code{noise},\code{noise<-}: getter and setter for the ##' \code{noise} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("noise", "CentWaveParam", function(object) return(object@noise)) ##' @aliases noise<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("noise", "CentWaveParam", function(object, value) { object@noise <- value if (validObject(object)) @@ -176,11 +176,11 @@ setReplaceMethod("noise", "CentWaveParam", function(object, value) { ##' @aliases verboseColumns ##' @description \code{verboseColumns},\code{verboseColumns<-}: getter and ##' setter for the \code{verboseColumns} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("verboseColumns", "CentWaveParam", function(object) return(object@verboseColumns)) ##' @aliases verboseColumns<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("verboseColumns", "CentWaveParam", function(object, value) { object@verboseColumns <- value if (validObject(object)) @@ -190,11 +190,11 @@ setReplaceMethod("verboseColumns", "CentWaveParam", function(object, value) { ##' @aliases roiList ##' @description \code{roiList},\code{roiList<-}: getter and setter for the ##' \code{roiList} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("roiList", "CentWaveParam", function(object) return(object@roiList)) ##' @aliases roiList<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("roiList", "CentWaveParam", function(object, value) { object@roiList <- value if (validObject(object)) @@ -204,11 +204,11 @@ setReplaceMethod("roiList", "CentWaveParam", function(object, value) { ##' @aliases firstBaselineCheck ##' @description \code{fistBaselineCheck},\code{firstBaselineCheck<-}: getter ##' and setter for the \code{firstBaselineCheck} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("firstBaselineCheck", "CentWaveParam", function(object) return(object@firstBaselineCheck)) ##' @aliases firstBaselineCheck<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("firstBaselineCheck", "CentWaveParam", function(object, value) { object@firstBaselineCheck <- value if (validObject(object)) @@ -218,11 +218,11 @@ setReplaceMethod("firstBaselineCheck", "CentWaveParam", function(object, value) ##' @aliases roiScales ##' @description \code{roiScales},\code{roiScales<-}: getter and setter for the ##' \code{roiScales} slot of the object. -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setMethod("roiScales", "CentWaveParam", function(object) return(object@roiScales)) ##' @aliases roiScales<- -##' @rdname featureDetection-centWave +##' @rdname findChromPeaks-centWave setReplaceMethod("roiScales", "CentWaveParam", function(object, value) { object@roiScales <- value if (validObject(object)) @@ -236,7 +236,7 @@ setMethod("initialize", "MatchedFilterParam", function(.Object, ...) { classVersion(.Object)["MatchedFilterParam"] <- "0.0.1" callNextMethod(.Object, ...) }) -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("show", "MatchedFilterParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -256,12 +256,12 @@ setMethod("show", "MatchedFilterParam", function(object) { ##' @aliases binSize ##' @description \code{binSize},\code{binSize<-}: getter and setter for the ##' \code{binSize} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("binSize", "MatchedFilterParam", function(object) return(object@binSize)) ##' @aliases binSize<- ##' @param value The value for the slot. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("binSize", "MatchedFilterParam", function(object, value) { object@binSize <- value if (validObject(object)) @@ -270,11 +270,11 @@ setReplaceMethod("binSize", "MatchedFilterParam", function(object, value) { ##' @description \code{impute},\code{impute<-}: getter and setter for the ##' \code{impute} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("impute", "MatchedFilterParam", function(object) return(object@impute)) ##' @aliases impute<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("impute", "MatchedFilterParam", function(object, value) { object@impute <- value if (validObject(object)) @@ -284,11 +284,11 @@ setReplaceMethod("impute", "MatchedFilterParam", function(object, value) { ##' @aliases baseValue ##' @description \code{baseValue},\code{baseValue<-}: getter and setter for the ##' \code{baseValue} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("baseValue", "MatchedFilterParam", function(object) return(object@baseValue)) ##' @aliases baseValue<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("baseValue", "MatchedFilterParam", function(object, value) { object@baseValue <- value if (validObject(object)) @@ -298,11 +298,11 @@ setReplaceMethod("baseValue", "MatchedFilterParam", function(object, value) { ##' @aliases distance ##' @description \code{distance},\code{distance<-}: getter and setter for the ##' \code{distance} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("distance", "MatchedFilterParam", function(object) return(object@distance)) ##' @aliases distance<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("distance", "MatchedFilterParam", function(object, value) { object@distance <- value if (validObject(object)) @@ -312,11 +312,11 @@ setReplaceMethod("distance", "MatchedFilterParam", function(object, value) { ##' @aliases fwhm ##' @description \code{fwhm},\code{fwhm<-}: getter and setter for the ##' \code{fwhm} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("fwhm", "MatchedFilterParam", function(object) return(object@fwhm)) ##' @aliases fwhm<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("fwhm", "MatchedFilterParam", function(object, value) { object@fwhm <- value if (validObject(object)) @@ -326,11 +326,11 @@ setReplaceMethod("fwhm", "MatchedFilterParam", function(object, value) { ##' @aliases sigma ##' @description \code{sigma},\code{sigma<-}: getter and setter for the ##' \code{sigma} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("sigma", "MatchedFilterParam", function(object) return(object@sigma)) ##' @aliases sigma<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("sigma", "MatchedFilterParam", function(object, value) { object@sigma <- value if (validObject(object)) @@ -340,11 +340,11 @@ setReplaceMethod("sigma", "MatchedFilterParam", function(object, value) { ##' @description \code{max},\code{max<-}: getter and setter for the ##' \code{max} slot of the object. ##' @param x For \code{max}: a \code{MatchedFilterParam} object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("max", signature(x="MatchedFilterParam"), function(x) return(x@max)) ##' @aliases max<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("max", "MatchedFilterParam", function(object, value) { object@max <- value if (validObject(object)) @@ -353,10 +353,10 @@ setReplaceMethod("max", "MatchedFilterParam", function(object, value) { ##' @description \code{snthresh},\code{snthresh<-}: getter and setter for the ##' \code{snthresh} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("snthresh", "MatchedFilterParam", function(object) return(object@snthresh)) -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("snthresh", "MatchedFilterParam", function(object, value) { object@snthresh <- value if (validObject(object)) @@ -366,11 +366,11 @@ setReplaceMethod("snthresh", "MatchedFilterParam", function(object, value) { ##' @aliases steps ##' @description \code{steps},\code{steps<-}: getter and setter for the ##' \code{steps} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("steps", "MatchedFilterParam", function(object) return(object@steps)) ##' @aliases steps<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("steps", "MatchedFilterParam", function(object, value) { object@steps <- value if (validObject(object)) @@ -379,10 +379,10 @@ setReplaceMethod("steps", "MatchedFilterParam", function(object, value) { ##' @description \code{mzdiff},\code{mzdiff<-}: getter and setter for the ##' \code{mzdiff} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("mzdiff", "MatchedFilterParam", function(object) return(object@mzdiff)) -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("mzdiff", "MatchedFilterParam", function(object, value) { object@mzdiff <- value if (validObject(object)) @@ -392,11 +392,11 @@ setReplaceMethod("mzdiff", "MatchedFilterParam", function(object, value) { ##' @aliases index ##' @description \code{index},\code{index<-}: getter and setter for the ##' \code{index} slot of the object. -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setMethod("index", "MatchedFilterParam", function(object) return(object@index)) ##' @aliases index<- -##' @rdname featureDetection-matchedFilter +##' @rdname findChromPeaks-matchedFilter setReplaceMethod("index", "MatchedFilterParam", function(object, value) { object@index <- value if (validObject(object)) @@ -411,7 +411,7 @@ setMethod("initialize", "MassifquantParam", function(.Object, ...) { callNextMethod(.Object, ...) }) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("show", "MassifquantParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -434,10 +434,10 @@ setMethod("show", "MassifquantParam", function(object) { ##' @description \code{ppm},\code{ppm<-}: getter and setter for the \code{ppm} ##' slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("ppm", "MassifquantParam", function(object){ return(object@ppm)}) ##' @param value The value for the slot. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("ppm", "MassifquantParam", function(object, value) { object@ppm <- value if (validObject(object)) @@ -446,10 +446,10 @@ setReplaceMethod("ppm", "MassifquantParam", function(object, value) { ##' @description \code{peakwidth},\code{peakwidth<-}: getter and setter for the ##' \code{peakwidth} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("peakwidth", "MassifquantParam", function(object) return(object@peakwidth)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("peakwidth", "MassifquantParam", function(object, value) { object@peakwidth <- value if (validObject(object)) @@ -458,10 +458,10 @@ setReplaceMethod("peakwidth", "MassifquantParam", function(object, value) { ##' @description \code{snthresh},\code{snthresh<-}: getter and setter for the ##' \code{snthresh} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("snthresh", "MassifquantParam", function(object) return(object@snthresh)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("snthresh", "MassifquantParam", function(object, value) { object@snthresh <- value if (validObject(object)) @@ -470,10 +470,10 @@ setReplaceMethod("snthresh", "MassifquantParam", function(object, value) { ##' @description \code{prefilter},\code{prefilter<-}: getter and setter for the ##' \code{prefilter} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("prefilter", "MassifquantParam", function(object) return(object@prefilter)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("prefilter", "MassifquantParam", function(object, value) { object@prefilter <- value if (validObject(object)) @@ -482,10 +482,10 @@ setReplaceMethod("prefilter", "MassifquantParam", function(object, value) { ##' @description \code{mzCenterFun},\code{mzCenterFun<-}: getter and setter for the ##' \code{mzCenterFun} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("mzCenterFun", "MassifquantParam", function(object) return(object@mzCenterFun)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("mzCenterFun", "MassifquantParam", function(object, value) { object@mzCenterFun <- value if (validObject(object)) @@ -496,10 +496,10 @@ setReplaceMethod("mzCenterFun", "MassifquantParam", function(object, value) { ##' \code{integrate} slot of the object. ##' @param f For \code{integrate}: a \code{MassifquantParam} object. ##' -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("integrate", signature(f = "MassifquantParam"), function(f) return(f@integrate)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("integrate", "MassifquantParam", function(object, value) { object@integrate <- as.integer(value) if (validObject(object)) @@ -508,10 +508,10 @@ setReplaceMethod("integrate", "MassifquantParam", function(object, value) { ##' @description \code{mzdiff},\code{mzdiff<-}: getter and setter for the ##' \code{mzdiff} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("mzdiff", "MassifquantParam", function(object) return(object@mzdiff)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("mzdiff", "MassifquantParam", function(object, value) { object@mzdiff <- value if (validObject(object)) @@ -520,10 +520,10 @@ setReplaceMethod("mzdiff", "MassifquantParam", function(object, value) { ##' @description \code{fitgauss},\code{fitgauss<-}: getter and setter for the ##' \code{fitgauss} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("fitgauss", "MassifquantParam", function(object) return(object@fitgauss)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("fitgauss", "MassifquantParam", function(object, value) { object@fitgauss <- value if (validObject(object)) @@ -532,10 +532,10 @@ setReplaceMethod("fitgauss", "MassifquantParam", function(object, value) { ##' @description \code{noise},\code{noise<-}: getter and setter for the ##' \code{noise} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("noise", "MassifquantParam", function(object) return(object@noise)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("noise", "MassifquantParam", function(object, value) { object@noise <- value if (validObject(object)) @@ -544,10 +544,10 @@ setReplaceMethod("noise", "MassifquantParam", function(object, value) { ##' @description \code{verboseColumns},\code{verboseColumns<-}: getter and ##' setter for the \code{verboseColumns} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("verboseColumns", "MassifquantParam", function(object) return(object@verboseColumns)) -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("verboseColumns", "MassifquantParam", function(object, value) { object@verboseColumns <- value if (validObject(object)) @@ -557,11 +557,11 @@ setReplaceMethod("verboseColumns", "MassifquantParam", function(object, value) { ##' @aliases criticalValue ##' @description \code{criticalValue},\code{criticalValue<-}: getter and ##' setter for the \code{criticalValue} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("criticalValue", "MassifquantParam", function(object) return(object@criticalValue)) ##' @aliases criticalValue<- -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("criticalValue", "MassifquantParam", function(object, value) { object@criticalValue <- value if (validObject(object)) @@ -571,11 +571,11 @@ setReplaceMethod("criticalValue", "MassifquantParam", function(object, value) { ##' @aliases consecMissedLimit ##' @description \code{consecMissedLimit},\code{consecMissedLimit<-}: getter and ##' setter for the \code{consecMissedLimit} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("consecMissedLimit", "MassifquantParam", function(object) return(object@consecMissedLimit)) ##' @aliases consecMissedLimit<- -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("consecMissedLimit", "MassifquantParam", function(object, value) { object@consecMissedLimit <- as.integer(value) @@ -586,11 +586,11 @@ setReplaceMethod("consecMissedLimit", "MassifquantParam", ##' @aliases unions ##' @description \code{unions},\code{unions<-}: getter and ##' setter for the \code{unions} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("unions", "MassifquantParam", function(object) return(object@unions)) ##' @aliases unions<- -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("unions", "MassifquantParam", function(object, value) { object@unions <- as.integer(value) if (validObject(object)) @@ -600,11 +600,11 @@ setReplaceMethod("unions", "MassifquantParam", function(object, value) { ##' @aliases checkBack ##' @description \code{checkBack},\code{checkBack<-}: getter and ##' setter for the \code{checkBack} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("checkBack", "MassifquantParam", function(object) return(object@checkBack)) ##' @aliases checkBack<- -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("checkBack", "MassifquantParam", function(object, value) { object@checkBack <- as.integer(value) if (validObject(object)) @@ -614,11 +614,11 @@ setReplaceMethod("checkBack", "MassifquantParam", function(object, value) { ##' @aliases withWave ##' @description \code{withWave},\code{withWave<-}: getter and ##' setter for the \code{withWave} slot of the object. -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setMethod("withWave", "MassifquantParam", function(object) return(object@withWave)) ##' @aliases withWave<- -##' @rdname featureDetection-massifquant +##' @rdname findChromPeaks-massifquant setReplaceMethod("withWave", "MassifquantParam", function(object, value) { object@withWave <- value if (validObject(object)) @@ -634,7 +634,7 @@ setMethod("initialize", "MSWParam", function(.Object, ...) { callNextMethod(.Object, ...) }) -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("show", "MSWParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -659,10 +659,10 @@ setMethod("show", "MSWParam", function(object) { ##' @description \code{snthresh},\code{snthresh<-}: getter and setter for the ##' \code{snthresh} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("snthresh", "MSWParam", function(object){ return(object@snthresh)}) ##' @param value The value for the slot. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("snthresh", "MSWParam", function(object, value) { object@snthresh <- value if (validObject(object)) @@ -671,10 +671,10 @@ setReplaceMethod("snthresh", "MSWParam", function(object, value) { ##' @description \code{verboseColumns},\code{verboseColumns<-}: getter and setter ##' for the \code{verboseColumns} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("verboseColumns", "MSWParam", function(object){ return(object@verboseColumns)}) -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("verboseColumns", "MSWParam", function(object, value) { object@verboseColumns <- value if (validObject(object)) @@ -684,10 +684,10 @@ setReplaceMethod("verboseColumns", "MSWParam", function(object, value) { ##' @aliases scales ##' @description \code{scales},\code{scales<-}: getter and setter for the ##' \code{scales} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("scales", "MSWParam", function(object){ return(object@scales)}) ##' @aliases scales<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("scales", "MSWParam", function(object, value) { object@scales <- value if (validObject(object)) @@ -697,10 +697,10 @@ setReplaceMethod("scales", "MSWParam", function(object, value) { ##' @aliases nearbyPeak ##' @description \code{nearbyPeak},\code{nearbyPeak<-}: getter and setter for the ##' \code{nearbyPeak} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("nearbyPeak", "MSWParam", function(object){ return(object@nearbyPeak)}) ##' @aliases nearbyPeak<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("nearbyPeak", "MSWParam", function(object, value) { object@nearbyPeak <- value if (validObject(object)) @@ -710,11 +710,11 @@ setReplaceMethod("nearbyPeak", "MSWParam", function(object, value) { ##' @aliases peakScaleRange ##' @description \code{peakScaleRange},\code{peakScaleRange<-}: getter and setter ##' for the \code{peakScaleRange} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("peakScaleRange", "MSWParam", function(object){ return(object@peakScaleRange)}) ##' @aliases peakScaleRange<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("peakScaleRange", "MSWParam", function(object, value) { object@peakScaleRange <- value if (validObject(object)) @@ -724,10 +724,10 @@ setReplaceMethod("peakScaleRange", "MSWParam", function(object, value) { ##' @aliases ampTh ##' @description \code{ampTh},\code{ampTh<-}: getter and setter for the ##' \code{ampTh} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("ampTh", "MSWParam", function(object){ return(object@ampTh)}) ##' @aliases ampTh<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("ampTh", "MSWParam", function(object, value) { object@ampTh <- value if (validObject(object)) @@ -737,11 +737,11 @@ setReplaceMethod("ampTh", "MSWParam", function(object, value) { ##' @aliases minNoiseLevel ##' @description \code{minNoiseLevel},\code{minNoiseLevel<-}: getter and setter ##' for the \code{minNoiseLevel} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("minNoiseLevel", "MSWParam", function(object){ return(object@minNoiseLevel)}) ##' @aliases minNoiseLevel<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("minNoiseLevel", "MSWParam", function(object, value) { object@minNoiseLevel <- value if (validObject(object)) @@ -751,11 +751,11 @@ setReplaceMethod("minNoiseLevel", "MSWParam", function(object, value) { ##' @aliases ridgeLength ##' @description \code{ridgeLength},\code{ridgeLength<-}: getter and setter for ##' the \code{ridgeLength} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("ridgeLength", "MSWParam", function(object){ return(object@ridgeLength)}) ##' @aliases ridgeLength<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("ridgeLength", "MSWParam", function(object, value) { object@ridgeLength <- value if (validObject(object)) @@ -765,10 +765,10 @@ setReplaceMethod("ridgeLength", "MSWParam", function(object, value) { ##' @aliases peakThr ##' @description \code{peakThr},\code{peakThr<-}: getter and setter for the ##' \code{peakThr} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("peakThr", "MSWParam", function(object){ return(object@peakThr)}) ##' @aliases peakThr<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("peakThr", "MSWParam", function(object, value) { object@peakThr <- value if (validObject(object)) @@ -778,10 +778,10 @@ setReplaceMethod("peakThr", "MSWParam", function(object, value) { ##' @aliases tuneIn ##' @description \code{tuneIn},\code{tuneIn<-}: getter and setter for the ##' \code{tuneIn} slot of the object. -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("tuneIn", "MSWParam", function(object){ return(object@tuneIn)}) ##' @aliases tuneIn<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("tuneIn", "MSWParam", function(object, value) { object@tuneIn <- value if (validObject(object)) @@ -796,10 +796,10 @@ setReplaceMethod("tuneIn", "MSWParam", function(object, value) { ##' \code{\link[MassSpecWavelet]{sav.gol}} functions from the ##' \code{MassSpecWavelet} package. ##' -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setMethod("addParams", "MSWParam", function(object){ return(object@addParams)}) ##' @aliases addParams<- -##' @rdname featureDetection-MSW +##' @rdname findPeaks-MSW setReplaceMethod("addParams", "MSWParam", function(object, value) { object@addParams <- value if (validObject(object)) @@ -829,7 +829,7 @@ setMethod("initialize", "CentWavePredIsoParam", function(.Object, ...) { callNextMethod(.Object, ...) }) -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("show", "CentWavePredIsoParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -856,11 +856,11 @@ setMethod("show", "CentWavePredIsoParam", function(object) { ##' @aliases snthreshIsoROIs ##' @description \code{snthreshIsoROIs},\code{snthreshIsoROIs<-}: getter and ##' setter for the \code{snthreshIsoROIs} slot of the object. -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("snthreshIsoROIs", "CentWavePredIsoParam", function(object){ return(object@snthreshIsoROIs)}) ##' @aliases snthreshIsoROIs<- -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setReplaceMethod("snthreshIsoROIs", "CentWavePredIsoParam", function(object, value) { object@snthreshIsoROIs <- value if (validObject(object)) @@ -870,11 +870,11 @@ setReplaceMethod("snthreshIsoROIs", "CentWavePredIsoParam", function(object, val ##' @aliases maxCharge ##' @description \code{maxCharge},\code{maxCharge<-}: getter and ##' setter for the \code{maxCharge} slot of the object. -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("maxCharge", "CentWavePredIsoParam", function(object){ return(object@maxCharge)}) ##' @aliases maxCharge<- -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setReplaceMethod("maxCharge", "CentWavePredIsoParam", function(object, value) { object@maxCharge <- as.integer(value) if (validObject(object)) @@ -884,11 +884,11 @@ setReplaceMethod("maxCharge", "CentWavePredIsoParam", function(object, value) { ##' @aliases maxIso ##' @description \code{maxIso},\code{maxIso<-}: getter and ##' setter for the \code{maxIso} slot of the object. -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("maxIso", "CentWavePredIsoParam", function(object){ return(object@maxIso)}) ##' @aliases maxIso<- -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setReplaceMethod("maxIso", "CentWavePredIsoParam", function(object, value) { object@maxIso <- as.integer(value) if (validObject(object)) @@ -898,11 +898,11 @@ setReplaceMethod("maxIso", "CentWavePredIsoParam", function(object, value) { ##' @aliases mzIntervalExtension ##' @description \code{mzIntervalExtension},\code{mzIntervalExtension<-}: getter ##' and setter for the \code{mzIntervalExtension} slot of the object. -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("mzIntervalExtension", "CentWavePredIsoParam", function(object){ return(object@mzIntervalExtension)}) ##' @aliases mzIntervalExtension<- -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setReplaceMethod("mzIntervalExtension", "CentWavePredIsoParam", function(object, value) { object@mzIntervalExtension <- value @@ -912,11 +912,11 @@ setReplaceMethod("mzIntervalExtension", "CentWavePredIsoParam", ##' @description \code{polarity},\code{polarity<-}: getter and ##' setter for the \code{polarity} slot of the object. -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setMethod("polarity", "CentWavePredIsoParam", function(object){ return(object@polarity)}) ##' @aliases polarity<- -##' @rdname featureDetection-centWaveWithPredIsoROIs +##' @rdname findChromPeaks-centWaveWithPredIsoROIs setReplaceMethod("polarity", "CentWavePredIsoParam", function(object, value) { object@polarity <- value if (validObject(object)) @@ -925,16 +925,16 @@ setReplaceMethod("polarity", "CentWavePredIsoParam", function(object, value) { ############################################################ -## FeatureDensityParam -setMethod("initialize", "FeatureDensityParam", function(.Object, ...) { - classVersion(.Object)["FeatureDensityParam"] <- "0.0.1" +## PeakDensityParam +setMethod("initialize", "PeakDensityParam", function(.Object, ...) { + classVersion(.Object)["PeakDensityParam"] <- "0.0.1" callNextMethod(.Object, ...) }) -## ##' @rdname groupFeatures-density +## ##' @rdname groupChromPeaks-density ## setMethod("print", "CentWaveParam", function(x, ...) show(x)) -##' @rdname groupFeatures-density -setMethod("show", "FeatureDensityParam", function(object) { +##' @rdname groupChromPeaks-density +setMethod("show", "PeakDensityParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") cat(" sampleGroups:", class(object@sampleGroups), "of length", @@ -949,13 +949,13 @@ setMethod("show", "FeatureDensityParam", function(object) { ##' @aliases sampleGroups ##' @description \code{sampleGroups},\code{sampleGroups<-}: getter and setter ##' for the \code{sampleGroups} slot of the object. -##' @rdname groupFeatures-density -setMethod("sampleGroups", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("sampleGroups", "PeakDensityParam", function(object){ return(object@sampleGroups)}) ##' @aliases sampleGroups<- ##' @param value The value for the slot. -##' @rdname groupFeatures-density -setReplaceMethod("sampleGroups", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("sampleGroups", "PeakDensityParam", function(object, value) { object@sampleGroups <- value if (validObject(object)) return(object) @@ -964,12 +964,12 @@ setReplaceMethod("sampleGroups", "FeatureDensityParam", function(object, value) ##' @aliases bw ##' @description \code{bw},\code{bw<-}: getter and setter for the \code{bw} slot ##' of the object. -##' @rdname groupFeatures-density -setMethod("bw", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("bw", "PeakDensityParam", function(object){ return(object@bw)}) ##' @aliases bw<- -##' @rdname groupFeatures-density -setReplaceMethod("bw", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("bw", "PeakDensityParam", function(object, value) { object@bw <- value if (validObject(object)) return(object) @@ -978,12 +978,12 @@ setReplaceMethod("bw", "FeatureDensityParam", function(object, value) { ##' @aliases minFraction ##' @description \code{minFraction},\code{minFraction<-}: getter and setter for ##' the \code{minFraction} slot of the object. -##' @rdname groupFeatures-density -setMethod("minFraction", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("minFraction", "PeakDensityParam", function(object){ return(object@minFraction)}) ##' @aliases minFraction<- -##' @rdname groupFeatures-density -setReplaceMethod("minFraction", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("minFraction", "PeakDensityParam", function(object, value) { object@minFraction <- value if (validObject(object)) return(object) @@ -992,12 +992,12 @@ setReplaceMethod("minFraction", "FeatureDensityParam", function(object, value) { ##' @aliases minSamples ##' @description \code{minSamples},\code{minSamples<-}: getter and setter for the ##' \code{minSamples} slot of the object. -##' @rdname groupFeatures-density -setMethod("minSamples", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("minSamples", "PeakDensityParam", function(object){ return(object@minSamples)}) ##' @aliases minSamples<- -##' @rdname groupFeatures-density -setReplaceMethod("minSamples", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("minSamples", "PeakDensityParam", function(object, value) { object@minSamples <- value if (validObject(object)) return(object) @@ -1005,11 +1005,11 @@ setReplaceMethod("minSamples", "FeatureDensityParam", function(object, value) { ##' @description \code{binSize},\code{binSize<-}: getter and setter for the ##' \code{binSize} slot of the object. -##' @rdname groupFeatures-density -setMethod("binSize", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("binSize", "PeakDensityParam", function(object){ return(object@binSize)}) -##' @rdname groupFeatures-density -setReplaceMethod("binSize", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("binSize", "PeakDensityParam", function(object, value) { object@binSize <- value if (validObject(object)) return(object) @@ -1018,12 +1018,12 @@ setReplaceMethod("binSize", "FeatureDensityParam", function(object, value) { ##' @aliases maxFeatures ##' @description \code{maxFeatures},\code{maxFeatures<-}: getter and setter for ##' the \code{maxFeatures} slot of the object. -##' @rdname groupFeatures-density -setMethod("maxFeatures", "FeatureDensityParam", function(object){ +##' @rdname groupChromPeaks-density +setMethod("maxFeatures", "PeakDensityParam", function(object){ return(object@maxFeatures)}) ##' @aliases maxFeatures<- -##' @rdname groupFeatures-density -setReplaceMethod("maxFeatures", "FeatureDensityParam", function(object, value) { +##' @rdname groupChromPeaks-density +setReplaceMethod("maxFeatures", "PeakDensityParam", function(object, value) { object@maxFeatures <- value if (validObject(object)) return(object) @@ -1037,9 +1037,9 @@ setMethod("initialize", "MzClustParam", function(.Object, ...) { callNextMethod(.Object, ...) }) -## ##' @rdname groupFeatures-mzClust +## ##' @rdname groupChromPeaks-mzClust ## setMethod("print", "CentWaveParam", function(x, ...) show(x)) -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("show", "MzClustParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") @@ -1053,11 +1053,11 @@ setMethod("show", "MzClustParam", function(object) { ##' @description \code{sampleGroups},\code{sampleGroups<-}: getter and setter ##' for the \code{sampleGroups} slot of the object. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("sampleGroups", "MzClustParam", function(object){ return(object@sampleGroups)}) ##' @param value The value for the slot. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setReplaceMethod("sampleGroups", "MzClustParam", function(object, value) { object@sampleGroups <- value if (validObject(object)) @@ -1066,10 +1066,10 @@ setReplaceMethod("sampleGroups", "MzClustParam", function(object, value) { ##' @description \code{ppm},\code{ppm<-}: getter and setter for the \code{ppm} ##' slot of the object. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("ppm", "MzClustParam", function(object){ return(object@ppm)}) -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setReplaceMethod("ppm", "MzClustParam", function(object, value) { object@ppm <- value if (validObject(object)) @@ -1079,11 +1079,11 @@ setReplaceMethod("ppm", "MzClustParam", function(object, value) { ##' @aliases absMz ##' @description \code{absMz},\code{absMz<-}: getter and setter for the ##' \code{absMz} slot of the object. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("absMz", "MzClustParam", function(object){ return(object@absMz)}) ##' @aliases absMz<- -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setReplaceMethod("absMz", "MzClustParam", function(object, value) { object@absMz <- value if (validObject(object)) @@ -1092,10 +1092,10 @@ setReplaceMethod("absMz", "MzClustParam", function(object, value) { ##' @description \code{minFraction},\code{minFraction<-}: getter and setter for ##' the \code{minFraction} slot of the object. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("minFraction", "MzClustParam", function(object){ return(object@minFraction)}) -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setReplaceMethod("minFraction", "MzClustParam", function(object, value) { object@minFraction <- value if (validObject(object)) @@ -1104,10 +1104,10 @@ setReplaceMethod("minFraction", "MzClustParam", function(object, value) { ##' @description \code{minSamples},\code{minSamples<-}: getter and setter for the ##' \code{minSamples} slot of the object. -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setMethod("minSamples", "MzClustParam", function(object){ return(object@minSamples)}) -##' @rdname groupFeatures-mzClust +##' @rdname groupChromPeaks-mzClust setReplaceMethod("minSamples", "MzClustParam", function(object, value) { object@minSamples <- value if (validObject(object)) @@ -1116,14 +1116,14 @@ setReplaceMethod("minSamples", "MzClustParam", function(object, value) { ############################################################ -## NearestFeaturesParam -setMethod("initialize", "NearestFeaturesParam", function(.Object, ...) { - classVersion(.Object)["NearestFeaturesParam"] <- "0.0.1" +## NearestPeaksParam +setMethod("initialize", "NearestPeaksParam", function(.Object, ...) { + classVersion(.Object)["NearestPeaksParam"] <- "0.0.1" callNextMethod(.Object, ...) }) -##' @rdname groupFeatures-nearest -setMethod("show", "NearestFeaturesParam", function(object) { +##' @rdname groupChromPeaks-nearest +setMethod("show", "NearestPeaksParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") cat(" sampleGroups:", class(object@sampleGroups), "of length", @@ -1136,12 +1136,12 @@ setMethod("show", "NearestFeaturesParam", function(object) { ##' @description \code{sampleGroups},\code{sampleGroups<-}: getter and setter ##' for the \code{sampleGroups} slot of the object. -##' @rdname groupFeatures-nearest -setMethod("sampleGroups", "NearestFeaturesParam", function(object){ +##' @rdname groupChromPeaks-nearest +setMethod("sampleGroups", "NearestPeaksParam", function(object){ return(object@sampleGroups)}) ##' @param value The value for the slot. -##' @rdname groupFeatures-nearest -setReplaceMethod("sampleGroups", "NearestFeaturesParam", function(object, value) { +##' @rdname groupChromPeaks-nearest +setReplaceMethod("sampleGroups", "NearestPeaksParam", function(object, value) { object@sampleGroups <- value if (validObject(object)) return(object) @@ -1150,12 +1150,12 @@ setReplaceMethod("sampleGroups", "NearestFeaturesParam", function(object, value) ##' @aliases mzVsRtBalance ##' @description \code{mzVsRtBalance},\code{mzVsRtBalance<-}: getter and setter ##' for the \code{mzVsRtBalance} slot of the object. -##' @rdname groupFeatures-nearest -setMethod("mzVsRtBalance", "NearestFeaturesParam", function(object){ +##' @rdname groupChromPeaks-nearest +setMethod("mzVsRtBalance", "NearestPeaksParam", function(object){ return(object@mzVsRtBalance)}) ##' @aliases mzVsRtBalance<- -##' @rdname groupFeatures-nearest -setReplaceMethod("mzVsRtBalance", "NearestFeaturesParam", function(object, value) { +##' @rdname groupChromPeaks-nearest +setReplaceMethod("mzVsRtBalance", "NearestPeaksParam", function(object, value) { object@mzVsRtBalance <- value if (validObject(object)) return(object) @@ -1163,11 +1163,11 @@ setReplaceMethod("mzVsRtBalance", "NearestFeaturesParam", function(object, value ##' @description \code{absMz},\code{absMz<-}: getter and setter for the ##' \code{absMz} slot of the object. -##' @rdname groupFeatures-nearest -setMethod("absMz", "NearestFeaturesParam", function(object){ +##' @rdname groupChromPeaks-nearest +setMethod("absMz", "NearestPeaksParam", function(object){ return(object@absMz)}) -##' @rdname groupFeatures-nearest -setReplaceMethod("absMz", "NearestFeaturesParam", function(object, value) { +##' @rdname groupChromPeaks-nearest +setReplaceMethod("absMz", "NearestPeaksParam", function(object, value) { object@absMz <- value if (validObject(object)) return(object) @@ -1176,12 +1176,12 @@ setReplaceMethod("absMz", "NearestFeaturesParam", function(object, value) { ##' @aliases absRt ##' @description \code{absRt},\code{absRt<-}: getter and setter for the ##' \code{absRt} slot of the object. -##' @rdname groupFeatures-nearest -setMethod("absRt", "NearestFeaturesParam", function(object){ +##' @rdname groupChromPeaks-nearest +setMethod("absRt", "NearestPeaksParam", function(object){ return(object@absRt)}) ##' @aliases absRt<- -##' @rdname groupFeatures-nearest -setReplaceMethod("absRt", "NearestFeaturesParam", function(object, value) { +##' @rdname groupChromPeaks-nearest +setReplaceMethod("absRt", "NearestPeaksParam", function(object, value) { object@absRt <- value if (validObject(object)) return(object) @@ -1190,12 +1190,12 @@ setReplaceMethod("absRt", "NearestFeaturesParam", function(object, value) { ##' @aliases kNN ##' @description \code{kNN},\code{kNN<-}: getter and setter for the ##' \code{kNN} slot of the object. -##' @rdname groupFeatures-nearest -setMethod("kNN", "NearestFeaturesParam", function(object){ +##' @rdname groupChromPeaks-nearest +setMethod("kNN", "NearestPeaksParam", function(object){ return(object@kNN)}) ##' @aliases kNN<- -##' @rdname groupFeatures-nearest -setReplaceMethod("kNN", "NearestFeaturesParam", function(object, value) { +##' @rdname groupChromPeaks-nearest +setReplaceMethod("kNN", "NearestPeaksParam", function(object, value) { object@kNN <- value if (validObject(object)) return(object) @@ -1203,18 +1203,18 @@ setReplaceMethod("kNN", "NearestFeaturesParam", function(object, value) { ############################################################ -## FeatureGroupsParam -setMethod("initialize", "FeatureGroupsParam", function(.Object, ...) { - classVersion(.Object)["FeatureGroupsParam"] <- "0.0.1" +## PeakGroupsParam +setMethod("initialize", "PeakGroupsParam", function(.Object, ...) { + classVersion(.Object)["PeakGroupsParam"] <- "0.0.1" callNextMethod(.Object, ...) }) -##' @rdname adjustRtime-featureGroups -setMethod("show", "FeatureGroupsParam", function(object) { +##' @rdname adjustRtime-peakGroups +setMethod("show", "PeakGroupsParam", function(object) { cat("Object of class: ", class(object), "\n") cat("Parameters:\n") cat(" minFraction:", object@minFraction, "\n") - cat(" extraFeatures:", object@extraFeatures, "\n") + cat(" extraPeaks:", object@extraPeaks, "\n") cat(" smooth:", object@smooth, "\n") cat(" span:", object@span, "\n") cat(" family:", object@family, "\n") @@ -1222,27 +1222,27 @@ setMethod("show", "FeatureGroupsParam", function(object) { ##' @description \code{minFraction},\code{minFraction<-}: getter and setter ##' for the \code{minFraction} slot of the object. -##' @rdname adjustRtime-featureGroups -setMethod("minFraction", "FeatureGroupsParam", function(object){ +##' @rdname adjustRtime-peakGroups +setMethod("minFraction", "PeakGroupsParam", function(object){ return(object@minFraction)}) ##' @param value The value for the slot. -##' @rdname adjustRtime-featureGroups -setReplaceMethod("minFraction", "FeatureGroupsParam", function(object, value) { +##' @rdname adjustRtime-peakGroups +setReplaceMethod("minFraction", "PeakGroupsParam", function(object, value) { object@minFraction <- value if (validObject(object)) return(object) }) -##' @aliases extraFeatures -##' @description \code{extraFeatures},\code{extraFeatures<-}: getter and setter -##' for the \code{extraFeatures} slot of the object. -##' @rdname adjustRtime-featureGroups -setMethod("extraFeatures", "FeatureGroupsParam", function(object){ - return(object@extraFeatures)}) -##' @aliases extraFeatures<- -##' @rdname adjustRtime-featureGroups -setReplaceMethod("extraFeatures", "FeatureGroupsParam", function(object, value) { - object@extraFeatures <- value +##' @aliases extraPeaks +##' @description \code{extraPeaks},\code{extraPeaks<-}: getter and setter +##' for the \code{extraPeaks} slot of the object. +##' @rdname adjustRtime-peakGroups +setMethod("extraPeaks", "PeakGroupsParam", function(object){ + return(object@extraPeaks)}) +##' @aliases extraPeaks<- +##' @rdname adjustRtime-peakGroups +setReplaceMethod("extraPeaks", "PeakGroupsParam", function(object, value) { + object@extraPeaks <- value if (validObject(object)) return(object) }) @@ -1250,13 +1250,13 @@ setReplaceMethod("extraFeatures", "FeatureGroupsParam", function(object, value) ##' @aliases smooth ##' @description \code{smooth},\code{smooth<-}: getter and setter ##' for the \code{smooth} slot of the object. -##' @param x a \code{FeatureGroupsParam} object. -##' @rdname adjustRtime-featureGroups -setMethod("smooth", "FeatureGroupsParam", function(x){ +##' @param x a \code{PeakGroupsParam} object. +##' @rdname adjustRtime-peakGroups +setMethod("smooth", "PeakGroupsParam", function(x){ return(x@smooth)}) ##' @aliases smooth<- -##' @rdname adjustRtime-featureGroups -setReplaceMethod("smooth", "FeatureGroupsParam", function(object, value) { +##' @rdname adjustRtime-peakGroups +setReplaceMethod("smooth", "PeakGroupsParam", function(object, value) { object@smooth <- value if (validObject(object)) return(object) @@ -1265,12 +1265,12 @@ setReplaceMethod("smooth", "FeatureGroupsParam", function(object, value) { ##' @aliases span ##' @description \code{span},\code{span<-}: getter and setter ##' for the \code{span} slot of the object. -##' @rdname adjustRtime-featureGroups -setMethod("span", "FeatureGroupsParam", function(object){ +##' @rdname adjustRtime-peakGroups +setMethod("span", "PeakGroupsParam", function(object){ return(object@span)}) ##' @aliases span<- -##' @rdname adjustRtime-featureGroups -setReplaceMethod("span", "FeatureGroupsParam", function(object, value) { +##' @rdname adjustRtime-peakGroups +setReplaceMethod("span", "PeakGroupsParam", function(object, value) { object@span <- value if (validObject(object)) return(object) @@ -1279,12 +1279,12 @@ setReplaceMethod("span", "FeatureGroupsParam", function(object, value) { ##' @aliases family ##' @description \code{family},\code{family<-}: getter and setter ##' for the \code{family} slot of the object. -##' @rdname adjustRtime-featureGroups -setMethod("family", "FeatureGroupsParam", function(object){ +##' @rdname adjustRtime-peakGroups +setMethod("family", "PeakGroupsParam", function(object){ return(object@family)}) ##' @aliases family<- -##' @rdname adjustRtime-featureGroups -setReplaceMethod("family", "FeatureGroupsParam", function(object, value) { +##' @rdname adjustRtime-peakGroups +setReplaceMethod("family", "PeakGroupsParam", function(object, value) { object@family <- value if (validObject(object)) return(object) diff --git a/R/methods-XCMSnExp.R b/R/methods-XCMSnExp.R index cab6f1e2b..f2325c6ba 100644 --- a/R/methods-XCMSnExp.R +++ b/R/methods-XCMSnExp.R @@ -1,6 +1,6 @@ ## Methods for the XCMSnExp object representing untargeted metabolomics ## results -#' @include functions-XCMSnExp.R do_groupFeatures-functions.R +#' @include functions-XCMSnExp.R do_groupChromPeaks-functions.R #' do_adjustRtime-functions.R methods-xcmsRaw.R functions-OnDiskMSnExp.R setMethod("initialize", "XCMSnExp", function(.Object, ...) { @@ -15,25 +15,25 @@ setMethod("show", "XCMSnExp", function(object) { callNextMethod() ## And not XCMSnExp related stuff. cat("- - - xcms preprocessing - - -\n") - if (hasDetectedFeatures(object)) { - cat("Feature detection:\n") - cat(" ", nrow(features(object)), " features identified in ", + if (hasChromPeaks(object)) { + cat("Chromatographic peak detection:\n") + cat(" ", nrow(chromPeaks(object)), " peaks identified in ", length(fileNames(object)), " samples.\n", sep = "") cat(" On average ", - format(mean(table(features(object)[, "sample"])), digits = 3), - " features per sample.\n", sep = "") + format(mean(table(chromPeaks(object)[, "sample"])), digits = 3), + " chromatographic peaks per sample.\n", sep = "") } - if (hasAlignedFeatures(object)) { - cat("Feature alignment:\n") - cat(" ", nrow(featureGroups(object)), " featureGroups identified.\n", + if (hasFeatures(object)) { + cat("Correspondence:\n") + cat(" ", nrow(featureDefinitions(object)), " features identified.\n", sep = "") - cat(" Median mz range of feature groups: ", - format(median(featureGroups(object)[, "mzmax"] - - featureGroups(object)[, "mzmin"]), digits = 5), + cat(" Median mz range of features: ", + format(median(featureDefinitions(object)[, "mzmax"] - + featureDefinitions(object)[, "mzmin"]), digits = 5), "\n", sep = "") - cat(" Median rt range of feature groups: ", - format(median(featureGroups(object)[, "rtmax"] - - featureGroups(object)[, "rtmin"]), digits = 5), + cat(" Median rt range of features: ", + format(median(featureDefinitions(object)[, "rtmax"] - + featureDefinitions(object)[, "rtmin"]), digits = 5), "\n", sep = "") } if (hasAdjustedRtime(object)) { @@ -50,24 +50,24 @@ setMethod("hasAdjustedRtime", "XCMSnExp", function(object) { return(hasAdjustedRtime(object@msFeatureData)) }) -##' @aliases hasAlignedFeatures +##' @aliases hasFeatures ##' -##' @description \code{hasAlignedFeatures}: whether the object contains feature -##' alignment results. +##' @description \code{hasFeatures}: whether the object contains correspondence +##' results (i.e. features). ##' ##' @rdname XCMSnExp-class -setMethod("hasAlignedFeatures", "XCMSnExp", function(object) { - return(hasAlignedFeatures(object@msFeatureData)) +setMethod("hasFeatures", "XCMSnExp", function(object) { + return(hasFeatures(object@msFeatureData)) }) -##' @aliases hasDetectedFeatures +##' @aliases hasChromPeaks ##' -##' @description \code{hasDetectedFeatures}: whether the object contains feature +##' @description \code{hasChromPeaks}: whether the object contains peak ##' detection results. ##' ##' @rdname XCMSnExp-class -setMethod("hasDetectedFeatures", "XCMSnExp", function(object) { - return(hasDetectedFeatures(object@msFeatureData)) +setMethod("hasChromPeaks", "XCMSnExp", function(object) { + return(hasChromPeaks(object@msFeatureData)) }) ##' @aliases adjustedRtime @@ -76,7 +76,7 @@ setMethod("hasDetectedFeatures", "XCMSnExp", function(object) { ##' extract/set adjusted retention times. \code{adjustedRtime<-} should not be ##' called manually, it is called internally by the \code{\link{adjustRtime}} ##' methods. For \code{XCMSnExp} objects, \code{adjustedRtime<-} does also apply -##' the retention time adjustment to the features in the object. +##' the retention time adjustment to the chromatographic peaks in the object. ##' The \code{bySample} parameter allows to specify whether the adjusted ##' retention time should be grouped by sample (file). ##' @@ -89,6 +89,8 @@ setMethod("hasDetectedFeatures", "XCMSnExp", function(object) { ##' @rdname XCMSnExp-class setMethod("adjustedRtime", "XCMSnExp", function(object, bySample = FALSE) { res <- adjustedRtime(object@msFeatureData) + if (length(res) == 0) + return(res) ## Adjusted retention time is a list of retention times. if (!bySample) { ## Have to re-order the adjusted retention times by spectrum name, such @@ -112,18 +114,18 @@ setReplaceMethod("adjustedRtime", "XCMSnExp", function(object, value) { newFd <- new("MsFeatureData") newFd@.xData <- .copy_env(object@msFeatureData) adjustedRtime(newFd) <- value - if (hasDetectedFeatures(newFd)) { - ## Change also the retention times reported in the features matrix. + if (hasChromPeaks(newFd)) { + ## Change also the retention times reported in the peak matrix. if (length(value) != length(rtime(object, bySample = TRUE))) stop("The length of 'value' has to match the number of samples!") message("Applying retention time adjustment to the identified", - " features ... ", appendLF = FALSE) - fts <- .applyRtAdjToFeatures(features(newFd), - rtraw = rtime(object, bySample = TRUE), - rtadj = value) + " chromatographic peaks ... ", appendLF = FALSE) + fts <- .applyRtAdjToChromPeaks(chromPeaks(newFd), + rtraw = rtime(object, bySample = TRUE), + rtadj = value) ## Calling this on the MsFeatureData to avoid all results being removed - ## again by the features<- method. - features(newFd) <- fts + ## again by the chromPeaks<- method. + chromPeaks(newFd) <- fts message("OK") } lockEnvironment(newFd, bindings = TRUE) @@ -132,34 +134,35 @@ setReplaceMethod("adjustedRtime", "XCMSnExp", function(object, value) { return(object) }) -##' @aliases featureGroups -##' -##' @description \code{featureGroups}, \code{featureGroups<-}: extract -##' or set the feature alignment results. -##' -##' @return For \code{featureGroups}: a \code{DataFrame} with feature alignment -##' information, each row corresponding to one group of aligned features (across -##' samples) and columns \code{"mzmed"} (median mz value), \code{"mzmin"} -##' (minimal mz value), \code{"mzmax"} (maximum mz value), \code{"rtmed"} (median -##' retention time), \code{"rtmin"} (minimal retention time), \code{"rtmax"} -##' (maximal retention time) and \code{"featureidx"}. Column \code{"featureidx"} -##' contains a \code{list} with indices of features (rows) in the matrix returned -##' by the \code{features} method that belong to that feature group. The method -##' returns \code{NULL} if no aligned feature information is present. +##' @aliases featureDefinitions +##' +##' @description \code{featureDefinitions}, \code{featureDefinitions<-}: extract +##' or set the correspondence results, i.e. the mz-rt features (peak groups). +##' +##' @return For \code{featureDefinitions}: a \code{DataFrame} with peak grouping +##' information, each row corresponding to one mz-rt feature (grouped peaks +##' within and across samples) and columns \code{"mzmed"} (median mz value), +##' \code{"mzmin"} (minimal mz value), \code{"mzmax"} (maximum mz value), +##' \code{"rtmed"} (median retention time), \code{"rtmin"} (minimal retention +##' time), \code{"rtmax"} (maximal retention time) and \code{"peakidx"}. +##' Column \code{"peakidx"} contains a \code{list} with indices of +##' chromatographic peaks (rows) in the matrix returned by the \code{chromPeaks} +##' method that belong to that feature group. The method returns \code{NULL} if +##' no feature definitions are present. ##' ##' @rdname XCMSnExp-class -setMethod("featureGroups", "XCMSnExp", function(object) { - return(featureGroups(object@msFeatureData)) +setMethod("featureDefinitions", "XCMSnExp", function(object) { + return(featureDefinitions(object@msFeatureData)) }) -##' @aliases featureGroups<- +##' @aliases featureDefinitions<- ##' ##' @rdname XCMSnExp-class -setReplaceMethod("featureGroups", "XCMSnExp", function(object, value) { - if (hasAlignedFeatures(object)) - object <- dropFeatureGroups(object) +setReplaceMethod("featureDefinitions", "XCMSnExp", function(object, value) { + if (hasFeatures(object)) + object <- dropFeatureDefinitions(object) newFd <- new("MsFeatureData") newFd@.xData <- .copy_env(object@msFeatureData) - featureGroups(newFd) <- value + featureDefinitions(newFd) <- value lockEnvironment(newFd, bindings = TRUE) object@msFeatureData <- newFd if (validObject(object)) { @@ -170,41 +173,44 @@ setReplaceMethod("featureGroups", "XCMSnExp", function(object, value) { } }) -##' @aliases features -##' -##' @description \code{features}, \code{features<-}: extract or set -##' the matrix containing the information on identified features. Parameter -##' \code{bySample} allows to specify whether features should be returned -##' ungrouped (default \code{bySample = FALSE}) or grouped by sample ( -##' \code{bySample = TRUE}). The \code{features<-} method for \code{XCMSnExp} -##' objects removes also all feature alignment and retention time correction -##' results. +##' @aliases chromPeaks +##' +##' @description \code{chromPeaks}, \code{chromPeaks<-}: extract or set +##' the matrix containing the information on identified chromatographic peaks. +##' Parameter \code{bySample} allows to specify whether peaks should be +##' returned ungrouped (default \code{bySample = FALSE}) or grouped by sample ( +##' \code{bySample = TRUE}). The \code{chromPeaks<-} method for \code{XCMSnExp} +##' objects removes also all correspondence (peak grouping) and retention time +##' correction (alignment) results. ##' See description of the return value for details on the returned matrix. Users -##' usually don't have to use the \code{features<-} method directly as detected -##' features are added to the object by the \code{\link{detectFeatures}} method. +##' usually don't have to use the \code{chromPeaks<-} method directly as detected +##' chromatographic peaks are added to the object by the +##' \code{\link{findChromPeaks}} method. ##' -##' @return For \code{features}: if \code{bySample = FALSE} a \code{matrix} with +##' @return For \code{chromPeaks}: if \code{bySample = FALSE} a \code{matrix} with ##' at least the following columns: \code{"mz"} (mz value for the largest ##' intensity), \code{"mzmin"} (minimal mz value), \code{"mzmax"} (maximal mz ##' value), \code{"rt"} (retention time for the peak apex), \code{"rtmin"} ##' (minimal retention time), \code{"rtmax"} (maximal retention time), -##' \code{"into"} (integrated, original, intensity of the feature) and -##' \code{"sample"} (sample index in which the feature was identified). -##' Depending on the employed feature detection algorithm and the +##' \code{"into"} (integrated, original, intensity of the peak) and +##' \code{"sample"} (sample index in which the peak was identified). +##' Depending on the employed peak detection algorithm and the ##' \code{verboseColumns} parameter of it additional columns might be returned. -##' For \code{bySample = TRUE} the features are returned as a \code{list} of -##' matrices, each containing the features of a specific sample. For sample in -##' which no feastures were detected a matrix with 0 rows is returned. +##' For \code{bySample = TRUE} the chronatographic peaks are returned as a +##' \code{list} of matrices, each containing the chromatographic peak of a +##' specific sample. For sample in which no feastures were detected a matrix +##' with 0 rows is returned. ##' ##' @rdname XCMSnExp-class -setMethod("features", "XCMSnExp", function(object, bySample = FALSE) { +setMethod("chromPeaks", "XCMSnExp", function(object, bySample = FALSE) { if (bySample) { - tmp <- split(features(object), f = features(object)[, "sample"]) + tmp <- split(chromPeaks(object), f = chromPeaks(object)[, "sample"]) ## Ensure we return something for each sample in case there is a sample - ## without detected features. + ## without detected peaks. res <- vector("list", length(fileNames(object))) names(res) <- as.character(1:length(res)) - tmp <- split.data.frame(features(object), f = features(object)[, "sample"]) + tmp <- split.data.frame(chromPeaks(object), + f = chromPeaks(object)[, "sample"]) res[as.numeric(names(tmp))] <- tmp if (any(lengths(res) == 0)) { emat <- matrix(nrow = 0, ncol = ncol(tmp[[1]])) @@ -213,21 +219,21 @@ setMethod("features", "XCMSnExp", function(object, bySample = FALSE) { } return(res) } else { - return(features(object@msFeatureData)) + return(chromPeaks(object@msFeatureData)) } }) -##' @aliases features<- +##' @aliases chromPeaks<- ##' ##' @rdname XCMSnExp-class -setReplaceMethod("features", "XCMSnExp", function(object, value) { +setReplaceMethod("chromPeaks", "XCMSnExp", function(object, value) { newFd <- new("MsFeatureData") ## Dropping all alignment results and all retention time corrections. suppressMessages( - object <- dropFeatures(object) + object <- dropChromPeaks(object) ) ## Ensure that we remove ALL related process history steps newFd@.xData <- .copy_env(object@msFeatureData) - features(newFd) <- value + chromPeaks(newFd) <- value lockEnvironment(newFd, bindings = TRUE) object@msFeatureData <- newFd if (validObject(object)) { @@ -363,8 +369,8 @@ setMethod("spectra", "XCMSnExp", function(object, bySample = FALSE) { ##' ##' @param type For \code{processHistory}: restrict returned ##' \code{\link{ProcessHistory}} objects to analysis steps of a certain type. -##' Supported values are \code{"Unknown"}, \code{"Feature detection"}, -##' \code{"Feature alignment"} and \code{"Retention time correction"}. +##' Supported values are \code{"Unknown"}, \code{"Peak detection"}, +##' \code{"Peak grouping"} and \code{"Retention time correction"}. ##' ##' @return For \code{processHistory}: a \code{list} of ##' \code{\link{ProcessHistory}} objects providing the details of the individual @@ -413,79 +419,86 @@ setMethod("addProcessHistory", "XCMSnExp", function(object, ph) { return(object) }) -##' @aliases dropFeatures +##' @aliases dropChromPeaks ##' -##' @description \code{dropFeatures}: drops any identified features -##' and returns the object without that information. Note that for -##' \code{XCMSnExp} objects the method drops all results from a feature alignment -##' or retention time adjustment too. For \code{XCMSnExp} objects the method -##' drops also any related process history steps. +##' @description \code{dropChromPeaks}: drops any identified chromatographic +##' peaks and returns the object without that information. Note that for +##' \code{XCMSnExp} objects the method drops all results from a correspondence +##' (peak grouping) or alignment (retention time adjustment) too. +##' For \code{XCMSnExp} objects the method drops also any related process +##' history steps. ##' ##' @rdname XCMSnExp-class -setMethod("dropFeatures", "XCMSnExp", function(object) { - if (hasDetectedFeatures(object)) { - object <- dropProcessHistories(object, type = .PROCSTEP.FEATURE.DETECTION) +setMethod("dropChromPeaks", "XCMSnExp", function(object) { + if (hasChromPeaks(object)) { + object <- dropProcessHistories(object, type = .PROCSTEP.PEAK.DETECTION) ## Make sure we delete all related process history steps object <- dropProcessHistories(object, type = .PROCSTEP.RTIME.CORRECTION) - object <- dropProcessHistories(object, type = .PROCSTEP.FEATURE.ALIGNMENT) + object <- dropProcessHistories(object, type = .PROCSTEP.PEAK.GROUPING) ## idx_fd <- which(unlist(lapply(processHistory(object), processType)) == - ## .PROCSTEP.FEATURE.DETECTION) + ## .PROCSTEP.PEAK.DETECTION) ## if (length(idx_fd) > 0) ## object@.processHistory <- object@.processHistory[-idx_fd] newFd <- new("MsFeatureData") newFd@.xData <- .copy_env(object@msFeatureData) - newFd <- dropFeatures(newFd) + newFd <- dropChromPeaks(newFd) ## Dropping other results from the environment (not the object). if (hasAdjustedRtime(newFd)) newFd <- dropAdjustedRtime(newFd) - if (hasAlignedFeatures(newFd)) - newFd <- dropFeatureGroups(newFd) + if (hasFeatures(newFd)) + newFd <- dropFeatureDefinitions(newFd) lockEnvironment(newFd, bindings = TRUE) object@msFeatureData <- newFd } if (validObject(object)) return(object) }) -##' @aliases dropFeatureGroups -##' -##' @description \code{dropFeatureGroups}: drops aligned feature -##' results (i.e. feature groups) and returns the object -##' without that information. Note that for \code{XCMSnExp} objects the method -##' will also drop retention time adjustment results, if these were performed -##' after the last feature alignment (i.e. which base on the results from the -##' feature alignment that are going to be removed). For \code{XCMSnExp} objects -##' also all related process history steps are removed. -##' -##' @param keepAdjRtime For \code{dropFeatureGroups,XCMSnExp}: logical(1) -##' defining whether eventually present retention time adjustment should not be -##' dropped. By default dropping feature groups drops retention time adjustment -##' results too. -##' -##' @param dropLastN For \code{dropFeatureGroups,XCMSnExp}: numeric(1) defining -##' the number of feature alignment related process history steps to remove. By -##' default \code{dropLastN = -1}, dropping the features removes all process -##' history steps related to feature alignment. Setting e.g. \code{dropLastN = 1} -##' will only remove the most recent feature alignment related process history -##' step. +##' @aliases dropFeatureDefinitions +##' +##' @description \code{dropFeatureDefinitions}: drops the results from a +##' correspondence (peak grouping) analysis, i.e. the definition of the mz-rt +##' features and returns the object without that information. Note that for +##' \code{XCMSnExp} objects the method will also drop retention time adjustment +##' results, if these were performed after the last peak grouping (i.e. which +##' base on the results from the peak grouping that are going to be removed). +##' For \code{XCMSnExp} objects also all related process history steps are +##' removed. +##' +##' @param keepAdjRtime For \code{dropFeatureDefinitions,XCMSnExp}: +##' \code{logical(1)} defining whether eventually present retention time +##' adjustment should not be dropped. By default dropping feature definitions +##' drops retention time adjustment results too. +##' +##' @param dropLastN For \code{dropFeatureDefinitions,XCMSnExp}: +##' \code{numeric(1)} defining the number of peak grouping related process +##' history steps to remove. By default \code{dropLastN = -1}, dropping the +##' 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. ##' ##' @rdname XCMSnExp-class -setMethod("dropFeatureGroups", "XCMSnExp", function(object, keepAdjRtime = FALSE, - dropLastN = -1) { - if (hasAlignedFeatures(object)) { +setMethod("dropFeatureDefinitions", "XCMSnExp", function(object, + keepAdjRtime = FALSE, + dropLastN = -1) { + if (hasFeatures(object)) { phTypes <- unlist(lapply(processHistory(object), function(z) processType(z))) idx_art <- which(phTypes == .PROCSTEP.RTIME.CORRECTION) - idx_fal <- which(phTypes == .PROCSTEP.FEATURE.ALIGNMENT) + idx_fal <- which(phTypes == .PROCSTEP.PEAK.GROUPING) + if (length(idx_art) == 0) + idx_art <- -1L + if (length(idx_fal) == 0) + idx_fal <- -1L ## 1) drop last related process history step and results object <- dropProcessHistories(object, - type = .PROCSTEP.FEATURE.ALIGNMENT, + type = .PROCSTEP.PEAK.GROUPING, num = 1) newFd <- new("MsFeatureData") newFd@.xData <- .copy_env(object@msFeatureData) - newFd <- dropFeatureGroups(newFd) + newFd <- dropFeatureDefinitions(newFd) lockEnvironment(newFd, bindings = TRUE) object@msFeatureData <- newFd - ## 2) If retention time correction was performed after the latest feature + ## 2) If retention time correction was performed after the latest peak ## alignment, drop also the retention time correction and all related ## process history steps. ## Otherwise (grouping performed after retention time adjustment) do @@ -494,13 +507,13 @@ setMethod("dropFeatureGroups", "XCMSnExp", function(object, keepAdjRtime = FALSE if (hasAdjustedRtime(object)) { if (max(idx_art) > max(idx_fal)) { object <- dropProcessHistories(object, - type = .PROCSTEP.FEATURE.ALIGNMENT) - ## This will ensure that the retention times of the features + type = .PROCSTEP.PEAK.GROUPING) + ## This will ensure that the retention times of the peaks ## are restored. object <- dropAdjustedRtime(object) - warning("Removed also feature alignment results as these based", - " on the retention time correction results that were", - " dropped.") + warning("Removed also correspondence (peak grouping) results as", + " these based on the retention time correction results", + " that were dropped.") } } } @@ -513,11 +526,12 @@ setMethod("dropFeatureGroups", "XCMSnExp", function(object, keepAdjRtime = FALSE ##' @description \code{dropAdjustedRtime}: drops any retention time ##' adjustment information and returns the object without adjusted retention ##' time. For \code{XCMSnExp} object this also reverts the retention times -##' reported for the features in the feature matrix to the original, raw, ones -##' (after feature detection). Note that for \code{XCMSnExp} objects the method -##' drops also all feature alignment results if these were performed \emph{after} -##' the retention time adjustment. For \code{XCMSnExp} objects the method drops -##' also any related process history steps. +##' reported for the chromatographic peaks in the peak matrix to the original, +##' raw, ones (after chromatographic peak detection). Note that for +##' \code{XCMSnExp} objects the method drops also all peak grouping results +##' if these were performed \emph{after} the retention time adjustment. +##' For \code{XCMSnExp} objects the method drops also any related process history +##' steps. ##' ##' @rdname XCMSnExp-class setMethod("dropAdjustedRtime", "XCMSnExp", function(object) { @@ -527,23 +541,27 @@ setMethod("dropAdjustedRtime", "XCMSnExp", function(object) { phTypes <- unlist(lapply(processHistory(object), function(z) processType(z))) idx_art <- which(phTypes == .PROCSTEP.RTIME.CORRECTION) - idx_fal <- which(phTypes == .PROCSTEP.FEATURE.ALIGNMENT) + idx_fal <- which(phTypes == .PROCSTEP.PEAK.GROUPING) + if (length(idx_art) == 0) + idx_art <- -1L + if (length(idx_fal) == 0) + idx_fal <- -1L ## Copy the content of the object newFd <- new("MsFeatureData") newFd@.xData <- .copy_env(object@msFeatureData) - ## Revert applied adjustments in features: - if (hasDetectedFeatures(newFd)) { - message("Reverting retention times of identified features to ", + ## Revert applied adjustments in peaks: + if (hasChromPeaks(newFd)) { + message("Reverting retention times of identified peaks to ", "original values ... ", appendLF = FALSE) - fts <- .applyRtAdjToFeatures(features(newFd), - rtraw = adjustedRtime(object, - bySample = TRUE), - rtadj = rtime(object, - bySample = TRUE, - adjusted = FALSE)) - ## Replacing features in MsFeatureData, not in XCMSnExp to avoid + fts <- .applyRtAdjToChromPeaks(chromPeaks(newFd), + rtraw = adjustedRtime(object, + bySample = TRUE), + rtadj = rtime(object, + bySample = TRUE, + adjusted = FALSE)) + ## Replacing peaks in MsFeatureData, not in XCMSnExp to avoid ## all results being removed. - features(newFd) <- fts + chromPeaks(newFd) <- fts message("OK") } ## 1) Drop the retention time adjustment and (the latest) related process @@ -556,18 +574,18 @@ setMethod("dropAdjustedRtime", "XCMSnExp", function(object) { lockEnvironment(newFd, bindings = TRUE) ## 2) If grouping has been performed AFTER retention time correction it ## has to be dropped too, including ALL related process histories. - if (hasAlignedFeatures(object)) { + if (hasFeatures(object)) { if (max(idx_fal) > max(idx_art)) { - object <- dropFeatureGroups(object) + object <- dropFeatureDefinitions(object) object <- dropProcessHistories(object, - type = .PROCSTEP.FEATURE.ALIGNMENT, + type = .PROCSTEP.PEAK.GROUPING, num = -1) } } else { - ## If there is any feature alignment related process history, but no - ## feature alignment results, drop them. + ## If there is any peak alignment related process history, but no + ## peak alignment results, drop them. object <- dropProcessHistories(object, - type = .PROCSTEP.FEATURE.ALIGNMENT, + type = .PROCSTEP.PEAK.GROUPING, num = -1) } } @@ -576,26 +594,6 @@ setMethod("dropAdjustedRtime", "XCMSnExp", function(object) { }) -############################################################ -## Methods inherited from OnDiskMSnExp. -## For some of these methods (altering the raw data or subsetting) we have to -## remove the results. -## Methods to consider: -## o [ subset spectra, return an OnDiskMSnExp. -## o bin remove the results -## o clean remove the results. -## o featureNames returns the names of the spectra. -## o filterAcquisitionNum remove the results. -## o filterFile remove the results. -## o filterMsLevel remove the results. -## o filterMz -## o filterRt -## o fromFile<- -## o normalize remove the results. -## o pickPeaks remove the results. -## o removePeaks remove the results. -## o smooth remove the results. - ##' @title XCMSnExp data manipulation methods inherited from MSnbase ##' ##' @description The methods listed on this page are \code{\link{XCMSnExp}} @@ -632,16 +630,22 @@ setMethod("dropAdjustedRtime", "XCMSnExp", function(object) { setMethod("[", signature(x = "XCMSnExp", i = "logicalOrNumeric", j = "missing", drop = "missing"), function(x, i, j, drop) { - ## Want to support subsetting of the features! + ## Want to support subsetting of the peaks! ## This means that we will also have to adjust the process ## history accordingly. - if (hasAdjustedRtime(x) | hasAlignedFeatures(x) | - hasDetectedFeatures(x)) { + if (hasAdjustedRtime(x) | hasFeatures(x) | + hasChromPeaks(x)) { ## x@.processHistory <- list() ## x@msFeatureData <- new("MsFeatureData") - x <- dropAdjustedRtime(x) - x <- dropFeatureGroups(x) - x <- dropFeatures(x) + suppressMessages( + x <- dropAdjustedRtime(x) + ) + suppressMessages( + x <- dropFeatureDefinitions(x) + ) + suppressMessages( + x <- dropChromPeaks(x) + ) warning("Removed preprocessing results") } callNextMethod() @@ -673,13 +677,13 @@ setMethod("[", signature(x = "XCMSnExp", i = "logicalOrNumeric", j = "missing", ##' ##' @rdname XCMSnExp-inherited-methods setMethod("bin", "XCMSnExp", function(object, binSize = 1L, msLevel.) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -698,13 +702,13 @@ setMethod("bin", "XCMSnExp", function(object, binSize = 1L, msLevel.) { ##' @rdname XCMSnExp-inherited-methods setMethod("clean", "XCMSnExp", function(object, all = FALSE, verbose = FALSE, msLevel.) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -716,13 +720,13 @@ setMethod("clean", "XCMSnExp", function(object, all = FALSE, ##' ##' @rdname XCMSnExp-inherited-methods setMethod("filterMsLevel", "XCMSnExp", function(object, msLevel.) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -743,13 +747,13 @@ setMethod("filterMsLevel", "XCMSnExp", function(object, msLevel.) { ##' ##' @rdname XCMSnExp-inherited-methods setMethod("filterAcquisitionNum", "XCMSnExp", function(object, n, file) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -765,9 +769,12 @@ setMethod("filterAcquisitionNum", "XCMSnExp", function(object, n, file) { ##' results. ##' ##' @description \code{filterFile}: allows to reduce the -##' \code{\link{XCMSnExp}} to data from only certain files. Identified features -##' for these files are retained while eventually all present feature -##' alignment/grouping information and adjusted retention times are dropped.. +##' \code{\link{XCMSnExp}} to data from only certain files. Identified +##' chromatographic peaks for these files are retained while all eventually +##' present features (peak grouping information) are dropped. By default also +##' adjusted retention times are removed. This can be overwritten by setting +##' \code{keepAdjustedRtime = TRUE}, but users should use this option with +##' caution. ##' ##' @note The \code{filterFile} method removes also process history steps not ##' related to the files to which the object should be sub-setted and updates @@ -782,6 +789,11 @@ setMethod("filterAcquisitionNum", "XCMSnExp", function(object, n, file) { ##' the file names to sub set. The indices are expected to be increasingly ##' ordered, if not they are ordered internally. ##' +##' @param keepAdjustedRtime For \code{filterFile}: \code{logical(1)} defining +##' whether the adjusted retention times should be kept, even if features are +##' being removed (and the retention time correction being potentially performed +##' on these features). +##' ##' @return All methods return an \code{\link{XCMSnExp}} object. ##' ##' @author Johannes Rainer @@ -799,22 +811,42 @@ setMethod("filterAcquisitionNum", "XCMSnExp", function(object, n, file) { ##' ## Read the files ##' od <- readMSData2(fs) ##' -##' ## Perform feature detection on them using default matched filter settings. +##' ## Perform peak detection on them using default matched filter settings. ##' mfp <- MatchedFilterParam() -##' xod <- detectFeatures(od, param = mfp) +##' xod <- findChromPeaks(od, param = mfp) ##' ##' ## Subset the dataset to the first and third file. ##' xod_sub <- filterFile(xod, file = c(1, 3)) ##' -##' ## The number of features per file for the full object -##' table(features(xod)[, "sample"]) +##' ## The number of chromatographic peaks per file for the full object +##' table(chromPeaks(xod)[, "sample"]) ##' -##' ## The number of features per file for the subset -##' table(features(xod_sub)[, "sample"]) +##' ## The number of chromatographic peaks per file for the subset +##' table(chromPeaks(xod_sub)[, "sample"]) ##' ##' basename(fileNames(xod)) ##' basename(fileNames(xod_sub)) -setMethod("filterFile", "XCMSnExp", function(object, file) { +##' +##' ## Filter on mz values; chromatographic peaks and features within the +##' ## mz range are retained (as well as adjusted retention times). +##' xod_sub <- filterMz(xod, mz = c(300, 400)) +##' head(chromPeaks(xod_sub)) +##' nrow(chromPeaks(xod_sub)) +##' nrow(chromPeaks(xod)) +##' +##' ## Filter on rt values. All chromatographic peaks and features within the +##' ## retention time range are retained. Filtering is performed by default on +##' ## adjusted retention times, if present. +##' xod_sub <- filterRt(xod, rt = c(2700, 2900)) +##' +##' range(rtime(xod_sub)) +##' head(chromPeaks(xod_sub)) +##' range(chromPeaks(xod_sub)[, "rt"]) +##' +##' nrow(chromPeaks(xod)) +##' nrow(chromPeaks(xod_sub)) +setMethod("filterFile", "XCMSnExp", function(object, file, + keepAdjustedRtime = FALSE) { if (missing(file)) return(object) if (is.character(file)) { file <- base::match(file, basename(fileNames(object))) @@ -825,24 +857,33 @@ setMethod("filterFile", "XCMSnExp", function(object, file) { ## Error checking - seems that's not performed downstream. if (!all(file %in% 1:length(fileNames(object)))) stop("'file' has to be within 1 and the number of files in the object!") - ## Get the data we want to keep/subset - fts <- features(object) - if (hasAdjustedRtime(object)) { - warning("Adjusted retention times removed.") + ## Dropping data. + if (hasAdjustedRtime(object) & !keepAdjustedRtime) { + message("Adjusted retention times removed.") object <- dropAdjustedRtime(object) } - if (hasAlignedFeatures(object)) { - warning("Feature alignment information removed.") - object <- dropFeatureGroups(object) - } - ## Process the processing history. - object <- dropProcessHistories(object, type = c(.PROCSTEP.FEATURE.ALIGNMENT, - .PROCSTEP.RTIME.CORRECTION)) + suppressWarnings( + adjRt <- adjustedRtime(object, bySample = TRUE) + ) + ## Get the data we want to keep/subset. + fts <- chromPeaks(object) + ## Keep also the processHistory ph <- processHistory(object) + if (hasFeatures(object)) { + message("Correspondence results (features) removed.") + suppressMessages( + object <- dropFeatureDefinitions(object) + ) + } + ph <- dropProcessHistoriesList(ph, type = .PROCSTEP.PEAK.GROUPING) + ## ## Process the processing history. + ## object <- dropProcessHistories(object, type = c(.PROCSTEP.PEAK.GROUPING, + ## .PROCSTEP.RTIME.CORRECTION)) + ## ph <- processHistory(object) ## The next method will actually clean everything, process history and ## msFeatureData suppressWarnings( - object <- callNextMethod() + object <- callNextMethod(object = object, file = file) ) ## Remove ProcessHistory not related to any of the files. if (length(ph)) { @@ -856,19 +897,31 @@ setMethod("filterFile", "XCMSnExp", function(object, file) { updateFileIndex(z, old = file, new = 1:length(file)) }) } - ## Process features. + ## Process peaks. fts <- fts[fts[, "sample"] %in% file, , drop = FALSE] fts[, "sample"] <- match(fts[, "sample"], file) - features(object) <- fts + if (length(adjRt) & keepAdjustedRtime) { + ## Put all directly into the msFeatureData environment to avoid an + ## additional correction of the peak retention times by the adjusted rt. + newFd <- new("MsFeatureData") + newFd@.xData <- .copy_env(object@msFeatureData) + chromPeaks(newFd) <- fts + adjustedRtime(newFd) <- adjRt[file] + lockEnvironment(newFd, bindings = TRUE) + object@msFeatureData <- newFd + } else { + chromPeaks(object) <- fts + } object@.processHistory <- ph return(object) }) ##' @description \code{filterMz}: filters the data set based on the -##' provided mz value range. All features and feature groups (aligned features) -##' falling completely within the provided mz value range are retained (if their -##' minimal mz value is \code{>= mz[1]} and the maximal mz value \code{<= mz[2]}. -##' Adjusted retention times, if present, are not altered by the filtering. +##' provided mz value range. All chromatographic peaks and features (grouped +##' peaks) falling completely within the provided mz value range are retained +##' (if their minimal mz value is \code{>= mz[1]} and the maximal mz value +##' \code{<= mz[2]}. Adjusted retention times, if present, are not altered by +##' the filtering. ##' ##' @param mz For \code{filterMz}: \code{numeric(2)} defining the lower and upper ##' mz value for the filtering. @@ -886,13 +939,13 @@ setMethod("filterMz", "XCMSnExp", function(object, mz, msLevel., ...) { if (!is.numeric(mz) | length(mz) != 2) stop("'mz' has to be a numeric vector of length(2)!") mz <- range(mz) - ## Subset features if present. + ## Subset peaks if present. object <- callNextMethod() # just adds to processing queue. - if (hasDetectedFeatures(object)) { - fts <- features(object) + if (hasChromPeaks(object)) { + fts <- chromPeaks(object) keepIdx <- which(fts[, "mzmin"] >= mz[1] & fts[, "mzmax"] <= mz[2]) - newE <- .filterFeatures(object@msFeatureData, idx = keepIdx) + newE <- .filterChromPeaks(object@msFeatureData, idx = keepIdx) lockEnvironment(newE, bindings = TRUE) object@msFeatureData <- newE } @@ -901,14 +954,14 @@ setMethod("filterMz", "XCMSnExp", function(object, mz, msLevel., ...) { }) ##' @description \code{filterRt}: filters the data set based on the -##' provided retention time range. All features and feature groups within -##' the specified retention time window are retained (i.e. if the retention time -##' corresponding to the feature's peak is within the specified rt range). -##' If retention time correction has been performed, the method will by default -##' filter the object by adjusted retention times. The argument \code{adjusted} -##' allows to specify manually whether filtering should be performed by raw or -##' adjusted retention times. Filtering by retention time does not drop any -##' preprocessing results. +##' provided retention time range. All chromatographic peaks and features +##' (grouped peaks) the specified retention time window are retained (i.e. if +##' the retention time corresponding to the peak's apex is within the specified +##' rt range). If retention time correction has been performed, the method will +##' by default filter the object by adjusted retention times. +##' The argument \code{adjusted} allows to specify manually whether filtering +##' should be performed by raw or adjusted retention times. Filtering by +##' retention time does not drop any preprocessing results. ##' The method returns an empty object if no spectrum or feature is within the ##' specified retention time range. ##' @@ -929,8 +982,8 @@ setMethod("filterRt", "XCMSnExp", function(object, rt, msLevel., rt <- range(rt) ## Get index of spectra within the rt window. ## Subset using [ + ## Subset peaks ## Subset features - ## Subset feature groups ## Subset adjusted retention time if (!adjusted) { have_rt <- rtime(object, adjusted = FALSE, bySample = FALSE) @@ -956,30 +1009,30 @@ setMethod("filterRt", "XCMSnExp", function(object, rt, msLevel., ## mfd <- as(.copy_env(object@msFeatureData), "MsFeatureData") newMfd <- new("MsFeatureData") ph <- processHistory(object) - ## 1) Subset features within the retention time range and feature groups. + ## 1) Subset peaks within the retention time range and peak groups. keep_fts <- numeric() - if (hasDetectedFeatures(object)) { - ftrt <- features(object)[, "rt"] + if (hasChromPeaks(object)) { + ftrt <- chromPeaks(object)[, "rt"] if (!adjusted & hasAdjustedRtime(object)) { ## Have to convert the rt before subsetting. - fts <- .applyRtAdjToFeatures(features(object), - rtraw = rtime(object, bySample = TRUE), - rtadj = rtime(object, bySample = TRUE, - adjusted = FALSE)) + fts <- .applyRtAdjToChromPeaks(chromPeaks(object), + rtraw = rtime(object, bySample = TRUE), + rtadj = rtime(object, bySample = TRUE, + adjusted = FALSE)) ftrt <- fts[, "rt"] } keep_fts <- base::which(ftrt >= rt[1] & ftrt <= rt[2]) if (length(keep_fts)) - newMfd <- .filterFeatures(object, idx = keep_fts) + newMfd <- .filterChromPeaks(object, idx = keep_fts) ## features(newMfd) <- features(object)[keep_fts, , drop = FALSE] else ph <- dropProcessHistoriesList(ph, - type = c(.PROCSTEP.FEATURE.DETECTION, - .PROCSTEP.FEATURE.ALIGNMENT, - .PROCSTEP.RTIME.CORRECTION)) + type = c(.PROCSTEP.PEAK.DETECTION, + .PROCSTEP.PEAK.GROUPING)) } ## 2) Subset adjusted retention time - if (hasAdjustedRtime(object) & length(keep_fts)) { + ## if (hasAdjustedRtime(object) & length(keep_fts)) { + if (hasAdjustedRtime(object)) { ## Subset the adjusted retention times (which are stored as a list of ## rts by file): keep_by_file <- base::split(keep_logical, fromFile(object)) @@ -1031,13 +1084,13 @@ setMethod("filterRt", "XCMSnExp", function(object, rt, msLevel., ##' @rdname XCMSnExp-inherited-methods setMethod("normalize", "XCMSnExp", function(object, method = c("max", "sum"), ...) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -1061,20 +1114,23 @@ setMethod("normalize", "XCMSnExp", function(object, method = c("max", "sum"), setMethod("pickPeaks", "XCMSnExp", function(object, halfWindowSize = 3L, method = c("MAD", "SuperSmoother"), SNR = 0L, ...) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() }) -##' The \code{removePeaks} method removes peaks (intensities) lower than a -##' threshold. Note that these peaks are not features! See \code{\link[MSnbase]{removePeaks}} documentation for details and examples. +##' 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}} +##' documentation for details and examples. ##' ##' @param t For \code{removePeaks}: either a \code{numeric(1)} or \code{"min"} ##' defining the threshold (method) to be used. See @@ -1083,13 +1139,13 @@ setMethod("pickPeaks", "XCMSnExp", function(object, halfWindowSize = 3L, ##' @rdname XCMSnExp-inherited-methods setMethod("removePeaks", "XCMSnExp", function(object, t = "min", verbose = FALSE, msLevel.) { - if (hasAdjustedRtime(object) | hasAlignedFeatures(object) | - hasDetectedFeatures(object)) { + if (hasAdjustedRtime(object) | hasFeatures(object) | + hasChromPeaks(object)) { ## object@.processHistory <- list() ## object@msFeatureData <- new("MsFeatureData") object <- dropAdjustedRtime(object) - object <- dropFeatureGroups(object) - object <- dropFeatures(object) + object <- dropFeatureDefinitions(object) + object <- dropChromPeaks(object) warning("Removed preprocessing results") } callNextMethod() @@ -1103,13 +1159,13 @@ setMethod("smooth", "XCMSnExp", function(x, method = c("SavitzkyGolay", "MovingAverage"), halfWindowSize = 2L, verbose = FALSE, ...) { - if (hasAdjustedRtime(x) | hasAlignedFeatures(x) | - hasDetectedFeatures(x)) { + if (hasAdjustedRtime(x) | hasFeatures(x) | + hasChromPeaks(x)) { ## x@.processHistory <- list() ## x@msFeatureData <- new("MsFeatureData") x <- dropAdjustedRtime(x) - x <- dropFeatureGroups(x) - x <- dropFeatures(x) + x <- dropFeatureDefinitions(x) + x <- dropChromPeaks(x) warning("Removed preprocessing results") } callNextMethod() @@ -1125,43 +1181,43 @@ setMethod("smooth", "XCMSnExp", function(x, method = c("SavitzkyGolay", setAs(from = "XCMSnExp", to = "xcmsSet", def = .XCMSnExp2xcmsSet) -##' @title Feature alignment based on time dimension feature densities +##' @title Peak grouping/correspondence based on time dimension peak densities ##' -##' @description \code{groupFeatures,XCMSnExp,FeatureDensityParam}: -##' performs feature alignment (within and across samples) within in mz dimension -##' overlapping slices of MS data based on the density distribution of the -##' identified features in the slice along the time axis. +##' @description \code{groupChromPeaks,XCMSnExp,PeakDensityParam}: +##' performs correspondence (peak grouping within and across samples) within in +##' mz dimension overlapping slices of MS data based on the density distribution +##' of the identified chromatographic peaks in the slice along the time axis. ##' -##' @note Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause -##' all eventually present previous alignment results to be dropped. +##' @note Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause +##' all eventually present previous correspondence results to be dropped. ##' -##' @param object For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -##' containing the results from a previous feature detection analysis (see -##' \code{\link{detectFeatures}}). +##' @param object For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +##' containing the results from a previous peak detection analysis (see +##' \code{\link{findChromPeaks}}). ##' -##' For all other methods: a \code{FeatureDensityParam} object. +##' For all other methods: a \code{PeakDensityParam} object. ##' -##' @param param A \code{FeatureDensityParam} object containing all settings for -##' the feature alignment algorithm. +##' @param param A \code{PeakDensityParam} object containing all settings for +##' the peak grouping algorithm. ##' -##' @return For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -##' results of the feature alignment step. These can be accessed with the -##' \code{\link{featureGroups}} method. +##' @return For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +##' results of the correspondence analysis. The definition of the resulting mz-rt +##' features can be accessed with the \code{\link{featureDefinitions}} method. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature alignment. +##' the correspondence. ##' -##' @rdname groupFeatures-density -setMethod("groupFeatures", - signature(object = "XCMSnExp", param = "FeatureDensityParam"), +##' @rdname groupChromPeaks-density +setMethod("groupChromPeaks", + signature(object = "XCMSnExp", param = "PeakDensityParam"), function(object, param) { - if (!hasDetectedFeatures(object)) - stop("No feature detection results in 'object'! Please ", - "perform first a feature detection using the ", - "'detectFeatures' method.") + if (!hasChromPeaks(object)) + stop("No chromatographic peak detection results in 'object'! ", + "Please perform first a peak detection using the ", + "'findChromPeaks' method.") ## Get rid of any previous results. - if (hasAlignedFeatures(object)) - object <- dropFeatureGroups(object) + if (hasFeatures(object)) + object <- dropFeatureDefinitions(object) ## Check if we've got any sample groups: if (length(sampleGroups(param)) == 0) { sampleGroups(param) <- rep(1, length(fileNames(object))) @@ -1175,59 +1231,59 @@ setMethod("groupFeatures", "samples!") } startDate <- date() - res <- do_groupFeatures_density(features(object), - sampleGroups = sampleGroups(param), - bw = bw(param), - minFraction = minFraction(param), - minSamples = minSamples(param), - binSize = binSize(param), - maxFeatures = maxFeatures(param)) + res <- do_groupChromPeaks_density(chromPeaks(object), + sampleGroups = sampleGroups(param), + bw = bw(param), + minFraction = minFraction(param), + minSamples = minSamples(param), + binSize = binSize(param), + maxFeatures = maxFeatures(param)) xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.ALIGNMENT, + type. = .PROCSTEP.PEAK.GROUPING, fileIndex = 1:length(fileNames(object))) object <- addProcessHistory(object, xph) ## Add the results. - df <- DataFrame(res$featureGroups) - df$featureidx <- res$featureIndex - featureGroups(object) <- df + df <- DataFrame(res$featureDefinitions) + df$peakidx <- res$peakIndex + featureDefinitions(object) <- df if (validObject(object)) return(object) }) -##' @title Single-spectrum non-chromatography MS data feature detection +##' @title Single-spectrum non-chromatography MS data peak grouping ##' -##' @description \code{groupFeatures,XCMSnExp,MzClustParam}: -##' performs high resolution feature alignment for single spectrum metabolomics -##' data. +##' @description \code{groupChromPeaks,XCMSnExp,MzClustParam}: +##' performs high resolution peak grouping for single spectrum +##' metabolomics data. ##' -##' @note Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause -##' all eventually present previous alignment results to be dropped. +##' @note Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause +##' all eventually present previous correspondence results to be dropped. ##' -##' @param object For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -##' containing the results from a previous feature detection analysis (see -##' \code{\link{detectFeatures}}). +##' @param object For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +##' containing the results from a previous chromatographic peak detection +##' analysis (see \code{\link{findChromPeaks}}). ##' ##' For all other methods: a \code{MzClustParam} object. ##' ##' @param param A \code{MzClustParam} object containing all settings for -##' the feature alignment algorithm. +##' the peak grouping algorithm. ##' -##' @return For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -##' results of the feature alignment step. These can be accessed with the -##' \code{\link{featureGroups}} method. +##' @return For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +##' results of the peak grouping step (i.e. the features). These can be accessed +##' with the \code{\link{featureDefinitions}} method. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature alignment. +##' the peak grouping. ##' -##' @rdname groupFeatures-mzClust -setMethod("groupFeatures", +##' @rdname groupChromPeaks-mzClust +setMethod("groupChromPeaks", signature(object = "XCMSnExp", param = "MzClustParam"), function(object, param) { - if (!hasDetectedFeatures(object)) - stop("No feature detection results in 'object'! Please ", - "perform first a feature detection using the ", - "'detectFeatures' method.") + if (!hasChromPeaks(object)) + stop("No chromatographic peak detection results in 'object'! ", + "Please perform first a peak detection using the ", + "'findChromPeak' method.") ## I'm expecting a single spectrum per file! rtL <- split(rtime(object), f = fromFile(object)) if (any(lengths(rtL) > 1)) @@ -1235,8 +1291,8 @@ setMethod("groupFeatures", "algorithm does only work for single spectra ", "files/samples!") ## Get rid of any previous results. - if (hasAlignedFeatures(object)) - object <- dropFeatureGroups(object) + if (hasFeatures(object)) + object <- dropFeatureDefinitions(object) ## Check if we've got any sample groups: if (length(sampleGroups(param)) == 0) { sampleGroups(param) <- rep(1, length(fileNames(object))) @@ -1250,61 +1306,61 @@ setMethod("groupFeatures", "samples!") } startDate <- date() - res <- do_groupFeatures_mzClust(features(object), - sampleGroups = sampleGroups(param), - ppm = ppm(param), - absMz = absMz(param), - minFraction = minFraction(param), - minSamples = minSamples(param)) + res <- do_groupPeaks_mzClust(chromPeaks(object), + sampleGroups = sampleGroups(param), + ppm = ppm(param), + absMz = absMz(param), + minFraction = minFraction(param), + minSamples = minSamples(param)) xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.ALIGNMENT, + type. = .PROCSTEP.PEAK.GROUPING, fileIndex = 1:length(fileNames(object))) object <- addProcessHistory(object, xph) ## Add the results. - df <- DataFrame(res$featureGroups) - df$featureidx <- res$featureIndex - featureGroups(object) <- df + df <- DataFrame(res$featureDefinitions) + df$peakidx <- res$peakIndex + featureDefinitions(object) <- df if (validObject(object)) return(object) }) -##' @title Feature alignment based on proximity in the mz-rt space +##' @title Peak grouping/correspondence based on proximity in the mz-rt space ##' -##' @description \code{groupFeatures,XCMSnExp,NearestFeaturesParam}: -##' performs feature alignment based on the proximity between features from -##' different samples in the mz-rt range. +##' @description \code{groupChromPeaks,XCMSnExp,NearestPeaksParam}: +##' performs peak grouping based on the proximity between chromatographic +##' peaks from different samples in the mz-rt range. ##' -##' @note Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause +##' @note Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause ##' all eventually present previous alignment results to be dropped. ##' -##' @param object For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -##' containing the results from a previous feature detection analysis (see -##' \code{\link{detectFeatures}}). +##' @param object For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +##' containing the results from a previous chromatographic peak detection +##' analysis (see \code{\link{findChromPeaks}}). ##' -##' For all other methods: a \code{NearestFeaturesParam} object. +##' For all other methods: a \code{NearestPeaksParam} object. ##' -##' @param param A \code{NearestFeaturesParam} object containing all settings for -##' the feature alignment algorithm. +##' @param param A \code{NearestPeaksParam} object containing all settings for +##' the peak grouping algorithm. ##' -##' @return For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -##' results of the feature alignment step. These can be accessed with the -##' \code{\link{featureGroups}} method. +##' @return For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +##' results of the peak grouping/correspondence step (i.e. the mz-rt features). +##' These can be accessed with the \code{\link{featureDefinitions}} method. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature alignment. +##' the peak grouping. ##' -##' @rdname groupFeatures-nearest -setMethod("groupFeatures", - signature(object = "XCMSnExp", param = "NearestFeaturesParam"), +##' @rdname groupChromPeaks-nearest +setMethod("groupChromPeaks", + signature(object = "XCMSnExp", param = "NearestPeaksParam"), function(object, param) { - if (!hasDetectedFeatures(object)) - stop("No feature detection results in 'object'! Please ", - "perform first a feature detection using the ", - "'detectFeatures' method.") + if (!hasChromPeaks(object)) + stop("No chromatographic peak detection results in 'object'! ", + "Please perform first a peak detection using the ", + "'findChromPeaks' method.") ## Get rid of any previous results. - if (hasAlignedFeatures(object)) - object <- dropFeatureGroups(object) + if (hasFeatures(object)) + object <- dropFeatureDefinitions(object) ## Check if we've got any sample groups: if (length(sampleGroups(param)) == 0) { sampleGroups(param) <- rep(1, length(fileNames(object))) @@ -1318,82 +1374,85 @@ setMethod("groupFeatures", "samples!") } startDate <- date() - res <- do_groupFeatures_nearest(features(object), - sampleGroups = sampleGroups(param), - mzVsRtBalance = mzVsRtBalance(param), - absMz = absMz(param), - absRt = absRt(param), - kNN = kNN(param)) + res <- do_groupChromPeaks_nearest(chromPeaks(object), + sampleGroups = sampleGroups(param), + mzVsRtBalance = mzVsRtBalance(param), + absMz = absMz(param), + absRt = absRt(param), + kNN = kNN(param)) xph <- XProcessHistory(param = param, date. = startDate, - type. = .PROCSTEP.FEATURE.ALIGNMENT, + type. = .PROCSTEP.PEAK.GROUPING, fileIndex = 1:length(fileNames(object))) object <- addProcessHistory(object, xph) ## Add the results. - df <- DataFrame(res$featureGroups) - df$featureidx <- res$featureIndex - featureGroups(object) <- df + df <- DataFrame(res$featureDefinitions) + df$peakidx <- res$peakIndex + featureDefinitions(object) <- df if (validObject(object)) return(object) }) -##' @title Retention time correction based on alignment of house keeping feature +##' @title Retention time correction based on alignment of house keeping peak ##' groups ##' -##' @description \code{adjustRtime,XCMSnExp,FeatureGroupsParam}: -##' performs retention time correction based on the alignment of feature groups -##' found in all/most samples. +##' @description \code{adjustRtime,XCMSnExp,PeakGroupsParam}: +##' performs retention time correction based on the alignment of peak groups +##' (features) found in all/most samples. ##' -##' @note Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause -##' all feature grouping (alignment) results to be dropped. +##' @note This method requires that a correspondence has been performed on the +##' data (see \code{\link{groupChromPeaks}}). Calling \code{adjustRtime} on an +##' \code{XCMSnExp} object will cause all peak grouping (correspondence) results +##' to be dropped after rt correction. ##' ##' @param object For \code{adjustRtime}: an \code{\link{XCMSnExp}} object -##' containing the results from a previous feature detection (see -##' \code{\link{detectFeatures}}) and alignment analysis (see -##' \code{\link{groupFeatures}}). +##' containing the results from a previous chromatographic peak detection (see +##' \code{\link{findChromPeaks}}) and alignment analysis (see +##' \code{\link{groupChromPeaks}}). ##' -##' For all other methods: a \code{FeatureGroupsParam} object. +##' For all other methods: a \code{PeakGroupsParam} object. ##' -##' @param param A \code{FeatureGroupsParam} object containing all settings for +##' @param param A \code{PeakGroupsParam} object containing all settings for ##' the retention time correction method.. ##' ##' @return For \code{adjustRtime}: a \code{\link{XCMSnExp}} object with the ##' results of the retention time adjustment step. These can be accessed with the ##' \code{\link{adjustedRtime}} method. Retention time correction does also adjust -##' the retention time of the identified features (accessed \emph{via} -##' \code{\link{features}}. Note that retention time correction drops -##' all previous alignment results from the result object. +##' the retention time of the identified chromatographic peaks (accessed +##' \emph{via} \code{\link{chromPeaks}}. Note that retention time correction +##' drops all previous alignment results from the result object. ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature alignment. +##' the alignment. ##' -##' @rdname adjustRtime-featureGroups +##' @rdname adjustRtime-peakGroups setMethod("adjustRtime", - signature(object = "XCMSnExp", param = "FeatureGroupsParam"), + signature(object = "XCMSnExp", param = "PeakGroupsParam"), function(object, param) { - if (!hasDetectedFeatures(object)) - stop("No feature detection results in 'object'! Please ", - "perform first a feature detection using the ", - "'detectFeatures' method.") - if (!hasAlignedFeatures(object)) - stop("No feature alignment results in 'object'! Please ", - "perform first a feature alignment using the ", - "'groupFeatures' method.") + if (!hasChromPeaks(object)) + stop("No chromatographic peak detection results in 'object'! ", + "Please perform first a peak detection using the ", + "'findChromPeaks' method.") + if (!hasFeatures(object)) + stop("No feature definitions found in 'object'! Please ", + "perform first a peak grouping using the ", + "'groupChromPeak' method.") startDate <- date() - res <- do_adjustRtime_featureGroups(features(object), - featureIndex = featureGroups(object)$featureidx, - rtime = rtime(object, bySample = TRUE), - minFraction = minFraction(param), - extraFeatures = extraFeatures(param), - smooth = smooth(param), - span = span(param), - family = family(param) - ) - ## Dropping the feature groups but don't remove its process history + res <- do_adjustRtime_peakGroups( + chromPeaks(object), + peakIndex = featureDefinitions(object)$peakidx, + rtime = rtime(object, bySample = TRUE), + minFraction = minFraction(param), + extraPeaks = extraPeaks(param), + smooth = smooth(param), + span = span(param), + family = family(param) + ) + ## Dropping the peak groups but don't remove its process history ## step. - ph <- processHistory(object, type = .PROCSTEP.FEATURE.ALIGNMENT) - object <- dropFeatureGroups(object) + ph <- processHistory(object, type = .PROCSTEP.PEAK.GROUPING) + object <- dropFeatureDefinitions(object) ## Add the results. adjustedRtime<- should also fix the retention - ## times for the features! Want to keep also the lates alignment + ## times for the peaks! Want to keep also the lates alignment ## information adjustedRtime(object) <- res if (length(ph)) { @@ -1412,52 +1471,49 @@ setMethod("adjustRtime", ##' @title Align retention times across samples using Obiwarp ##' ##' @description \code{adjustRtime,XCMSnExp,ObiwarpParam}: -##' performs retention time correction based on the alignment of feature groups -##' found in all/most samples. +##' performs retention time correction/alignment based on the total mz-rt data +##' using the \emph{obiwarp} method. ##' ##' @note Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause -##' all feature grouping (alignment) results to be dropped. +##' all peak grouping (correspondence) results to be dropped. ##' ##' @param object For \code{adjustRtime}: an \code{\link{XCMSnExp}} object. ##' ##' For all other methods: a \code{ObiwarpParam} object. ##' ##' @param param A \code{ObiwarpParam} object containing all settings for -##' the retention time correction method. +##' the alignment method. ##' ##' @return For \code{adjustRtime,XCMSnExp,ObiwarpParam}: a ##' \code{\link{XCMSnExp}} object with the results of the retention time ##' adjustment step. These can be accessed with the \code{\link{adjustedRtime}} ##' method. Retention time correction does also adjust the retention time of the -##' identified features (accessed \emph{via} \code{\link{features}}. Note that -##' retention time correction drops all previous alignment results from the -##' result object. +##' identified chromatographic peaks (accessed \emph{via} +##' \code{\link{chromPeaks}}. Note that retention time correction drops all +##' previous peak grouping results from the result object. ##' ##' For \code{adjustRtime,OnDiskMSnExp,ObiwarpParam}: a \code{numeric} with the ##' adjusted retention times per spectra (in the same order than \code{rtime}). ##' ##' @seealso \code{\link{XCMSnExp}} for the object containing the results of -##' the feature alignment. +##' the alignment. +##' +##' @references +##' John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of +##' ESI-LC-MS Proteomic Data Sets by Ordered Bijective Interpolated Warping" +##' \emph{Anal. Chem.} 2006, 78 (17), 6140-6152. ##' ##' @rdname adjustRtime-obiwarp setMethod("adjustRtime", signature(object = "XCMSnExp", param = "ObiwarpParam"), function(object, param) { - ## We don't require any detected or aligned features. - ## if (!hasDetectedFeatures(object)) - ## stop("No feature detection results in 'object'! Please ", - ## "perform first a feature detection using the ", - ## "'detectFeatures' method.") - ## if (!hasAlignedFeatures(object)) - ## stop("No feature alignment results in 'object'! Please ", - ## "perform first a feature alignment using the ", - ## "'groupFeatures' method.") + ## We don't require any detected or aligned peaks. startDate <- date() res <- .obiwarp(as(object, "OnDiskMSnExp"), param = param) ## Dropping the feature groups. - object <- dropFeatureGroups(object) + object <- dropFeatureDefinitions(object) ## Add the results. adjustedRtime<- should also fix the retention - ## times for the features! Want to keep also the lates alignment + ## times for the peaks! Want to keep also the lates alignment ## information adjustedRtime(object) <- res ## Add the process history step. @@ -1488,70 +1544,71 @@ setMethod("profMat", signature(object = "XCMSnExp"), function(object, }) -##' @title Accessing feature grouping results +##' @title Accessing mz-rt feature data values ##' ##' @description \code{groupval,XCMSnExp}: extract a \code{matrix} for feature -##' values with rows representing feature groups and columns samples. Parameter -##' \code{value} allows to define which column from the \code{\link{features}} -##' matrix should be returned. Multiple features from the same sample can be -##' assigned to a feature group. Parameter \code{method} allows to specify the -##' method to be used in such cases to chose from which of the features the value -##' should be returned. -##' -##' @param object A \code{\link{XCMSnExp}} object providing the feature grouping -##' results. +##' values with rows representing features and columns samples. Parameter +##' \code{value} allows to define which column from the \code{\link{chromPeaks}} +##' matrix should be returned. Multiple chromatographic peaks from the same +##' sample can be assigned to a feature. Parameter \code{method} allows to +##' specify the method to be used in such cases to chose from which of the peaks +##' the value should be returned. +##' +##' @param object A \code{\link{XCMSnExp}} object providing the feature +##' definitions. ##' ##' @param method \code{character} specifying the method to resolve -##' multi-feature mappings within the same sample, i.e. to define the -##' \emph{representative} feature for a feature groups in samples where more than -##' one feature was assigned to the feature group. If \code{"medret"}: select the -##' feature closest to the median retention time of the feature group. -##' If \code{"maxint"}: select the feature yielding the largest signal. +##' multi-peak mappings within the same sample, i.e. to define the +##' \emph{representative} peak for a feature in samples where more than +##' one peak was assigned to the feature. If \code{"medret"}: select the +##' peak closest to the median retention time of the feature. +##' If \code{"maxint"}: select the peak yielding the largest signal. ##' ##' @param value \code{character} specifying the name of the column in -##' \code{features(object)} that should be returned or \code{"index"} (the -##' default) to return the index of the feature in the \code{features(object)} -##' matrix corresponding to the \emph{representative} feature for the feature -##' group in the respective sample. +##' \code{chromPeaks(object)} that should be returned or \code{"index"} (the +##' default) to return the index of the peak in the \code{chromPeaks(object)} +##' matrix corresponding to the \emph{representative} peak for the feature +##' in the respective sample. ##' ##' @param intensity \code{character} specifying the name of the column in the -##' \code{features(objects)} matrix containing the intensity value of the -##' feature that should be used for the conflict resolution if +##' \code{chromPeaks(objects)} matrix containing the intensity value of the +##' peak that should be used for the conflict resolution if ##' \code{method = "maxint"}. ##' ##' @return For \code{groupval}: a \code{matrix} with feature values, columns -##' representing samples, rows feature groups. The order of the feature groups -##' matches the order found in the \code{featureGroups(object)} \code{DataFrame}. -##' An \code{NA} is reported for feature groups without corresponding -##' features in the respective sample(s). +##' representing samples, rows features. The order of the features +##' matches the order found in the \code{featureDefinitions(object)} +##' \code{DataFrame}. An \code{NA} is reported for features without corresponding +##' chromatographic peak in the respective sample(s). ##' ##' @author Johannes Rainer ##' ##' @seealso ##' \code{\link{XCMSnExp}} for information on the data object. -##' \code{\link{featureGroups}} to extract the \code{DataFrame} with the -##' feature group definition. -##' \code{\link{hasAlignedFeatures}} to evaluate whether the -##' \code{\link{XCMSnExp}} provides feature groups. +##' \code{\link{featureDefinitions}} to extract the \code{DataFrame} with the +##' feature definitions. +##' \code{\link{hasFeatures}} to evaluate whether the +##' \code{\link{XCMSnExp}} provides feature definitions. ##' -##' @rdname XCMSnExp-feature-grouping-results +##' @rdname XCMSnExp-peak-grouping-results setMethod("groupval", signature(object = "XCMSnExp"), function(object, method = c("medret", "maxint"), value = "index", intensity = "into") { ## Input argument checkings - if (!hasAlignedFeatures(object)) - stop("No feature groups present! Use 'groupFeatures' first.") - if (!hasDetectedFeatures(object)) - stop("No detected features present! Use 'detectFeatures' first.") + if (!hasFeatures(object)) + stop("No peak groups present! Use 'groupChromPeaks' first.") + if (!hasChromPeaks(object)) + stop("No detected chromatographic peaks present! Use ", + "'findChromPeaks' first.") method <- match.arg(method) fNames <- basename(fileNames(object)) nSamples <- seq_along(fNames) ## Copy all of the objects to avoid costly S4 method calls - ## improves speed at the cost of higher memory demand. - fts <- features(object) - grps <- featureGroups(object) - ftIdx <- grps$featureidx + fts <- chromPeaks(object) + grps <- featureDefinitions(object) + ftIdx <- grps$peakidx ## Match columns idx_rt <- match("rt", colnames(fts)) idx_int <- match(intensity, colnames(fts)) @@ -1580,7 +1637,7 @@ setMethod("groupval", if (value != "index") { if (!any(colnames(fts) == value)) stop("Column '", value, - "' not present in the features matrix!") + "' not present in the chromatographic peaks matrix!") vals <- fts[vals, value] dim(vals) <- c(length(ftIdx), length(nSamples)) } @@ -1590,3 +1647,59 @@ setMethod("groupval", ## base::round(grps$rtmed), sep = "/") return(vals) }) + +#' @title Extracting chromatograms +#' +#' @description \code{extractChromatograms}: the method allows to extract +#' chromatograms from \code{\link[MSnbase]{OnDiskMSnExp}} and +#' \code{\link{XCMSnExp}} objects. +#' +#' @details Arguments \code{rt} and \code{mz} allow to specify the MS +#' data slice from which the chromatogram should be extracted. By specifying the +#' function to be used to aggregate intensity values across the mz range for the +#' same retention time it is possible to extract e.g. a +#' \emph{total ion chromatogram} (TIC, \code{aggregationFun = "sum"}) or a +#' \emph{base peak chromatogram} (BPC, \code{aggregationFun = "max"}). +#' +#' @param object Either a \code{\link[MSnbase]{OnDiskMSnExp}} or +#' \code{\link{XCMSnExp}} object from which the chromatograms should be extracted. +#' +#' @param rt \code{numeric(2)} defining the lower and upper boundary for the +#' retention time range. If not specified, the full retention time range of the +#' original data will be used. It is also possible to submit a \code{numeric(1)} +#' in which case \code{range} is called on it to transform it to a +#' \code{numeric(2)}. +#' +#' @param mz \code{numeric(2)} defining the lower and upper mz value for the +#' MS data slice. If not specified, the chromatograms will be calculated on the +#' full mz range. It is also possible to submit a \code{numeric(1)} in which case +#' \code{range} is called on it to transform it to a \code{numeric(2)}. +#' +#' @param adjustedRtime For \code{extractChromatograms,XCMSnExp}: whether the +#' adjusted (\code{adjustedRtime = TRUE}) or raw retention times +#' (\code{adjustedRtime = FALSE}) should be used for filtering and returned in +#' the resulting \code{\link{Chromatogram}} object. Adjusted retention times are +#' used by default if available. +#' +#' @param aggregationFun \code{character} specifying the function to be used to +#' aggregate intensity values across the mz value range for the same retention +#' time. Allowed values are \code{"sum"}, \code{"max"}, \code{"mean"} and +#' \code{"min"}. +#' +#' @author Johannes Rainer +#' +#' @seealso \code{\link{XCMSnExp}} for the data object. +#' \code{\link{Chromatogram}} for the object representing chromatographic data. +#' +#' @noRd +#' @rdname extractChromatograms-method +setMethod("extractChromatograms", + signature(object = "XCMSnExp"), + function(object, rt, mz, adjustedRtime = hasAdjustedRtime(object), + aggregationFun = "sum") { + return(.extractChromatogram(x = object, rt = rt, mz = mz, + aggregationFun = aggregationFun, + adjusted = adjustedRtime)) + }) + + diff --git a/R/methods-xcmsRaw.R b/R/methods-xcmsRaw.R index c5409c7d7..c73c2c158 100755 --- a/R/methods-xcmsRaw.R +++ b/R/methods-xcmsRaw.R @@ -309,46 +309,48 @@ setMethod("findPeaks.matchedFilter_orig", "xcmsRaw", ############################################################ ## findPeaks.matchedFilter -##' @title Feature detection in the chromatographic time domain +##' @title Peak detection in the chromatographic time domain ##' ##' @aliases findPeaks.matchedFilter -##' @description Find features (peaks) in the chromatographic time domain of the -##' profile matrix. For more details see \code{\link{do_detectFeatures_matchedFilter}}. -##' @param object The \code{\linkS4class{xcmsRaw}} object on which feature detection +##' @description Find peaks in the chromatographic time domain of the +##' profile matrix. For more details see +##' \code{\link{do_findChromPeaks_matchedFilter}}. +##' @param object The \code{\linkS4class{xcmsRaw}} object on which peak detection ##' should be performed. -##' @inheritParams featureDetection-matchedFilter +##' @inheritParams findChromPeaks-matchedFilter ##' @param step numeric(1) specifying the width of the bins/slices in m/z ##' dimension. ##' @param sleep (DEFUNCT). This parameter is no longer functional, as it would cause ##' problems in parallel processing mode. ##' @param scanrange Numeric vector defining the range of scans to which the original -##' \code{object} should be sub-setted before feature detection. +##' \code{object} should be sub-setted before peak detection. ##' @author Colin A. Smith -##' @return A matrix, each row representing an intentified feature, with columns: +##' @return A matrix, each row representing an intentified chromatographic peak, +##' with columns: ##' \describe{ -##' \item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} -##' \item{rt}{Retention time of the feature's midpoint.} -##' \item{rtmin}{Minimum retention time of the feature.} -##' \item{rtmax}{Maximum retention time of the feature.} -##' \item{into}{Integrated (original) intensity of the feature.} +##' \item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +##' \item{mzmin}{Minimum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} +##' \item{rt}{Retention time of the peak's midpoint.} +##' \item{rtmin}{Minimum retention time of the peak.} +##' \item{rtmax}{Maximum retention time of the peak.} +##' \item{into}{Integrated (original) intensity of the peak.} ##' \item{intf}{Integrated intensity of the filtered peak.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{maxf}{Maximum intensity of the filtered peak.} -##' \item{i}{Rank of feature in merged EIC (\code{<= max}).} -##' \item{sn}{Signal to noise ratio of the feature} +##' \item{i}{Rank of peak in merged EIC (\code{<= max}).} +##' \item{sn}{Signal to noise ratio of the peak.} ##' } ##' @references ##' Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and ##' Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite ##' Profiling Using Nonlinear Peak Alignment, Matching, and Identification" ##' \emph{Anal. Chem.} 2006, 78:779-787. -##' @family Old feature detection methods +##' @family Old peak detection methods ##' @seealso \code{\link{matchedFilter}} for the new user interface. ##' \code{\linkS4class{xcmsRaw}}, -##' \code{\link{do_detectFeatures_matchedFilter}} for the core function -##' performing the feature detection. +##' \code{\link{do_findChromPeaks_matchedFilter}} for the core function +##' performing the peak detection. setMethod("findPeaks.matchedFilter", "xcmsRaw", function(object, fwhm = 30, sigma = fwhm/2.3548, max = 5, snthresh = 10, step = 0.1, steps = 2, @@ -430,7 +432,7 @@ setMethod("findPeaks.matchedFilter", "xcmsRaw", distance <- 0 baseValue <- 0 } - res <- do_detectFeatures_matchedFilter(mz = object@env$mz, + res <- do_findChromPeaks_matchedFilter(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = diff(c(object@scanindex, @@ -486,7 +488,7 @@ setMethod("findPeaks.centWave", "xcmsRaw", function(object, ppm=25, object <- object[scanrange[1]:scanrange[2]] vps <- diff(c(object@scanindex, length(object@env$mz))) - res <- do_detectFeatures_centWave(mz = object@env$mz, + res <- do_findChromPeaks_centWave(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = vps, @@ -923,9 +925,9 @@ setMethod("findPeaks.centWave", "xcmsRaw", function(object, ppm=25, ############################################################ ## findPeaks.centWaveWithPredictedIsotopeROIs -## Performs first a centWave analysis and based on the identified features +## Performs first a centWave analysis and based on the identified peaks ## defines ROIs for a second centWave run to check for presence of -## predicted isotopes for the first features. +## predicted isotopes for the first peaks. setMethod("findPeaks.centWaveWithPredictedIsotopeROIs", "xcmsRaw", function(object, ppm = 25, peakwidth = c(20,50), snthresh = 10, prefilter = c(3,100), mzCenterFun = "wMean", integrate = 1, @@ -952,7 +954,7 @@ setMethod("findPeaks.centWaveWithPredictedIsotopeROIs", "xcmsRaw", object <- object[scanrange[1]:scanrange[2]] vps <- diff(c(object@scanindex, length(object@env$mz))) - res <- do_detectFeatures_centWaveWithPredIsoROIs(mz = object@env$mz, + res <- do_findChromPeaks_centWaveWithPredIsoROIs(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = vps, @@ -976,52 +978,6 @@ setMethod("findPeaks.centWaveWithPredictedIsotopeROIs", "xcmsRaw", ) invisible(new("xcmsPeaks", res)) }) -## ## Original code: TODO REMOVE ME once method is validated. -## .centWaveWithPredictedIsotopeROIs <- function(object, ppm = 25, -## peakwidth = c(20,50), snthresh = 10, -## prefilter = c(3,100), -## mzCenterFun = "wMean", integrate = 1, -## mzdiff = -0.001, fitgauss = FALSE, -## scanrange = numeric(), -## noise = 0, sleep = 0, -## verbose.columns = FALSE, -## ROI.list = list(), -## firstBaselineCheck = TRUE, -## roiScales = NULL, -## snthreshIsoROIs = 6.25, -## maxcharge = 3, -## maxiso = 5, -## mzIntervalExtension = TRUE) { -## ## perform tradictional peak picking -## xcmsPeaks <- findPeaks.centWave( -## object = object, ppm = ppm, peakwidth = peakwidth, -## snthresh = snthresh, prefilter = prefilter, -## mzCenterFun = mzCenterFun, integrate = integrate, -## mzdiff = mzdiff, fitgauss = fitgauss, scanrange = scanrange, -## noise = noise, sleep = sleep, verbose.columns = TRUE, -## ROI.list = ROI.list, firstBaselineCheck = firstBaselineCheck, -## roiScales = roiScales) - -## return( -## .addPredictedIsotopeFeatures(object = object, -## ppm = ppm, -## peakwidth = peakwidth, -## prefilter = prefilter, -## mzCenterFun = mzCenterFun, -## integrate = integrate, -## mzdiff = mzdiff, -## fitgauss = fitgauss, -## scanrange = scanrange, -## noise = noise, -## sleep = sleep, -## verbose.columns = verbose.columns, -## xcmsPeaks = xcmsPeaks, -## snthresh = snthreshIsoROIs, -## maxcharge = maxcharge, -## maxiso = maxiso, -## mzIntervalExtension = mzIntervalExtension -## )) -## } setMethod("findPeaks.addPredictedIsotopeFeatures", "xcmsRaw", function(object, ppm = 25, peakwidth = c(20,50), @@ -1051,7 +1007,7 @@ setMethod("findPeaks.addPredictedIsotopeFeatures", stop("Pparameter >xcmsPeaks< is not of class 'xcmsPeaks'!\n") vps <- diff(c(object@scanindex, length(object@env$mz))) - res <- do_detectFeatures_addPredIsoROIs(mz = object@env$mz, + res <- do_findChromPeaks_addPredIsoROIs(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = vps, @@ -1065,410 +1021,21 @@ setMethod("findPeaks.addPredictedIsotopeFeatures", fitgauss = fitgauss, noise = noise, verboseColumns = verbose.columns, - features. = xcmsPeaks@.Data, + peaks. = xcmsPeaks@.Data, maxCharge = maxcharge, maxIso = maxiso, mzIntervalExtension = mzIntervalExtension ) invisible(new("xcmsPeaks", res)) }) -## ## Original code: TODO REMOVE ME once method is validated. -## .addPredictedIsotopeFeatures <- -## function(object, ppm = 25, peakwidth = c(20,50), -## prefilter = c(3,100), mzCenterFun = "wMean", -## integrate = 1, mzdiff = -0.001, fitgauss = FALSE, -## scanrange = numeric(), noise=0, ## noise.local=TRUE, -## sleep = 0, verbose.columns = FALSE, -## xcmsPeaks, snthresh = 6.25, maxcharge = 3, -## maxiso = 5, mzIntervalExtension = TRUE) { -## if(nrow(xcmsPeaks) == 0){ -## warning("Warning: There are no features (parameter >xcmsPeaks<) for the prediction of isotope ROIs !\n") -## return(xcmsPeaks) -## } -## if(class(xcmsPeaks) != "xcmsPeaks") -## stop("Error: parameter >xcmsPeaks< is not of class 'xcmsPeaks' ! \n") -## if(any(is.na(match(x = c("scmin", "scmax"), table = colnames(xcmsPeaks))))) -## stop("Error: peak list >xcmsPeaks< is missing the columns 'scmin' and 'scmax' ! Please set parameter >verbose.columns< to TRUE for peak picking with 'centWave' and try again ! \n") - -## ############################################################################## -## ## predict new ROIs -## newROI.list <- do_predictIsotopeROIs(object, xcmsPeaks, ppm, maxcharge, -## maxiso, mzIntervalExtension) -## if(length(newROI.list) == 0) -## return(xcmsPeaks) - -## ## HOOK_1 -## ## return(newROI.list) -## ############################################################################## -## ## perform peak picking for predicted ROIs -## roiScales <- unlist(lapply(X = newROI.list, FUN = function(x){x$scale})) -## xcmsPeaks2 <- findPeaks.centWave( -## object = object, ppm=ppm, peakwidth=peakwidth, snthresh=snthresh, -## prefilter=prefilter, mzCenterFun=mzCenterFun, integrate=integrate, mzdiff=mzdiff, -## fitgauss=fitgauss, scanrange=scanrange, noise=noise, ## noise.local=noise.local, -## sleep=sleep, verbose.columns=verbose.columns, ROI.list=newROI.list, firstBaselineCheck=FALSE, roiScales=roiScales -## ) - -## ## HOOK_2 -## ## return(xcmsPeaks2) -## if(nrow(xcmsPeaks2) > 0){ -## ## remove NaN values -## rowsWithNaN <- which(apply(X = xcmsPeaks2[, c("mz", "mzmin", "mzmax", "rt", "rtmin", "rtmax")], MARGIN = 1, FUN = function(x){any(is.na(x))})) -## if(length(rowsWithNaN) > 0) -## xcmsPeaks2 <- xcmsPeaks2[-rowsWithNaN, ] - -## noArea <- which((xcmsPeaks2[, "mzmax"] - xcmsPeaks2[, "mzmin"]) == 0 || (xcmsPeaks2[, "rtmax"] - xcmsPeaks2[, "rtmin"]) == 0) -## if(length(noArea) > 0) -## xcmsPeaks2 <- xcmsPeaks2[-noArea, ] -## } - -## ## HOOK_3 -## ## return(xcmsPeaks2) ## Compare these results - -## ## make present peaks and new peaks distinct by removing overlapping peaks -## if(nrow(xcmsPeaks2) > 0){ -## ## remove ROIs which are already there -## overlapProportionThreshold <- 0.01 -## drop <- apply(X = xcmsPeaks2, MARGIN = 1, FUN = function(x){ -## roiInt <- x[["into"]] -## peakInt <- xcmsPeaks[, "into"] -## roiMzMin <- x[["mzmin"]] -## roiMzMax <- x[["mzmax"]] -## peakMzMin <- xcmsPeaks[, "mzmin"] -## peakMzMax <- xcmsPeaks[, "mzmax"] -## roiMzCenter = (roiMzMin + roiMzMax ) / 2; -## peakMzCenter = (peakMzMin + peakMzMax) / 2; -## roiMzRadius = (roiMzMax - roiMzMin ) / 2; -## peakMzRadius = (peakMzMax - peakMzMin) / 2; -## overlappingmz <- abs(peakMzCenter - roiMzCenter) <= (roiMzRadius + peakMzRadius) - -## roiRtMin <- x[["rtmin"]] -## roiRtMax <- x[["rtmax"]] -## peakRtMin <- xcmsPeaks[, "rtmin"] -## peakRtMax <- xcmsPeaks[, "rtmax"] -## roiRtCenter = (roiRtMin + roiRtMax ) / 2; -## peakRtCenter = (peakRtMin + peakRtMax) / 2; -## roiRtRadius = (roiRtMax - roiRtMin ) / 2; -## peakRtRadius = (peakRtMax - peakRtMin) / 2; -## overlappingrt <- abs(peakRtCenter - roiRtCenter) <= (roiRtRadius + peakRtRadius) - -## overlapping <- overlappingmz & overlappingrt - -## overlappingPeaks <- which(overlapping) -## overlappingPeaksInt <- peakInt[overlappingPeaks] - -## removeROI <- FALSE -## peaksToRemove <- NULL -## if(any(overlapping)){ -## if(any(overlappingPeaksInt > roiInt)) -## return(TRUE) -## else -## return(overlappingPeaks) -## } else { -## ## no overlap -## return(FALSE) -## } - -## ## Will never reach the condition below. -## ## return(isOverlap) -## }) - -## removeROI <- unlist(lapply(X = drop, FUN = function(x){ -## if(is.logical(x)){ -## return(x) -## } else { -## return(FALSE) -## } -## })) -## removePeaks <- unique(unlist(lapply(X = drop, FUN = function(x){ -## if(is.logical(x)){ -## return(NULL) -## } else { -## return(x) -## } -## }))) - -## if(length(removePeaks) > 0) -## xcmsPeaks <- xcmsPeaks[-removePeaks, ] -## xcmsPeaks2 <- xcmsPeaks2[!removeROI, ] -## } - -## ## merge result with present results -## if(!verbose.columns) -## xcmsPeaks <- xcmsPeaks[, c("mz", "mzmin", "mzmax", "rt", "rtmin", "rtmax", "into", "intb", "maxo", "sn")] - -## xcmsPeaks <- rbind(xcmsPeaks, xcmsPeaks2) - -## invisible(new("xcmsPeaks", xcmsPeaks)) -## } - -## ## Original code: TODO REMOVE ME once method is validated. -## removeROIsOutOfRange <- function(object, roi.matrix){ -## ## c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity") -## numberOfROIs <- nrow(roi.matrix) - -## minMz <- min(object@env$mz) -## maxMz <- max(object@env$mz) -## minScanRange <- 1 -## maxScanRange <- length(object@scantime) -## #minScanRange <- min(object@scantime) -## #maxScanRange <- max(object@scantime) - -## roiWithinRange <- rep(x = TRUE, times = numberOfROIs) -## roiWithinRange <- roiWithinRange & (roi.matrix[, "mzmin"] >= minMz) -## roiWithinRange <- roiWithinRange & (roi.matrix[, "mzmax"] <= maxMz) -## roiWithinRange <- roiWithinRange & (roi.matrix[, "scmin"] >= minScanRange) -## roiWithinRange <- roiWithinRange & (roi.matrix[, "scmax"] <= maxScanRange) - -## roi.matrix <- roi.matrix[roiWithinRange, ] - -## return(roi.matrix) -## } -## ## Original code: TODO REMOVE ME once method is validated. -## removeROIsWithoutSignal <- function(object, roi.matrix, intensityThreshold){ -## ## c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity") -## numberOfROIs <- nrow(roi.matrix) -## sufficientSignalThere <- rep(x = TRUE, times = numberOfROIs) -## for(roiIdx in seq_len(numberOfROIs)){ -## mzrange <- c(roi.matrix[[roiIdx, "mzmin"]], roi.matrix[[roiIdx, "mzmax"]]) -## scanrange <- c(roi.matrix[[roiIdx, "scmin"]], roi.matrix[[roiIdx, "scmax"]]) -## mzROI.EIC <- rawEIC(object, mzrange=mzrange, scanrange=scanrange) -## sumOfIntensities <- sum(mzROI.EIC$intensity) - -## if(sumOfIntensities < intensityThreshold) -## sufficientSignalThere[[roiIdx]] <- FALSE -## } -## roi.matrix <- roi.matrix[sufficientSignalThere, ] - -## return(roi.matrix) -## } - -## ## Original code: TODO REMOVE ME once method is validated. -## createAdditionalROIs <- function(object, ROI.list, ppm, addNewIsotopeROIs, maxcharge, maxiso, mzIntervalExtension, addNewAdductROIs, polarity){ -## ############################################################################################### -## ## isotope ROIs -## if(addNewIsotopeROIs){ -## ## init -## isotopeDistance <- 1.0033548378 -## charges <- 1:maxcharge -## isos <- 1:maxiso - -## isotopeStepSizesForCharge <- list() -## for(charge in charges) -## isotopeStepSizesForCharge[[charge]] <- isotopeDistance / charge - -## isotopeStepSizes <- list() -## for(charge in charges) -## isotopeStepSizes[[charge]] <- list() - -## for(charge in charges) -## for(iso in isos) -## isotopeStepSizes[[charge]][[iso]] <- isotopeStepSizesForCharge[[charge]] * iso - -## isotopePopulationMz <- list() -## for(charge in charges) -## for(iso in isos) -## isotopePopulationMz[[length(isotopePopulationMz) + 1]] <- isotopeStepSizes[[charge]][[iso]] -## isotopePopulationMz <- unlist(unique(isotopePopulationMz)) - -## numberOfIsotopeROIs <- length(ROI.list) * length(isotopePopulationMz) -## isotopeROIs.matrix <- matrix(nrow = numberOfIsotopeROIs, ncol = 8) -## colnames(isotopeROIs.matrix) <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity", "scale") - -## ## complement found ROIs -## for(roiIdx in 1:(length(ROI.list))){ -## for(mzIdx in 1:length(isotopePopulationMz)){ -## ## create new ROI! -## mzDifference <- isotopePopulationMz[[mzIdx]] -## if(mzIntervalExtension) -## ## extend m/z interval for weak peaks -## #mzIntervalExtension <- ROI.list[[roiIdx]]$mz * ppm / 1E6 -## mzIntervalExtension <- (ROI.list[[roiIdx]]$mzmax - ROI.list[[roiIdx]]$mzmin) * 2 -## else -## mzIntervalExtension <- 0 - -## idx <- (roiIdx - 1) * length(isotopePopulationMz) + mzIdx -## isotopeROIs.matrix[idx, ] <- c( -## ROI.list[[roiIdx]]$mz + mzDifference,## XXX not used! -## ROI.list[[roiIdx]]$mzmin + mzDifference - mzIntervalExtension, -## ROI.list[[roiIdx]]$mzmax + mzDifference + mzIntervalExtension, -## ROI.list[[roiIdx]]$scmin, -## ROI.list[[roiIdx]]$scmax, -## ROI.list[[roiIdx]]$length,## XXX not used! -## -1, #ROI.list[[roiIdx]]$intensity ## XXX not used! -## ROI.list[[roiIdx]]$scale -## ) -## } -## } -## } else { -## ## no isotope ROIs -## isotopeROIs.matrix <- matrix(nrow = 0, ncol = 8) -## colnames(isotopeROIs.matrix) <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity", "scale") -## } -## ############################################################################################### -## ## adduct ROIs -## if(addNewAdductROIs){ -## ## considered adduct distances -## ## reference: Huang N.; Siegel M.M.1; Kruppa G.H.; Laukien F.H.; J Am Soc Mass Spectrom 1999, 10, 1166–1173; Automation of a Fourier transform ion cyclotron resonance mass spectrometer for acquisition, analysis, and e-mailing of high-resolution exact-mass electrospray ionization mass spectral data -## ## see also for contaminants: Interferences and contaminants encountered in modern mass spectrometry (Bernd O. Keller, Jie Sui, Alex B. Young and Randy M. Whittal, ANALYTICA CHIMICA ACTA, 627 (1): 71-81) - -## mH <- 1.0078250322 -## mNa <- 22.98976928 -## mK <- 38.96370649 -## mC <- 12 -## mN <- 14.003074004 -## mO <- 15.994914620 -## mS <- 31.972071174 -## mCl <- 34.9688527 -## mBr <- 78.918338 -## mF <- 18.998403163 -## mDMSO <- mC*2+mH*6+mS+mO # dimethylsulfoxid -## mACN <- mC*2+mH*3+mN # acetonitril -## mIsoProp <- mC*3+mH*8+mO # isopropanol -## mNH4 <- mN+mH*4 # ammonium -## mCH3OH <- mC+mH*3+mO+mH # methanol -## mH2O <- mH*2+mO # water -## mFA <- mC+mH*2+mO*2 # formic acid -## mHAc <- mC+mH*3+mC+mO+mO+mH # acetic acid -## mTFA <- mC+mF*3+mC+mO+mO+mH # trifluoroacetic acid - -## switch(polarity, -## "positive"={ -## adductPopulationMz <- unlist(c( -## ## [M+H]+ to [M+H]+ (Reference) -## function(mass){ mass-mH+mNH4 }, ## [M+H]+ to [M+NH4]+ -## function(mass){ mass-mH+mNa }, ## [M+H]+ to [M+Na]+ -## function(mass){ mass+mCH3OH }, ## [M+H]+ to [M+CH3OH+H]+ -## function(mass){ mass-mH+mK }, ## [M+H]+ to [M+K]+ -## function(mass){ mass+mACN }, ## [M+H]+ to [M+ACN+H]+ -## function(mass){ mass-2*mH+2*mNa }, ## [M+H]+ to [M+2Na-H]+ -## function(mass){ mass+mIsoProp }, ## [M+H]+ to [M+IsoProp+H]+ -## function(mass){ mass-mH+mACN+mNa }, ## [M+H]+ to [M+ACN+Na]+ -## function(mass){ mass-2*mH+2*mK }, ## [M+H]+ to [M+2K-H]+ -## function(mass){ mass+mDMSO }, ## [M+H]+ to [M+DMSO+H]+ -## function(mass){ mass+2*mACN }, ## [M+H]+ to [M+2*ACN+H]+ -## function(mass){ mass+mIsoProp+mNa }, ## [M+H]+ to [M+IsoProp+Na+H]+ TODO double-charged? -## function(mass){ (mass-mH)*2+mH }, ## [M+H]+ to [2M+H]+ -## function(mass){ (mass-mH)*2+mNH4 }, ## [M+H]+ to [2M+NH4]+ -## function(mass){ (mass-mH)*2+mNa }, ## [M+H]+ to [2M+Na]+ -## function(mass){ (mass-mH)*2+mK }, ## [M+H]+ to [2M+K]+ -## function(mass){ (mass-mH)*2+mACN+mH }, ## [M+H]+ to [2M+ACN+H]+ -## function(mass){ (mass-mH)*2+mACN+mNa }, ## [M+H]+ to [2M+ACN+Na]+ -## function(mass){((mass-mH)*2+3*mH2O+2*mH)/2 }, ## [M+H]+ to [2M+3*H2O+2*H]2+ -## function(mass){ (mass+mH)/2 }, ## [M+H]+ to [M+2*H]2+ -## function(mass){ (mass+mNH4)/2 }, ## [M+H]+ to [M+H+NH4]2+ -## function(mass){ (mass+mNa)/2 }, ## [M+H]+ to [M+H+Na]2+ -## function(mass){ (mass+mK)/2 }, ## [M+H]+ to [M+H+K]2+ -## function(mass){ (mass+mACN+mH)/2 }, ## [M+H]+ to [M+ACN+2*H]2+ -## function(mass){ (mass-mH+2*mNa)/2 }, ## [M+H]+ to [M+2*Na]2+ -## function(mass){ (mass+2*mACN+mH)/2 }, ## [M+H]+ to [M+2*ACN+2*H]2+ -## function(mass){ (mass+3*mACN+mH)/2 }, ## [M+H]+ to [M+3*ACN+2*H]2+ -## function(mass){ (mass+2*mH)/3 }, ## [M+H]+ to [M+3*H]3+ -## function(mass){ (mass+mH+mNa)/3 }, ## [M+H]+ to [M+2*H+Na]3+ -## function(mass){ (mass+2*mNa)/3 }, ## [M+H]+ to [M+H+2*Na]3+ -## function(mass){ (mass-mH+3*mNa)/3 } ## [M+H]+ to [M+3*Na]3+ -## )) -## }, -## "negative"={ -## adductPopulationMz <- unlist(c( -## ## [M-H]+ to [M-H]+ (Reference) -## function(mass){ mass-mH2O }, ## [M-H]+ to [M-H2O-H]+ -## function(mass){ mass-mH+mNa }, ## [M-H]+ to [M+Na-2*H]+ -## function(mass){ mass+mH+mCl }, ## [M-H]+ to [M+Cl]+ -## function(mass){ mass-mH+mK }, ## [M-H]+ to [M+K-2*H]+ -## function(mass){ mass+mFA }, ## [M-H]+ to [M+FA-H]+ -## function(mass){ mass+mHAc }, ## [M-H]+ to [M+HAc-H]+ -## function(mass){ mass+mH+mBr }, ## [M-H]+ to [M+Br]+ -## function(mass){ mass+mTFA }, ## [M-H]+ to [M+TFA-H]+ -## function(mass){ (mass+mH)*2-mH }, ## [M-H]+ to [2M-H]+ -## function(mass){ (mass+mH)*2+mFA-mH }, ## [M-H]+ to [2M+FA-H]+ -## function(mass){ (mass+mH)*2+mHAc-mH }, ## [M-H]+ to [2M+HAc-H]+ -## function(mass){ (mass+mH)*3-mH }, ## [M-H]+ to [3M-H]+ -## function(mass){ (mass-mH)/2 }, ## [M-H]+ to [M-2*H]2+ -## function(mass){ (mass-2*mH)/3 } ## [M-H]+ to [M-3*H]3+ -## )) -## }, -## "unknown"={ -## warning(paste("Unknown polarity! No adduct ROIs have been added.", sep = "")) -## }, -## stop(paste("Unknown polarity (", polarity, ")!", sep = "")) -## ) - -## numberOfAdductROIs <- length(ROI.list) * length(adductPopulationMz) -## adductROIs.matrix <- matrix(nrow = numberOfAdductROIs, ncol = 8) -## colnames(adductROIs.matrix) <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity", "scale") - -## for(roiIdx in 1:(length(ROI.list))){ -## for(mzIdx in 1:length(adductPopulationMz)){ -## ## create new ROI! -## mzDifference <- adductPopulationMz[[mzIdx]](ROI.list[[roiIdx]]$mz) -## idx <- (roiIdx - 1) * length(adductPopulationMz) + mzIdx -## if(ROI.list[[roiIdx]]$mzmin + mzDifference > 0){ -## adductROIs.matrix[idx, ] <- c( -## ROI.list[[roiIdx]]$mz + mzDifference,## XXX not used! -## ROI.list[[roiIdx]]$mzmin + mzDifference, -## ROI.list[[roiIdx]]$mzmax + mzDifference, -## ROI.list[[roiIdx]]$scmin, -## ROI.list[[roiIdx]]$scmax, -## ROI.list[[roiIdx]]$length,## XXX not used! -## -1, #ROI.list[[roiIdx]]$intensity ## XXX not used! -## ROI.list[[roiIdx]]$scale -## ) -## } -## } -## } -## } else { -## ## no adduct ROIs -## adductROIs.matrix <- matrix(nrow = 0, ncol = 8) -## colnames(adductROIs.matrix) <- c("mz", "mzmin", "mzmax", "scmin", "scmax", "length", "intensity", "scale") -## } - -## numberOfAdditionalIsotopeROIsUnfiltered <- nrow(isotopeROIs.matrix) -## numberOfAdditionalAdductROIsUnfiltered <- nrow(adductROIs.matrix ) -## numberOfAdditionalROIsUnfiltered <- numberOfAdditionalIsotopeROIsUnfiltered + numberOfAdditionalAdductROIsUnfiltered -## newROI.matrixUnfiltered <- rbind(isotopeROIs.matrix, adductROIs.matrix) - -## ############################################################################################### -## ## filter out m/z's out of range and without sufficient intensity -## intensityThreshold <- 10 - -## if(addNewIsotopeROIs) isotopeROIs.matrix <- removeROIsOutOfRange(object, isotopeROIs.matrix) -## if(addNewAdductROIs) adductROIs.matrix <- removeROIsOutOfRange(object, adductROIs.matrix) -## if(addNewIsotopeROIs) isotopeROIs.matrix <- removeROIsWithoutSignal(object, isotopeROIs.matrix, intensityThreshold) -## if(addNewAdductROIs) adductROIs.matrix <- removeROIsWithoutSignal(object, adductROIs.matrix, intensityThreshold) - -## numberOfAdditionalIsotopeROIs <- nrow(isotopeROIs.matrix) -## numberOfAdditionalAdductROIs <- nrow(adductROIs.matrix ) -## numberOfAdditionalROIs <- numberOfAdditionalIsotopeROIs + numberOfAdditionalAdductROIs - -## ############################################################################################### -## ## box -## newROI.matrix <- rbind(isotopeROIs.matrix, adductROIs.matrix) - -## resultObj <- list() -## ## unfiltered -## resultObj$newROI.matrixUnfiltered <- newROI.matrixUnfiltered -## resultObj$numberOfAdditionalROIsUnfiltered <- numberOfAdditionalROIsUnfiltered -## resultObj$numberOfAdditionalIsotopeROIsUnfiltered <- numberOfAdditionalIsotopeROIsUnfiltered -## resultObj$numberOfAdditionalAdductROIsUnfiltered <- numberOfAdditionalAdductROIsUnfiltered -## ## filtered -## resultObj$newROI.matrix <- newROI.matrix -## resultObj$numberOfAdditionalROIs <- numberOfAdditionalROIs -## resultObj$numberOfAdditionalIsotopeROIs <- numberOfAdditionalIsotopeROIs -## resultObj$numberOfAdditionalAdductROIs <- numberOfAdditionalAdductROIs - -## return(resultObj) -## } - - ############################################################ ## findPeaks.MSW -##' @title Feature detection for single-spectrum non-chromatography MS data +##' @title Peak detection for single-spectrum non-chromatography MS data ##' @aliases findPeaks.MSW ##' -##' @description This method performs feature detection in mass spectrometry +##' @description This method performs peak detection in mass spectrometry ##' direct injection spectrum using a wavelet based algorithm. ##' ##' @details This is a wrapper around the peak picker in Bioconductor's @@ -1476,30 +1043,30 @@ setMethod("findPeaks.addPredictedIsotopeFeatures", ##' \code{\link[MassSpecWavelet]{peakDetectionCWT}} and ##' \code{\link[MassSpecWavelet]{tuneInPeakInfo}} functions. ##' -##' @inheritParams featureDetection-MSW -##' @inheritParams featureDetection-centWave -##' @param object The \code{\linkS4class{xcmsRaw}} object on which feature +##' @inheritParams findPeaks-MSW +##' @inheritParams findChromPeaks-centWave +##' @param object The \code{\linkS4class{xcmsRaw}} object on which peak ##' detection should be performed. -##' @param verbose.columns Logical whether additional feature meta data columns +##' @param verbose.columns Logical whether additional peak meta data columns ##' should be returned. ##' ##' @return -##' A matrix, each row representing an intentified feature, with columns: +##' A matrix, each row representing an intentified peak, with columns: ##' \describe{ -##' \item{mz}{m/z value of the feature at the centroid position.} -##' \item{mzmin}{Minimum m/z of the feature.} -##' \item{mzmax}{Maximum m/z of the feature.} +##' \item{mz}{m/z value of the peak at the centroid position.} +##' \item{mzmin}{Minimum m/z of the peak.} +##' \item{mzmax}{Maximum m/z of the peak.} ##' \item{rt}{Always \code{-1}.} ##' \item{rtmin}{Always \code{-1}.} ##' \item{rtmax}{Always \code{-1}.} -##' \item{into}{Integrated (original) intensity of the feature.} -##' \item{maxo}{Maximum intensity of the feature.} +##' \item{into}{Integrated (original) intensity of the peak.} +##' \item{maxo}{Maximum intensity of the peak.} ##' \item{intf}{Always \code{NA}.} -##' \item{maxf}{Maximum MSW-filter response of the feature.} +##' \item{maxf}{Maximum MSW-filter response of the peak.} ##' \item{sn}{Signal to noise ratio.} ##' } ##' @seealso \code{\link{MSW}} for the new user interface, -##' \code{\link{do_detectFeatures_MSW}} for the downstream analysis +##' \code{\link{do_findPeaks_MSW}} for the downstream analysis ##' function or \code{\link[MassSpecWavelet]{peakDetectionCWT}} from the ##' \code{MassSpecWavelet} for details on the algorithm and additionally supported ##' parameters. @@ -1507,11 +1074,11 @@ setMethod("findPeaks.addPredictedIsotopeFeatures", ##' @author Joachim Kutzera, Steffen Neumann, Johannes Rainer setMethod("findPeaks.MSW", "xcmsRaw", function(object, snthresh=3, verbose.columns = FALSE, ...) { - res <- do_detectFeatures_MSW(mz = object@env$mz, - int = object@env$intensity, - snthresh = snthresh, - verboseColumns = verbose.columns, - ...) + res <- do_findPeaks_MSW(mz = object@env$mz, + int = object@env$intensity, + snthresh = snthresh, + verboseColumns = verbose.columns, + ...) invisible(new("xcmsPeaks", res)) }) @@ -2128,90 +1695,6 @@ setMethod("findKalmanROI", "xcmsRaw", function(object, mzrange=c(0.0,0.0), ## PACKAGE ='xcms' ) }) -## ############################################################ -## ## This should be replaced soon; is only for testing purposes. -## setGeneric("findPeaks.massifquant_orig", function(object, ...) -## standardGeneric("findPeaks.massifquant_orig")) -## setMethod("findPeaks.massifquant_orig", "xcmsRaw", -## function(object, -## ppm=10, -## peakwidth=c(20,50), -## snthresh=10, -## prefilter=c(3,100), -## mzCenterFun="wMean", -## integrate=1, -## mzdiff=-0.001, -## fitgauss=FALSE, -## scanrange= numeric(), -## noise=0, ## noise.local=TRUE, -## sleep=0, -## verbose.columns=FALSE, -## criticalValue = 1.125, -## consecMissedLimit = 2, -## unions = 1, -## checkBack = 0, -## withWave = 0) { - -## cat("\n Massifquant, Copyright (C) 2013 Brigham Young University."); -## cat("\n Massifquant comes with ABSOLUTELY NO WARRANTY. See LICENSE for details.\n"); -## flush.console(); -## ## Seems we're not considering scanrange here at all. - -## ##keeep this check since massifquant doesn't check internally -## if (!isCentroided(object)) -## warning("It looks like this file is in profile mode. massifquant can process only centroid mode data !\n") - -## cat("\n Detecting mass traces at",ppm,"ppm ... \n"); flush.console(); -## massifquantROIs = findKalmanROI(object, minIntensity = prefilter[2], -## minCentroids = peakwidth[1], -## criticalVal = criticalValue, -## consecMissedLim = consecMissedLimit, -## segs = unions, -## scanBack = checkBack, -## ppm=ppm) - -## if (withWave == 1) { -## featlist = findPeaks.centWave(object, ppm, peakwidth, snthresh, -## prefilter, mzCenterFun, integrate, mzdiff, fitgauss, -## scanrange, noise, sleep, verbose.columns, ROI.list= massifquantROIs); -## } -## else { -## basenames <- c("mz","mzmin","mzmax","rtmin","rtmax","rt", "into") -## if (length(massifquantROIs) == 0) { -## cat("\nNo peaks found !\n"); -## nopeaks <- new("xcmsPeaks", matrix(nrow=0, ncol=length(basenames))); -## colnames(nopeaks) <- basenames; -## return(invisible(nopeaks)); -## } - -## p <- t(sapply(massifquantROIs, unlist)); -## colnames(p) <- basenames; - -## #get the max intensity for each feature -## maxo <- sapply(seq_len(nrow(p)), function(i) { -## raw <- rawMat(object, mzrange = p[i,c("mzmin", "mzmax")], -## scanrange = p[i,c("rtmin", "rtmax")]) -## max(raw[,3]) -## }) -## p <- cbind(p, maxo) - -## #calculate median index -## p[,"rt"] = as.integer(p[,"rtmin"] + ( (p[,"rt"] + 1) / 2 ) - 1); -## #convert from index into actual time -## p[,"rtmin"] = object@scantime[p[,"rtmin"]]; -## p[,"rtmax"] = object@scantime[p[,"rtmax"]]; -## p[,"rt"] = object@scantime[p[,"rt"]]; - -## uorder <- order(p[,"into"], decreasing=TRUE); -## pm <- as.matrix(p[,c("mzmin","mzmax","rtmin","rtmax"),drop=FALSE]); - -## uindex <- rectUnique(pm,uorder,mzdiff,ydiff = -0.00001) ## allow adjacent peaks; -## featlist <- p[uindex,,drop=FALSE]; -## cat("\n",dim(featlist)[1]," Peaks.\n"); -## invisible(new("xcmsPeaks", featlist)); -## } -## return(invisible(featlist)); -## }) ############################################################ ## findPeaks.massifquant: Note the original code returned, if withWave = 1, @@ -2274,7 +1757,7 @@ setMethod("findPeaks.massifquant", "xcmsRaw", function(object, warning("It looks like this file is in profile mode.", " Massifquant can process only centroid mode data !\n") vps <- diff(c(object@scanindex, length(object@env$mz))) - res <- do_detectFeatures_massifquant(mz = object@env$mz, + res <- do_findChromPeaks_massifquant(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = vps, @@ -2354,7 +1837,7 @@ setMethod("findPeaks.massifquant", "xcmsRaw", function(object, warning("It looks like this file is in profile mode.", " Massifquant can process only centroid mode data !\n") vps <- diff(c(object@scanindex, length(object@env$mz))) - res <- do_detectFeatures_massifquant(mz = object@env$mz, + res <- do_findChromPeaks_massifquant(mz = object@env$mz, int = object@env$intensity, scantime = object@scantime, valsPerSpect = vps, diff --git a/R/methods-xcmsSet.R b/R/methods-xcmsSet.R index 6fc30c082..0139ce169 100644 --- a/R/methods-xcmsSet.R +++ b/R/methods-xcmsSet.R @@ -32,7 +32,7 @@ setMethod("show", "xcmsSet", function(object) { scanrange(object)[2], "\n") } } - errs <- .getProcessErrors(object, PROCSTEP = .PROCSTEP.FEATURE.DETECTION) + errs <- .getProcessErrors(object, PROCSTEP = .PROCSTEP.PEAK.DETECTION) if (length(errs) > 0) { cat(" o Detection errors: ", length(errs), " files failed.\n", " Use method 'showError' to list the error(s).\n\n", sep ="") @@ -343,8 +343,8 @@ setMethod("groupnames", "xcmsSet", function(object, mzdec = 0, rtdec = 0, setMethod("group.density", "xcmsSet", function(object, bw = 30, minfrac = 0.5, minsamp = 1, mzwid = 0.25, max = 50, sleep = 0) { - ## Using now the do_groupFeatures_density function: - res <- do_groupFeatures_density(peaks(object), + ## Using now the do_groupChromPeaks_density function: + res <- do_groupChromPeaks_density(peaks(object), sampleGroups = sampclass(object), bw = bw, minFraction = minfrac, @@ -352,8 +352,8 @@ setMethod("group.density", "xcmsSet", function(object, bw = 30, minfrac = 0.5, binSize = mzwid, maxFeatures = max) - groups(object) <- res$featureGroups - groupidx(object) <- res$featureIndex + groups(object) <- res$featureDefinitions + groupidx(object) <- res$peakIndex object }) @@ -365,14 +365,14 @@ setMethod("group.mzClust", "xcmsSet", function(object, minsamp = 1, minfrac=0.5) { - res <- do_groupFeatures_mzClust(features = peaks(object), - sampleGroups = sampclass(object), - ppm = mzppm, - absMz = mzabs, - minFraction = minfrac, - minSamples = minsamp) - groups(object) <- res$featureGroups - groupidx(object) <- res$featureIndex + res <- do_groupPeaks_mzClust(peaks = peaks(object), + sampleGroups = sampclass(object), + ppm = mzppm, + absMz = mzabs, + minFraction = minfrac, + minSamples = minsamp) + groups(object) <- res$featureDefinitions + groupidx(object) <- res$peakIndex object }) @@ -381,14 +381,14 @@ setMethod("group.mzClust", "xcmsSet", function(object, setMethod("group.nearest", "xcmsSet", function(object, mzVsRTbalance=10, mzCheck=0.2, rtCheck=15, kNN=10) { - res <- do_groupFeatures_nearest(features = peaks(object), - sampleGroups = sampclass(object), - mzVsRtBalance = mzVsRTbalance, - absMz = mzCheck, - absRt = rtCheck, - kNN = kNN) - groups(object) <- res$featureGroups - groupidx(object) <- res$featureIndex + res <- do_groupChromPeaks_nearest(peaks = peaks(object), + sampleGroups = sampclass(object), + mzVsRtBalance = mzVsRTbalance, + absMz = mzCheck, + absRt = rtCheck, + kNN = kNN) + groups(object) <- res$featureDefinitions + groupidx(object) <- res$peakIndex invisible(object) }) @@ -498,14 +498,14 @@ setMethod("retcor.peakgroups", "xcmsSet", function(object, missing = 1, extra = } minFr <- (n - missing) / n - res <- do_adjustRtime_featureGroups(features = peakmat, - featureIndex = object@groupidx, - rtime = rtcor, - minFraction = minFr, - extraFeatures = extra, - smooth = smooth, - span = span, - family = family) + res <- do_adjustRtime_peakGroups(peaks = peakmat, + peakIndex = object@groupidx, + rtime = rtcor, + minFraction = minFr, + extraPeaks = extra, + smooth = smooth, + span = span, + family = family) rtdevsmo <- vector("list", n) for (i in 1:n) { rtdevsmo[[i]] <- rtcor[[i]] - res[[i]] @@ -522,8 +522,8 @@ setMethod("retcor.peakgroups", "xcmsSet", function(object, missing = 1, extra = if (plottype %in% c("deviation", "mdevden")) { ## Need also the 'rt' matrix: - rt <- .getFeatureGroupsRtMatrix(peakmat, object@groupidx, n, - missing, extra) + rt <- .getPeakGroupsRtMatrix(peakmat, object@groupidx, n, + missing, extra) rtdev <- rt - apply(rt, 1, median, na.rm = TRUE) ## define the colors and line types and returns a list of @@ -623,8 +623,8 @@ setMethod("retcor.peakgroups", "xcmsSet", function(object, missing = 1, extra = idx <- which(nsamp >= n-missing & groupmat[,"npeaks"] <= nsamp + extra) if (length(idx) == 0) stop("No peak groups found for retention time correction") - ## Ordering the feature groups by the rtmed might not represent the ordering - ## of the below selected "representative" feature for each feature group. + ## Ordering the peaks by the rtmed might not represent the ordering + ## of the below selected "representative" peak for each peak. ## See issue #110 ## idx <- idx[order(groupmat[idx,"rtmed"])] @@ -964,6 +964,8 @@ setMethod("retcor.obiwarp", "xcmsSet", function(object, plottype = c("none", "de ## Why are we rounding here, but NOT in the retcor.peakgroups? ## -> issue #122 + ## The point is we're using the un-rounded adjusted rt for the rt, BUT + ## use the rounded values for the adjustment of the peak rts. rtdevsmo[[s]] <- round(rtcor[[s]]-object@rt$corrected[[s]],2) rm(obj2) @@ -976,6 +978,8 @@ setMethod("retcor.obiwarp", "xcmsSet", function(object, plottype = c("none", "de } cat("\n") + ## Why are we rounding here, but NOT in the retcor.peakgroups? + ## -> issue #122 rtdevsmo[[center]] <- round(rtcor[[center]] - object@rt$corrected[[center]], 2) if (plottype == "deviation") { @@ -2036,7 +2040,7 @@ setMethod("specDist", signature(object="xcmsSet"), ##' @title Extract processing errors ##' @aliases showError ##' -##' @description If feature detection is performed with \code{\link{findPeaks}} +##' @description If peak detection is performed with \code{\link{findPeaks}} ##' setting argument \code{stopOnError = FALSE} eventual errors during the ##' process do not cause to stop the processing but are recorded inside of the ##' resulting \code{\linkS4class{xcmsSet}} object. These errors can be accessed diff --git a/inst/NEWS b/inst/NEWS index 2876ce91e..790b5b49a 100644 --- a/inst/NEWS +++ b/inst/NEWS @@ -1,3 +1,16 @@ +CHANGES IN VERSION 1.51.7 +------------------------- + +USER VISIBLE CHANGES: ++ Major renaming of methods and classes to follow the naming convention: + - chromatographic peak (chromPeak): the peaks identified in rt dimension. + - feature: mz-rt feature, being the grouped chromatographic peaks within and + across samples. + +BUG FIXES: ++ Issue #127: failing unit test on Windows build machine. + + CHANGES IN VERSION 1.51.6 ------------------------- diff --git a/inst/unitTests/runit.Chromatogram.R b/inst/unitTests/runit.Chromatogram.R new file mode 100644 index 000000000..4c6998d10 --- /dev/null +++ b/inst/unitTests/runit.Chromatogram.R @@ -0,0 +1,46 @@ +## Unit tests related to the Chromatogram class. +library(xcms) +library(RUnit) + +test_Chromatogram_class <- function() { + ch <- new("Chromatogram") + ch@mz <- 3 + checkException(validObject(ch)) + int <- rnorm(100, mean = 200, sd = 2) + rt <- rnorm(100, mean = 300, sd = 3) + ## check exceptions: + checkException(xcms:::Chromatogram(intensity = int)) + checkException(xcms:::Chromatogram(intensity = int, rtime = rt)) + rt <- sort(rt) + ch <- xcms:::Chromatogram(intensity = int, rtime = rt) + checkEquals(rtime(ch), rt) + checkEquals(intensity(ch), int) + checkException(xcms:::Chromatogram(aggregationFun = "other")) + ch@aggregationFun <- "max" + checkTrue(validObject(ch)) + checkEquals(aggregationFun(ch), "max") + ch@aggregationFun <- "sum" + checkTrue(validObject(ch)) + checkEquals(aggregationFun(ch), "sum") + ch@aggregationFun <- "mean" + checkTrue(validObject(ch)) + checkEquals(aggregationFun(ch), "mean") + ch@aggregationFun <- "min" + checkTrue(validObject(ch)) + checkEquals(aggregationFun(ch), "min") + ch@fromFile <- 3L + checkTrue(validObject(ch)) + checkEquals(fromFile(ch), 3L) + checkEquals(length(ch), length(rt)) + ## as.data.frame + df <- as.data.frame(ch) + checkEquals(df, data.frame(rtime = rt, intensity = int)) + ch <- xcms:::Chromatogram(mz = c(1, 3)) + checkEquals(ch@mz, c(1, 3)) + checkEquals(mzrange(ch), c(1, 3)) + checkEquals(mzrange(ch, filter = TRUE), c(0, 0)) + ch <- xcms:::Chromatogram(filterMz = c(1, 3)) + checkEquals(ch@filterMz, c(1, 3)) + checkEquals(mzrange(ch, filter = TRUE), c(1, 3)) + checkEquals(mzrange(ch, filter = FALSE), c(0, 0)) +} diff --git a/inst/unitTests/runit.Param-classes.R b/inst/unitTests/runit.Param-classes.R index 9281ab3e8..daf4f86cd 100644 --- a/inst/unitTests/runit.Param-classes.R +++ b/inst/unitTests/runit.Param-classes.R @@ -480,60 +480,60 @@ test_CentWavePredIsoParam <- function() { checkEquals(L$snthresh, 123) } -test_FeatureDensityParam <- function() { +test_PeakDensityParam <- function() { ## Check getter/setter methods: - p <- new("FeatureDensityParam", sampleGroups = c(1, 1, 1, 2, 2, 3, 4)) + p <- new("PeakDensityParam", sampleGroups = c(1, 1, 1, 2, 2, 3, 4)) checkEquals(sampleGroups(p), c(1, 1, 1, 2, 2, 3, 4)) sampleGroups(p) <- 1:4 checkEquals(sampleGroups(p), 1:4) - p <- FeatureDensityParam(sampleGroups = c("a", "a", "b")) + p <- PeakDensityParam(sampleGroups = c("a", "a", "b")) checkEquals(sampleGroups(p), c("a", "a", "b")) - p <- new("FeatureDensityParam", bw = 3) + p <- new("PeakDensityParam", bw = 3) checkEquals(bw(p), 3) bw(p) <- 20 checkEquals(bw(p), 20) - p <- FeatureDensityParam(bw = 33) + p <- PeakDensityParam(bw = 33) checkEquals(bw(p), 33) - checkException(FeatureDensityParam(bw = -4)) + checkException(PeakDensityParam(bw = -4)) ## minFraction - p <- new("FeatureDensityParam", minFraction = 0.7) + p <- new("PeakDensityParam", minFraction = 0.7) checkEquals(minFraction(p), 0.7) minFraction(p) <- 0.2 checkEquals(minFraction(p), 0.2) - p <- FeatureDensityParam(minFraction = 0.4) + p <- PeakDensityParam(minFraction = 0.4) checkEquals(minFraction(p), 0.4) - checkException(FeatureDensityParam(minFraction = -4)) + checkException(PeakDensityParam(minFraction = -4)) checkException(minFraction(p) <- c(0.3, 0.2, 0.4)) checkException(minFraction(p) <- 2) ## minSamples - p <- new("FeatureDensityParam", minSamples = 3) + p <- new("PeakDensityParam", minSamples = 3) checkEquals(minSamples(p), 3) minSamples(p) <- 20 checkEquals(minSamples(p), 20) - p <- FeatureDensityParam(minSamples = 33) + p <- PeakDensityParam(minSamples = 33) checkEquals(minSamples(p), 33) - checkException(FeatureDensityParam(minSamples = -4)) + checkException(PeakDensityParam(minSamples = -4)) ## binSize - p <- new("FeatureDensityParam", binSize = 3) + p <- new("PeakDensityParam", binSize = 3) checkEquals(binSize(p), 3) binSize(p) <- 20 checkEquals(binSize(p), 20) - p <- FeatureDensityParam(binSize = 0.3) + p <- PeakDensityParam(binSize = 0.3) checkEquals(binSize(p), 0.3) - checkException(FeatureDensityParam(binSize = -4)) + checkException(PeakDensityParam(binSize = -4)) ## maxFeatures - p <- new("FeatureDensityParam", maxFeatures = 3) + p <- new("PeakDensityParam", maxFeatures = 3) checkEquals(maxFeatures(p), 3) maxFeatures(p) <- 20 checkEquals(maxFeatures(p), 20) - p <- FeatureDensityParam(maxFeatures = 33) + p <- PeakDensityParam(maxFeatures = 33) checkEquals(maxFeatures(p), 33) - checkException(FeatureDensityParam(maxFeatures = -4)) + checkException(PeakDensityParam(maxFeatures = -4)) } test_MzClustParam <- function() { @@ -582,96 +582,96 @@ test_MzClustParam <- function() { checkException(MzClustParam(minSamples = -4)) } -test_NearestFeaturesParam <- function() { +test_NearestPeaksParam <- function() { ## Check getter/setter methods: - p <- new("NearestFeaturesParam", sampleGroups = c(1, 1, 1, 2, 2, 3, 4)) + p <- new("NearestPeaksParam", sampleGroups = c(1, 1, 1, 2, 2, 3, 4)) checkEquals(sampleGroups(p), c(1, 1, 1, 2, 2, 3, 4)) sampleGroups(p) <- 1:4 checkEquals(sampleGroups(p), 1:4) - p <- NearestFeaturesParam(sampleGroups = c("a", "a", "b")) + p <- NearestPeaksParam(sampleGroups = c("a", "a", "b")) checkEquals(sampleGroups(p), c("a", "a", "b")) - p <- new("NearestFeaturesParam", mzVsRtBalance = 3) + p <- new("NearestPeaksParam", mzVsRtBalance = 3) checkEquals(mzVsRtBalance(p), 3) mzVsRtBalance(p) <- 20 checkEquals(mzVsRtBalance(p), 20) - p <- NearestFeaturesParam(mzVsRtBalance = 33) + p <- NearestPeaksParam(mzVsRtBalance = 33) checkEquals(mzVsRtBalance(p), 33) - checkException(NearestFeaturesParam(mzVsRtBalance = -4)) - checkException(NearestFeaturesParam(mzVsRtBalance = 1:4)) + checkException(NearestPeaksParam(mzVsRtBalance = -4)) + checkException(NearestPeaksParam(mzVsRtBalance = 1:4)) - p <- new("NearestFeaturesParam", absMz = 3) + p <- new("NearestPeaksParam", absMz = 3) checkEquals(absMz(p), 3) absMz(p) <- 20 checkEquals(absMz(p), 20) - p <- NearestFeaturesParam(absMz = 33) + p <- NearestPeaksParam(absMz = 33) checkEquals(absMz(p), 33) - checkException(NearestFeaturesParam(absMz = -4)) - checkException(NearestFeaturesParam(absMz = 1:3)) + checkException(NearestPeaksParam(absMz = -4)) + checkException(NearestPeaksParam(absMz = 1:3)) - p <- new("NearestFeaturesParam", absRt = 3) + p <- new("NearestPeaksParam", absRt = 3) checkEquals(absRt(p), 3) absRt(p) <- 20 checkEquals(absRt(p), 20) - p <- NearestFeaturesParam(absRt = 33) + p <- NearestPeaksParam(absRt = 33) checkEquals(absRt(p), 33) - checkException(NearestFeaturesParam(absRt = -4)) - checkException(NearestFeaturesParam(absRt = 1:3)) + checkException(NearestPeaksParam(absRt = -4)) + checkException(NearestPeaksParam(absRt = 1:3)) - p <- new("NearestFeaturesParam", kNN = 3) + p <- new("NearestPeaksParam", kNN = 3) checkEquals(kNN(p), 3) kNN(p) <- 20 checkEquals(kNN(p), 20) - p <- NearestFeaturesParam(kNN = 33) + p <- NearestPeaksParam(kNN = 33) checkEquals(kNN(p), 33) - checkException(NearestFeaturesParam(kNN = -4)) - checkException(NearestFeaturesParam(kNN = 1:3)) + checkException(NearestPeaksParam(kNN = -4)) + checkException(NearestPeaksParam(kNN = 1:3)) } -test_FeatureGroupsParam <- function() { +test_PeakGroupsParam <- function() { ## Check getter/setter methods: - p <- new("FeatureGroupsParam", minFraction = 0.8) + p <- new("PeakGroupsParam", minFraction = 0.8) checkEquals(minFraction(p), 0.8) minFraction(p) <- 0.3 checkEquals(minFraction(p), 0.3) - p <- FeatureGroupsParam(minFraction = 0.7) + p <- PeakGroupsParam(minFraction = 0.7) checkEquals(minFraction(p), 0.7) checkException(minFraction(p) <- c(2, 2)) checkException(minFraction(p) <- -1) checkException(minFraction(p) <- 3) - p <- new("FeatureGroupsParam", extraFeatures = 2) - checkEquals(extraFeatures(p), 2) - extraFeatures(p) <- 0.3 - checkEquals(extraFeatures(p), 0.3) - p <- FeatureGroupsParam(extraFeatures = 7) - checkEquals(extraFeatures(p), 7) - checkException(extraFeatures(p) <- c(2, 2)) - checkException(extraFeatures(p) <- -1) - - p <- new("FeatureGroupsParam", span = 0.5) + p <- new("PeakGroupsParam", extraPeaks = 2) + checkEquals(extraPeaks(p), 2) + extraPeaks(p) <- 0.3 + checkEquals(extraPeaks(p), 0.3) + p <- PeakGroupsParam(extraPeaks = 7) + checkEquals(extraPeaks(p), 7) + checkException(extraPeaks(p) <- c(2, 2)) + checkException(extraPeaks(p) <- -1) + + p <- new("PeakGroupsParam", span = 0.5) checkEquals(span(p), 0.5) span(p) <- 0.3 checkEquals(span(p), 0.3) - p <- FeatureGroupsParam(span = 7) + p <- PeakGroupsParam(span = 7) checkEquals(span(p), 7) checkException(span(p) <- c(2, 2)) checkException(span(p) <- -1) - p <- new("FeatureGroupsParam", smooth = "linear") + p <- new("PeakGroupsParam", smooth = "linear") checkEquals(smooth(p), "linear") smooth(p) <- "loess" checkEquals(smooth(p), "loess") - p <- FeatureGroupsParam(smooth = "linear") + p <- PeakGroupsParam(smooth = "linear") checkEquals(smooth(p), "linear") checkException(smooth(p) <- "other") checkException(smooth(p) <- c("linear", "loess")) - p <- new("FeatureGroupsParam", family = "symmetric") + p <- new("PeakGroupsParam", family = "symmetric") checkEquals(family(p), "symmetric") family(p) <- "gaussian" checkEquals(family(p), "gaussian") - p <- FeatureGroupsParam(family = "symmetric") + p <- PeakGroupsParam(family = "symmetric") checkEquals(family(p), "symmetric") checkException(family(p) <- "other") checkException(family(p) <- c("symmetric", "gaussian")) diff --git a/inst/unitTests/runit.XCMSnExp.R b/inst/unitTests/runit.XCMSnExp.R index 42074f828..fa97db474 100644 --- a/inst/unitTests/runit.XCMSnExp.R +++ b/inst/unitTests/runit.XCMSnExp.R @@ -1,7 +1,11 @@ ## tests related to the new XCMSnExp object. -library(RUnit) -od_x <- faahko_xod +od_x <- faahko_od +xod_x <- faahko_xod +xod_xg <- groupChromPeaks(xod_x, param = PeakDensityParam()) +xod_xgr <- adjustRtime(xod_xg, param = PeakGroupsParam(span = 0.4)) +xod_xgrg <- groupChromPeaks(xod_xgr, param = PeakDensityParam()) + xs <- faahko_xs xs_2 <- group(xs) @@ -16,8 +20,8 @@ od_fa <- faahko_od .checkCreationOfEmptyObject <- function() { x <- new("XCMSnExp") checkTrue(!hasAdjustedRtime(x)) - checkTrue(!hasAlignedFeatures(x)) - checkTrue(!hasDetectedFeatures(x)) + checkTrue(!hasFeatures(x)) + checkTrue(!hasChromPeaks(x)) } test_XCMSnExp_class <- function() { @@ -31,16 +35,16 @@ test_XCMSnExp_class <- function() { xod <- as(od_fa, "XCMSnExp") checkTrue(validObject(xod)) ## MsFeatureData error: environment is locked - checkException(xod@msFeatureData$features <- 3) + checkException(xod@msFeatureData$chromPeaks <- 3) checkException(xod@msFeatureData$bla <- 4) checkTrue(validObject(xod)) .checkCreationOfEmptyObject() - ## xod@msFeatureData$features <- xs_2@peaks + ## xod@msFeatureData$chromPeaks <- xs_2@peaks ## checkTrue(validObject(xod)) - ## xod@msFeatureData$features[1, "sample"] <- 40 + ## xod@msFeatureData$chromPeaks[1, "sample"] <- 40 ## checkException(validObject(xod)) - ## xod@msFeatureData$features[1, "sample"] <- 3 + ## xod@msFeatureData$chromPeaks[1, "sample"] <- 3 ## xod@msFeatureData$adjustedRtime <- xs_2@rt$corrected ## checkTrue(validObject(xod)) ## xod@msFeatureData$adjustedRtime[[2]] <- 1:4 @@ -56,7 +60,7 @@ test_XCMSnExp_rtime <- function() { rts_2 <- rtime(od_x) checkEquals(rts, rts_2) ## Test with bySample. - rts_3 <- rtime(od_x, bySample = TRUE) + rts_3 <- rtime(xod_x, bySample = TRUE) checkEquals(rts_3, split(rts, f = fromFile(faahko_od))) ## Check if rtimes are correctly ordered for bySample rts_4 <- rtime(filterFile(faahko_od, file = 2)) @@ -74,7 +78,7 @@ test_XCMSnExp_mz <- function() { ## The check below has to work, since we're calling the mz,OnDiskMSnExp. ## mzs_2 <- mz(od_x) ## checkEquals(mzs, mzs_2) - mzs_2 <- mz(od_x, bySample = TRUE) + mzs_2 <- mz(xod_x, bySample = TRUE) tmp <- split(mzs, fromFile(faahko_od)) checkEquals(lapply(tmp, unlist, use.names = FALSE), mzs_2) ## Check if mz are correctly ordered for bySample @@ -87,7 +91,7 @@ test_XCMSnExp_intensity <- function() { ## The check below has to work, since we're calling the intensity,OnDiskMSnExp. ## ints_2 <- intensity(od_x) ## checkEquals(ints, ints_2) - ints_2 <- intensity(od_x, bySample = TRUE) + ints_2 <- intensity(xod_x, bySample = TRUE) tmp <- split(ints, fromFile(faahko_od)) checkEquals(lapply(tmp, unlist, use.names = FALSE), ints_2) ## Check if mz are correctly ordered for bySample @@ -106,54 +110,64 @@ test_XCMSnExp_class_accessors <- function() { .checkCreationOfEmptyObject() ## Filling with data... xod <- as(od_fa, "XCMSnExp") - ## features - checkTrue(!hasDetectedFeatures(xod)) - features(xod) <- xs_2@peaks - checkTrue(hasDetectedFeatures(xod)) - checkEquals(features(xod), xs_2@peaks) - checkException(features(xod) <- 4) - tmp <- features(xod, bySample = TRUE) + ## peaks + checkTrue(!hasChromPeaks(xod)) + chromPeaks(xod) <- xs_2@peaks + checkTrue(hasChromPeaks(xod)) + checkEquals(chromPeaks(xod), xs_2@peaks) + checkException(chromPeaks(xod) <- 4) + tmp <- chromPeaks(xod, bySample = TRUE) checkTrue(length(tmp) == length(fileNames(xod))) tmp <- do.call(rbind, tmp) rownames(tmp) <- NULL - checkEquals(tmp, features(xod)) + checkEquals(tmp, chromPeaks(xod)) ## Wrong assignments. pks <- xs_2@peaks pks[1, "sample"] <- 40 - checkException(features(xod) <- pks) - ## featureGroups - checkTrue(!hasAlignedFeatures(xod)) + checkException(chromPeaks(xod) <- pks) + ## featureDefinitions + checkTrue(!hasFeatures(xod)) library(S4Vectors) fd <- DataFrame(xs_2@groups) - fd$featureidx <- xs_2@groupidx - featureGroups(xod) <- fd - checkTrue(hasDetectedFeatures(xod)) - checkTrue(hasAlignedFeatures(xod)) - checkEquals(featureGroups(xod), fd) + fd$peakidx <- xs_2@groupidx + featureDefinitions(xod) <- fd + checkTrue(hasChromPeaks(xod)) + checkTrue(hasFeatures(xod)) + checkEquals(featureDefinitions(xod), fd) ## adjustedRtime checkTrue(!hasAdjustedRtime(xod)) - adjustedRtime(xod) <- xs_2@rt$corrected - checkTrue(hasAdjustedRtime(xod)) - checkTrue(hasDetectedFeatures(xod)) - checkTrue(hasAlignedFeatures(xod)) - checkEquals(adjustedRtime(xod, bySample = TRUE), xs_2@rt$corrected) + xod2 <- xod + adjustedRtime(xod2) <- xs_2@rt$corrected + checkTrue(hasAdjustedRtime(xod2)) + checkTrue(hasChromPeaks(xod2)) + checkTrue(hasFeatures(xod2)) + checkEquals(adjustedRtime(xod2, bySample = TRUE), xs_2@rt$corrected) + ## The chromatographic peaks should be different to the unadjusted ones. + tmp <- chromPeaks(xod)[, "rt"] == chromPeaks(xod2)[, "rt"] + ## Most of the rts should be different + checkTrue(sum(tmp) < length(tmp)/4) + tmp <- chromPeaks(xod)[, "rtmin"] == chromPeaks(xod2)[, "rtmin"] + checkTrue(sum(tmp) < length(tmp)/4) + tmp <- chromPeaks(xod)[, "rtmax"] == chromPeaks(xod2)[, "rtmax"] + checkTrue(sum(tmp) < length(tmp)/4) ## rtime should now also return adjusted retention times - checkEquals(rtime(xod), adjustedRtime(xod)) - checkEquals(rtime(xod, adjusted = FALSE), rtime(as(xod, "OnDiskMSnExp"))) - checkEquals(rtime(xod, adjusted = TRUE), adjustedRtime(xod)) + checkEquals(rtime(xod2), adjustedRtime(xod2)) + checkEquals(rtime(xod2, adjusted = FALSE), rtime(as(xod2, "OnDiskMSnExp"))) + checkEquals(rtime(xod2, adjusted = FALSE), rtime(xod)) + checkEquals(rtime(xod2, adjusted = TRUE), adjustedRtime(xod2)) ## Indirect test that the ordering of the adjusted retention times matches ## ordering of rtime. - tmp <- unlist(adjustedRtime(xod, bySample = TRUE)) - tmp_diff <- tmp - rtime(xod) - tmp_diff_2 <- adjustedRtime(xod, bySample = FALSE) - rtime(xod) + tmp <- unlist(adjustedRtime(xod2, bySample = TRUE)) + tmp_diff <- tmp - rtime(xod2) + tmp_diff_2 <- adjustedRtime(xod2, bySample = FALSE) - rtime(xod2) checkTrue(max(tmp_diff) > max(tmp_diff_2)) - checkEquals(names(adjustedRtime(xod)), names(rtime(xod))) + checkEquals(names(adjustedRtime(xod2)), names(rtime(xod2))) ## Wrong assignments. - checkException(adjustedRtime(xod) <- xs_2@rt$corrected[1:2]) + checkException(adjustedRtime(xod2) <- xs_2@rt$corrected[1:2]) ## bracket subset - tmp <- xod[1] + tmp <- xod2[1] checkTrue(length(tmp[[1]]) == 1) - checkTrue(length(xod[[1]]) == 1) + checkTrue(length(xod2[[1]]) == 1) .checkCreationOfEmptyObject() } @@ -179,97 +193,110 @@ test_XCMSnExp_processHistory <- function() { test_XCMSnExp_droppers <- function() { ## How are the drop functions expected to work? .checkCreationOfEmptyObject() - type_feat_det <- xcms:::.PROCSTEP.FEATURE.DETECTION - type_feat_algn <- xcms:::.PROCSTEP.FEATURE.ALIGNMENT + type_feat_det <- xcms:::.PROCSTEP.PEAK.DETECTION + type_feat_algn <- xcms:::.PROCSTEP.PEAK.GROUPING type_rt_adj <- xcms:::.PROCSTEP.RTIME.CORRECTION ## Perform alignment. - od_xg <- groupFeatures(od_x, param = FeatureDensityParam()) - checkTrue(hasAlignedFeatures(od_xg)) - checkTrue(length(processHistory(od_xg, type = type_feat_algn)) == 1) + ## xod_xg <- groupChromPeaks(xod_x, param = PeakDensityParam()) + checkTrue(hasFeatures(xod_xg)) + checkTrue(hasChromPeaks(xod_x)) + checkTrue(hasChromPeaks(xod_xg)) + checkTrue(!hasAdjustedRtime(xod_xg)) + checkTrue(length(processHistory(xod_xg, type = type_feat_algn)) == 1) ## Retention time adjustment. - od_xgr <- adjustRtime(od_xg, param = FeatureGroupsParam(span = 1)) - checkTrue(hasDetectedFeatures(od_xgr)) - checkTrue(length(processHistory(od_xgr, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(od_xgr)) ## These should have been removed - checkTrue(length(processHistory(od_xgr, type = type_feat_algn)) == 1) - checkTrue(hasAdjustedRtime(od_xgr)) - checkTrue(length(processHistory(od_xgr, type = type_rt_adj)) == 1) + ## xod_xgr <- adjustRtime(xod_xg, param = PeakGroupsParam(span = 1)) + checkTrue(hasChromPeaks(xod_xgr)) + checkTrue(length(processHistory(xod_xgr, type = type_feat_det)) == 1) + checkTrue(!hasFeatures(xod_xgr)) ## These should have been removed + checkTrue(length(processHistory(xod_xgr, type = type_feat_algn)) == 1) + checkTrue(hasAdjustedRtime(xod_xgr)) + checkTrue(length(processHistory(xod_xgr, type = type_rt_adj)) == 1) ## Most of the retention times are different - checkTrue(sum(features(od_xgr)[, "rt"] != features(od_x)[, "rt"]) > - nrow(features(od_x)) / 2) + checkTrue(sum(chromPeaks(xod_xgr)[, "rt"] != chromPeaks(xod_x)[, "rt"]) > + nrow(chromPeaks(xod_x)) / 2) + checkTrue(sum(rtime(xod_xgr) == rtime(xod_xg)) < length(rtime(xod_xg) / 2)) ## Alignment after retention time adjustment. - od_xgrg <- groupFeatures(od_xgr, param = FeatureDensityParam()) - checkTrue(hasDetectedFeatures(od_xgrg)) - checkEquals(features(od_xgrg), features(od_xgr)) - checkTrue(hasAdjustedRtime(od_xgrg)) - checkTrue(length(processHistory(od_xgr, type = type_feat_algn)) == 1) - checkTrue(hasAlignedFeatures(od_xgrg)) - checkTrue(length(processHistory(od_xgrg, type = type_feat_algn)) == 2) + ## xod_xgrg <- groupChromPeaks(xod_xgr, param = PeakDensityParam()) + checkTrue(hasChromPeaks(xod_xgrg)) + checkEquals(chromPeaks(xod_xgrg), chromPeaks(xod_xgr)) + checkTrue(hasAdjustedRtime(xod_xgrg)) + checkEquals(rtime(xod_xgrg), rtime(xod_xgr)) + checkEquals(rtime(xod_xgrg, adjusted = FALSE), rtime(od_x)) + checkTrue(length(processHistory(xod_xgr, type = type_feat_algn)) == 1) + checkTrue(hasFeatures(xod_xgrg)) + checkTrue(length(processHistory(xod_xgrg, type = type_feat_algn)) == 2) ## 1) dropDetectedFeatures: delete all process history steps and all data. - res <- dropFeatures(od_x) - checkTrue(!hasDetectedFeatures(res)) + res <- dropChromPeaks(xod_x) + checkTrue(!hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 0) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) + checkEquals(rtime(res), rtime(od_x)) ## - res <- dropFeatures(od_xg) - checkTrue(!hasDetectedFeatures(res)) + res <- dropChromPeaks(xod_xg) + checkTrue(!hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 0) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) + checkEquals(rtime(res), rtime(od_x)) ## - res <- dropFeatures(od_xgr) - checkTrue(!hasDetectedFeatures(res)) + res <- dropChromPeaks(xod_xgr) + checkTrue(!hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 0) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) + checkEquals(rtime(res), rtime(od_x)) ## - res <- dropFeatures(od_xgrg) - checkTrue(!hasDetectedFeatures(res)) + res <- dropChromPeaks(xod_xgrg) + checkTrue(!hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 0) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) + checkEquals(rtime(res), rtime(od_x)) - ## 2) dropFeatureGroups: + ## 2) dropFeatureDefinitions: ## a) drop the feature groups and the latest related process history ## b) if retention time correction was performed AFTER the latest feature ## grouping, drop also the retention time correction and all related ## process histories. - res <- dropFeatureGroups(od_xg) - checkEquals(res, od_x) - checkTrue(hasDetectedFeatures(res)) + res <- dropFeatureDefinitions(xod_xg) + checkEquals(res, xod_x) + checkTrue(hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) + checkEquals(rtime(res), rtime(od_x)) ## No feature groups - so there is nothing that this function does here. - res <- dropFeatureGroups(od_xgr) - checkEquals(res, od_xgr) - checkTrue(hasDetectedFeatures(res)) + res <- dropFeatureDefinitions(xod_xgr) + checkEquals(res, xod_xgr) + checkTrue(hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 1) checkTrue(hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 1) ## Remove the latest ones. - res <- dropFeatureGroups(od_xgrg) - checkEquals(res, od_xgr) - checkTrue(hasDetectedFeatures(res)) + res <- dropFeatureDefinitions(xod_xgrg) + checkEquals(res, xod_xgr) + checkTrue(hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 1) checkTrue(hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 1) + checkEquals(rtime(res, adjusted = FALSE), rtime(od_x)) + checkEquals(rtime(res, adjusted = TRUE), rtime(xod_xgr)) ## 3) dropAdjustedRtime: ## a) drop the retention time adjustment and related process histories @@ -277,31 +304,31 @@ test_XCMSnExp_droppers <- function() { ## drop the feature alignment and all related process histories. ## c) if grouping has been performed BEFORE retention time correction, ## do nothing. - res <- dropAdjustedRtime(od_xg) - checkEquals(res, od_xg) + res <- dropAdjustedRtime(xod_xg) + checkEquals(res, xod_xg) ## This drops also the process history for alignment. - res <- dropAdjustedRtime(od_xgr) - checkTrue(hasDetectedFeatures(res)) + res <- dropAdjustedRtime(xod_xgr) + checkTrue(hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) - checkEquals(features(res), features(od_x)) - checkEquals(res, od_x) - checkEquals(rtime(res), rtime(od_x)) - checkEquals(rtime(res), rtime(od_xgr, adjusted = FALSE)) + checkEquals(chromPeaks(res), chromPeaks(xod_x)) + checkEquals(res, xod_x) + checkEquals(rtime(res), rtime(xod_x)) + checkEquals(rtime(res), rtime(xod_xgr, adjusted = FALSE)) ## This drops also the feature alignment performed later. - res <- dropAdjustedRtime(od_xgrg) - checkTrue(hasDetectedFeatures(res)) + res <- dropAdjustedRtime(xod_xgrg) + checkTrue(hasChromPeaks(res)) checkTrue(length(processHistory(res, type = type_feat_det)) == 1) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res, type = type_feat_algn)) == 0) checkTrue(!hasAdjustedRtime(res)) checkTrue(length(processHistory(res, type = type_rt_adj)) == 0) - checkEquals(features(res), features(od_x)) - checkEquals(res, od_x) - checkEquals(rtime(res), rtime(od_xgrg, adjusted = FALSE)) + checkEquals(chromPeaks(res), chromPeaks(xod_x)) + checkEquals(res, xod_x) + checkEquals(rtime(res), rtime(xod_xgrg, adjusted = FALSE)) .checkCreationOfEmptyObject() } @@ -315,91 +342,91 @@ test_XCMSnExp_inherited_methods <- function() { ## [ tmp_1 <- od_fa[1:10] suppressWarnings( - tmp_2 <- od_x[1:10] + tmp_2 <- xod_x[1:10] ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## bin tmp_1 <- bin(od_fa) suppressWarnings( - tmp_2 <- bin(od_x) + tmp_2 <- bin(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## clean tmp_1 <- clean(od_fa) suppressWarnings( - tmp_2 <- clean(od_x) + tmp_2 <- clean(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## filterAcquisitionNum tmp_1 <- filterAcquisitionNum(od_fa) suppressWarnings( - tmp_2 <- filterAcquisitionNum(od_x) + tmp_2 <- filterAcquisitionNum(xod_x) ) checkTrue(length(tmp_2[[1]]) > 0) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## filterMsLevel tmp_1 <- filterMsLevel(od_fa) suppressWarnings( - tmp_2 <- filterMsLevel(od_x) + tmp_2 <- filterMsLevel(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## normalize tmp_1 <- normalize(od_fa) suppressWarnings( - tmp_2 <- normalize(od_x) + tmp_2 <- normalize(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## pickPeaks tmp_1 <- pickPeaks(od_fa) suppressWarnings( - tmp_2 <- pickPeaks(od_x) + tmp_2 <- pickPeaks(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## removePeaks tmp_1 <- removePeaks(od_fa) suppressWarnings( - tmp_2 <- removePeaks(od_x) + tmp_2 <- removePeaks(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) ## smooth tmp_1 <- smooth(od_fa) suppressWarnings( - tmp_2 <- smooth(od_x) + tmp_2 <- smooth(xod_x) ) checkTrue(length(processHistory(tmp_2)) == 0) - checkTrue(!hasDetectedFeatures(tmp_2)) + checkTrue(!hasChromPeaks(tmp_2)) tmp_1@processingData <- new("MSnProcess") tmp_2@processingData <- new("MSnProcess") checkEquals(tmp_1, as(tmp_2, "OnDiskMSnExp")) @@ -409,36 +436,45 @@ test_XCMSnExp_inherited_methods <- function() { ## Test XCMSnExp filter methods. test_XCMSnExp_filterFile <- function() { ## filterFile - tmp <- filterFile(od_x, file = 2) + tmp <- filterFile(xod_x, file = 2) checkException(tmp@msFeatureData$bla <- 3) checkTrue(!hasAdjustedRtime(tmp)) - checkTrue(!hasAlignedFeatures(tmp)) - checkTrue(all(features(tmp)[, "sample"] == 1)) - checkEquals(features(tmp)[, -ncol(features(tmp))], - features(od_x)[features(od_x)[, "sample"] == 2, - -ncol(features(od_x))]) + checkTrue(!hasFeatures(tmp)) + checkTrue(all(chromPeaks(tmp)[, "sample"] == 1)) + checkEquals(chromPeaks(tmp)[, -ncol(chromPeaks(tmp))], + chromPeaks(xod_x)[chromPeaks(xod_x)[, "sample"] == 2, + -ncol(chromPeaks(xod_x))]) checkEquals(fileIndex(processHistory(tmp)[[1]]), 1) ## check with other index. - tmp <- filterFile(od_x, file = c(1, 3)) + tmp <- filterFile(xod_x, file = c(1, 3)) checkTrue(length(tmp[[1]]) == 1) checkTrue(!hasAdjustedRtime(tmp)) - checkTrue(!hasAlignedFeatures(tmp)) - checkTrue(all(features(tmp)[, "sample"] %in% c(1, 2))) - a <- features(tmp) - b <- features(od_x) + checkTrue(!hasFeatures(tmp)) + checkTrue(all(chromPeaks(tmp)[, "sample"] %in% c(1, 2))) + a <- chromPeaks(tmp) + b <- chromPeaks(xod_x) checkEquals(a[, -ncol(a)], b[b[, "sample"] %in% c(1, 3), -ncol(b)]) checkEquals(fileIndex(processHistory(tmp)[[1]]), c(1, 2)) ## Errors - checkException(filterFile(od_x, file = 5)) - checkException(filterFile(od_x, file = 1:5)) + checkException(filterFile(xod_x, file = 5)) + checkException(filterFile(xod_x, file = 1:5)) ## Little mockup to check correctness of Process history. - od_2 <- od_x - od_2 <- xcms:::addProcessHistory(od_2, - xcms:::ProcessHistory(type = xcms:::.PROCSTEP.RTIME.CORRECTION)) - od_2 <- xcms:::addProcessHistory(od_2, xcms:::ProcessHistory(type = xcms:::.PROCSTEP.UNKNOWN, fileIndex = 2, info. = "I should be here")) - od_2 <- xcms:::addProcessHistory(od_2, xcms:::ProcessHistory(type = xcms:::.PROCSTEP.UNKNOWN, fileIndex = 1, info. = "EEEEEE")) + od_2 <- xod_x + od_2 <- xcms:::addProcessHistory( + od_2, + xcms:::ProcessHistory( + type = xcms:::.PROCSTEP.RTIME.CORRECTION)) + od_2 <- xcms:::addProcessHistory( + od_2, + xcms:::ProcessHistory(type = xcms:::.PROCSTEP.UNKNOWN, + fileIndex = 2, + info. = "I should be here")) + od_2 <- xcms:::addProcessHistory( + od_2, + xcms:::ProcessHistory(type = xcms:::.PROCSTEP.UNKNOWN, + fileIndex = 1, info. = "EEEEEE")) tmp <- filterFile(od_2, file = 2) ph <- processHistory(tmp) @@ -452,183 +488,332 @@ test_XCMSnExp_filterFile <- function() { processInfo(z) == "EEEEEE" })) checkTrue(!any(b)) + ## Do filterFile on xod_xg + res <- filterFile(xod_xg, file = 2) + checkTrue(hasChromPeaks(res)) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + tmp <- chromPeaks(xod_xg) + checkEquals(chromPeaks(res)[, -ncol(tmp)], tmp[tmp[, "sample"] == 2, -ncol(tmp)]) + checkEquals(rtime(res), rtime(xod_xg, bySample = TRUE)[[2]]) + ## Do filterFile on xod_xgr + ## Should remove adjusted rts and revert the original peak rts. + res <- filterFile(xod_xgr, file = 2) + checkTrue(hasChromPeaks(res)) + tmp <- chromPeaks(xod_xg) + checkEquals(chromPeaks(res)[, -ncol(tmp)], tmp[tmp[, "sample"] == 2, -ncol(tmp)]) + checkEquals(rtime(res), rtime(xod_xg, bySample = TRUE)[[2]]) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 1) + checkEquals(processType(processHistory(res)[[1]]), "Peak detection") + ## The same but keep the adjusted retention times. + res <- filterFile(xod_xgr, file = 2, keepAdjustedRtime = TRUE) + checkTrue(hasChromPeaks(res)) + tmp <- chromPeaks(xod_xgr) + checkEquals(chromPeaks(res)[, -ncol(tmp)], tmp[tmp[, "sample"] == 2, -ncol(tmp)]) + ## has to be different from the ones in xod_x + tmp <- chromPeaks(xod_x) + checkTrue(sum(chromPeaks(res)[, "rt"] == tmp[tmp[, "sample"] == 2, "rt"]) < + nrow(tmp) / 4) + checkEquals(rtime(res), rtime(xod_xgr, bySample = TRUE)[[2]]) + checkEquals(adjustedRtime(res), adjustedRtime(xod_xgr, bySample = TRUE)[[2]]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 2) + checkEquals(processType(processHistory(res)[[1]]), "Peak detection") + checkEquals(processType(processHistory(res)[[2]]), "Retention time correction") + ## Do filterFile on xod_xgrg + res <- filterFile(xod_xgrg, file = c(1, 3)) + checkTrue(hasChromPeaks(res)) + tmp <- chromPeaks(xod_x) + checkEquals(chromPeaks(res)[, -ncol(tmp)], + tmp[tmp[, "sample"] %in% c(1, 3), -ncol(tmp)]) + checkEquals(unname(rtime(res, bySample = TRUE)), + unname(rtime(xod_xg, bySample = TRUE)[c(1, 3)])) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 1) + checkEquals(processType(processHistory(res)[[1]]), "Peak detection") + ## keep adjusted rtime + res <- filterFile(xod_xgrg, file = c(1, 3), keepAdjustedRtime = TRUE) + checkTrue(hasChromPeaks(res)) + tmp <- chromPeaks(xod_xgr) + checkEquals(chromPeaks(res)[, -ncol(tmp)], + tmp[tmp[, "sample"] %in% c(1, 3), -ncol(tmp)]) + ## has to be different from the ones in xod_x + tmp <- chromPeaks(xod_x) + checkTrue(sum(chromPeaks(res)[, "rt"] == tmp[tmp[, "sample"] %in% c(1, 3), "rt"]) < + nrow(tmp) / 4) + checkEquals(rtime(res, bySample = TRUE), + rtime(xod_xgr, bySample = TRUE)[c(1, 3)]) + checkEquals(adjustedRtime(res, bySample = TRUE), + adjustedRtime(xod_xgr, bySample = TRUE)[c(1, 3)]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 2) + checkEquals(processType(processHistory(res)[[1]]), "Peak detection") + checkEquals(processType(processHistory(res)[[2]]), "Retention time correction") } test_XCMSnExp_filterMz <- function() { - od_x2 <- od_x - new_e <- xcms:::.copy_env(od_x2@msFeatureData) - xcms:::adjustedRtime(od_x2) <- xs_2@rt$corrected - library(S4Vectors) - fd <- DataFrame(xs_2@groups) - fd$featureidx <- xs_2@groupidx - featureGroups(od_x2) <- fd + ## od_x2 <- od_x + ## new_e <- xcms:::.copy_env(od_x2@msFeatureData) + ## xcms:::adjustedRtime(od_x2) <- xs_2@rt$corrected + ## library(S4Vectors) + ## fd <- DataFrame(xs_2@groups) + ## fd$peakidx <- xs_2@groupidx + ## featureDefinitions(od_x2) <- fd - ## Subset - tmp <- filterMz(od_x2, mz = c(300, 400)) - checkTrue(length(tmp[[1]]) == 1) - checkException(tmp@msFeatureData$bla <- 3) - checkTrue(length(tmp@spectraProcessingQueue) == 1) - checkTrue(all(features(tmp)[, "mz"] >= 300 & features(tmp)[, "mz"] <= 400)) - checkTrue(validObject(tmp@msFeatureData)) - checkTrue(all(featureGroups(tmp)$mzmed >= 300 & - featureGroups(tmp)$mzmed <= 400)) - checkEquals(adjustedRtime(tmp), adjustedRtime(od_x2)) - checkTrue(nrow(features(tmp)) < nrow(features(od_x2))) - checkTrue(hasDetectedFeatures(tmp)) - checkTrue(hasAlignedFeatures(tmp)) - ## second - tmp <- filterMz(od_x, mz = c(300, 400)) - checkTrue(hasDetectedFeatures(tmp)) - checkTrue(!hasAlignedFeatures(tmp)) - checkTrue(all(features(tmp)[, "mz"] >= 300 & features(tmp)[, "mz"] <= 400)) - checkTrue(validObject(tmp@msFeatureData)) + ## subset on xod_x + res <- filterMz(xod_x, mz = c(300, 400)) + suppressWarnings( + checkTrue(length(res[[1]]) == 1) + ) + checkTrue(length(res@spectraProcessingQueue) == 1) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 300 & chromPeaks(res)[, "mz"] <= 400)) + checkTrue(nrow(chromPeaks(res)) < nrow(chromPeaks(xod_x))) + idx <- which(chromPeaks(xod_x)[, "mzmin"] >= 300 & + chromPeaks(xod_x)[, "mzmax"] <= 400) + checkEquals(chromPeaks(res), chromPeaks(xod_x)[idx, ]) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(!hasFeatures(res)) + ## subset on xod_xg + res <- filterMz(xod_xg, mz = c(300, 400)) + checkTrue(validObject(res)) + suppressWarnings( + checkTrue(length(res[[1]]) == 1) + ) + checkTrue(length(res@spectraProcessingQueue) == 1) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 300 & chromPeaks(res)[, "mz"] <= 400)) + checkTrue(nrow(chromPeaks(res)) < nrow(chromPeaks(xod_x))) + idx <- which(chromPeaks(xod_xg)[, "mzmin"] >= 300 & + chromPeaks(xod_xg)[, "mzmax"] <= 400) + checkEquals(chromPeaks(res), chromPeaks(xod_xg)[idx, ]) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(hasFeatures(res)) + checkTrue(nrow(featureDefinitions(res)) < nrow(featureDefinitions(xod_xg))) + checkTrue(all(featureDefinitions(res)[, "mzmed"] >= 300 & + featureDefinitions(res)[, "mzmed"] <= 400)) + checkTrue(all(featureDefinitions(res)[, "mzmin"] >= 300 & + featureDefinitions(res)[, "mzmin"] <= 400)) + checkTrue(all(featureDefinitions(res)[, "mzmax"] >= 300 & + featureDefinitions(res)[, "mzmax"] <= 400)) + ## subset on xod_xgr + ## o keep chromPeaks + ## o keep adjusted rtime + res <- filterMz(xod_xgr, mz = c(300, 400)) + checkTrue(validObject(res)) + suppressWarnings( + checkTrue(length(res[[1]]) == 1) + ) + checkTrue(length(res@spectraProcessingQueue) == 1) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 300 & chromPeaks(res)[, "mz"] <= 400)) + checkTrue(nrow(chromPeaks(res)) < nrow(chromPeaks(xod_x))) + idx <- which(chromPeaks(xod_xgr)[, "mzmin"] >= 300 & + chromPeaks(xod_xgr)[, "mzmax"] <= 400) + checkEquals(chromPeaks(res), chromPeaks(xod_xgr)[idx, ]) + checkTrue(hasAdjustedRtime(res)) + checkEquals(adjustedRtime(res), adjustedRtime(xod_xgr)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 3) + ## subset xod_xgrg + res <- filterMz(xod_xgrg, mz = c(300, 400)) + checkTrue(validObject(res)) + suppressWarnings( + checkTrue(length(res[[1]]) == 1) + ) + checkTrue(length(res@spectraProcessingQueue) == 1) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 300 & chromPeaks(res)[, "mz"] <= 400)) + checkTrue(nrow(chromPeaks(res)) < nrow(chromPeaks(xod_xgrg))) + idx <- which(chromPeaks(xod_xgrg)[, "mzmin"] >= 300 & + chromPeaks(xod_xgrg)[, "mzmax"] <= 400) + checkEquals(chromPeaks(res), chromPeaks(xod_xgrg)[idx, ]) + checkTrue(hasAdjustedRtime(res)) + checkEquals(adjustedRtime(res), adjustedRtime(xod_xgrg)) + checkTrue(hasFeatures(res)) + checkTrue(nrow(featureDefinitions(res)) < nrow(featureDefinitions(xod_xgrg))) + checkTrue(all(featureDefinitions(res)[, "mzmed"] >= 300 & + featureDefinitions(res)[, "mzmed"] <= 400)) + checkTrue(all(featureDefinitions(res)[, "mzmin"] >= 300 & + featureDefinitions(res)[, "mzmin"] <= 400)) + checkTrue(all(featureDefinitions(res)[, "mzmax"] >= 300 & + featureDefinitions(res)[, "mzmax"] <= 400)) + ## With groups - no groups within this range + mzr <- c(120, 130) + res <- filterMz(xod_xg, mz = mzr) + checkTrue(!hasFeatures(res)) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 120 & chromPeaks(res)[, "mz"] <= 130)) + res <- filterMz(xod_xgrg, mz = mzr) + checkTrue(!hasFeatures(res)) + checkTrue(hasChromPeaks(res)) + checkTrue(all(chromPeaks(res)[, "mz"] >= 120 & chromPeaks(res)[, "mz"] <= 130)) } test_XCMSnExp_filterRt <- function() { - od_x2 <- od_x - ## Testing with only feature data present: - res <- filterRt(od_x2, rt = c(2700, 2900)) + ## xod_x + res <- filterRt(xod_x, rt = c(2700, 2900)) ## Check if the object is OK: - checkEquals(pData(res), pData(od_x2)) - checkTrue(length(spectra(res)) > 0) - + checkEquals(pData(res), pData(xod_x)) + spct <- spectra(res) + checkTrue(length(spct) > 0) ## MsFeatureData has to be locked! checkException(res@msFeatureData$bla <- 3) ## Retention time has to be within the range. checkTrue(all(rtime(res) >= 2700 & rtime(res) <= 2900)) - ## features have to be within the range. - checkTrue(all(features(res)[, "rt"] >= 2700 & - features(res)[, "rt"] <= 2900)) - ## features have to match the subsetted ones. - are_within <- features(od_x2)[, "rt"] >= 2700 & - features(od_x2)[, "rt"] <= 2900 - checkEquals(features(res), features(od_x2)[are_within,]) + rtm <- unlist(lapply(spct, rtime)) + checkTrue(all(rtm >= 2700 & rtm <= 2900)) + ## peaks have to be within the range. + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_x)[, "rt"] >= 2700 & + chromPeaks(xod_x)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_x)[are_within,]) ## Have a feature detection process history. + checkEquals(length(processHistory(res)), 1) checkEquals(processType(processHistory(res)[[1]]), - xcms:::.PROCSTEP.FEATURE.DETECTION) - ## filter such that we keep some spectra but no features: - res <- filterRt(od_x2, rt = c(4200, 4400)) + xcms:::.PROCSTEP.PEAK.DETECTION) + ## filter such that we keep some spectra but no chromPeaks: + res <- filterRt(xod_x, rt = c(4200, 4400)) checkTrue(all(rtime(res) >= 4200 & rtime(res) <= 4400)) - checkTrue(!hasDetectedFeatures(res)) + checkTrue(!hasChromPeaks(res)) checkTrue(length(processHistory(res)) == 0) ## No rt - res <- filterRt(od_x2, rt = c(10, 20)) + res <- filterRt(xod_x, rt = c(10, 20)) checkTrue(length(res) == 0) - ## With feature groups: - od_xg <- groupFeatures(od_x, param = FeatureDensityParam()) - res <- filterRt(od_xg, rt = c(2700, 2900)) - checkEquals(hasDetectedFeatures(res), hasDetectedFeatures(od_xg)) - checkEquals(hasAlignedFeatures(res), hasAlignedFeatures(od_xg)) - checkTrue(length(processHistory(res, type = "Feature detection")) == 1) - checkTrue(length(processHistory(res, type = "Feature alignment")) == 1) - ## Retention time has to be within the range. + ## xod_xg + ## o keep also the feature groups that are within the window. + res <- filterRt(xod_xg, rt = c(2700, 2900)) checkTrue(all(rtime(res) >= 2700 & rtime(res) <= 2900)) - ## features have to be within the range. - checkTrue(all(features(res)[, "rt"] >= 2700 & - features(res)[, "rt"] <= 2900)) - ## feature groups have to be within range: - checkTrue(all(featureGroups(res)$rtmed >= 2700 & - featureGroups(res)$rtmed <= 2900)) + checkEquals(hasChromPeaks(res), hasChromPeaks(xod_xg)) + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_x)[, "rt"] >= 2700 & + chromPeaks(xod_x)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_xg)[are_within,]) + checkTrue(!hasAdjustedRtime(res)) + checkTrue(hasFeatures(res)) + checkTrue(all(featureDefinitions(res)$rtmed >= 2700 & + featureDefinitions(res)$rtmed <= 2900)) + checkTrue(nrow(featureDefinitions(res)) < nrow(featureDefinitions(xod_xg))) + checkTrue(length(processHistory(res)) == 2) + checkTrue(length(processHistory(res, type = "Peak detection")) == 1) + checkTrue(length(processHistory(res, type = "Peak grouping")) == 1) ## All feature idx have to match. - checkTrue(all(unlist(featureGroups(res)$featureidx) %in% - 1:nrow(features(res)))) - ## Filter such that we don't have any features. - res <- filterRt(od_xg, rt = c(4200, 4400)) + checkTrue(all(unlist(featureDefinitions(res)$peakidx) %in% + 1:nrow(chromPeaks(res)))) + ## Filter such that we don't have any chromPeaks. + res <- filterRt(xod_xg, rt = c(4200, 4400)) checkTrue(all(rtime(res) >= 4200 & rtime(res) <= 4400)) - checkTrue(!hasDetectedFeatures(res)) - checkTrue(!hasAlignedFeatures(res)) + checkTrue(!hasChromPeaks(res)) + checkTrue(!hasFeatures(res)) checkTrue(length(processHistory(res)) == 0) ## No rt - res <- filterRt(od_xg, rt = c(10, 20)) + res <- filterRt(xod_xg, rt = c(10, 20)) checkTrue(length(res) == 0) - ## With adjusted retention time. - od_xgr <- adjustRtime(od_xg, param = FeatureGroupsParam(span = 0.5)) - res <- filterRt(od_xgr, rt = c(2700, 2900)) - checkEquals(hasDetectedFeatures(res), hasDetectedFeatures(od_xgr)) - checkEquals(hasAlignedFeatures(res), hasAlignedFeatures(od_xgr)) - checkEquals(hasAdjustedRtime(res), hasAdjustedRtime(od_xgr)) - checkTrue(length(processHistory(res, type = "Feature detection")) == 1) - checkTrue(length(processHistory(res, type = "Feature alignment")) == 1) - checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) - ## Retention time has to be within the range. By default we're supposed to - ## filter by adjusted rtime. + ## xod_xgr + res <- filterRt(xod_xgr, rt = c(2700, 2900)) checkTrue(all(rtime(res) >= 2700 & rtime(res) <= 2900)) + checkEquals(hasChromPeaks(res), hasChromPeaks(xod_xg)) + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_xgr)[, "rt"] >= 2700 & + chromPeaks(xod_xgr)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_xgr)[are_within,]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(all(adjustedRtime(res) >= 2700 & adjustedRtime(res) <= 2900)) checkTrue(!all(rtime(res, adjusted = FALSE) >= 2700 & rtime(res, adjusted = FALSE) <= 2900)) - ## Check if rtime is what we expect it to be: - keep_em <- rtime(od_xgr) >= 2700 & rtime(od_xgr) <= 2900 - checkEquals(rtime(res), rtime(od_xgr)[keep_em]) - checkEquals(rtime(res, adjusted = FALSE), - rtime(od_xgr, adjusted = FALSE)[keep_em]) - checkEquals(adjustedRtime(res), adjustedRtime(od_xgr)[keep_em]) - ## Check features. - keep_em <- features(od_xgr)[, "rt"] >= 2700 & features(od_xgr)[, "rt"] <= 2900 - checkEquals(features(od_xgr)[keep_em, ], features(res)) - ## Filtering for rt with no features drops also the adjusted rt. - res <- filterRt(od_xgr, rt = c(4200, 4400)) - checkTrue(!hasDetectedFeatures(res)) - checkTrue(!hasAdjustedRtime(res)) - checkTrue(length(processHistory(res)) == 0) - ## Enforce filtering on adjusted: - ## checkEquals(filterRt(od_xgr, rt = c(2700, 2900)), - ## filterRt(od_xgr, rt = c(2700, 2900), adjusted = TRUE)) - ## Filter using raw retention times - res <- filterRt(od_xgr, rt = c(2700, 2900), adjusted = FALSE) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res, type = "Peak detection")) == 1) + checkTrue(length(processHistory(res, type = "Peak grouping")) == 1) + checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) + ## Filter such that we don't have any chromPeaks. + res <- filterRt(xod_xgr, rt = c(4200, 4400), adjusted = TRUE) + checkTrue(hasAdjustedRtime(res)) + checkTrue(all(adjustedRtime(res) >= 4200 & adjustedRtime(res) <= 4400)) + checkTrue(all(rtime(res) >= 4200 & rtime(res) <= 4400)) + checkTrue(!all(rtime(res, adjusted = FALSE) >= 4200 & + rtime(res, adjusted = FALSE) <= 4400)) + checkTrue(!hasChromPeaks(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 1) + checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) + ## No rt + res <- filterRt(xod_xgr, rt = c(10, 20)) + checkTrue(length(res) == 0) + ## filter using raw rt + res <- filterRt(xod_xgr, rt = c(2700, 2900), adjusted = FALSE) checkTrue(!all(rtime(res) >= 2700 & rtime(res) <= 2900)) + checkEquals(hasChromPeaks(res), hasChromPeaks(xod_xg)) + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_xgr)[, "rt"] >= 2700 & + chromPeaks(xod_xgr)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_xgr)[are_within,]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(!all(adjustedRtime(res) >= 2700 & adjustedRtime(res) <= 2900)) checkTrue(all(rtime(res, adjusted = FALSE) >= 2700 & rtime(res, adjusted = FALSE) <= 2900)) - ## Features - can not really check here. - checkTrue(all(features(res)[, "rt"] >= 2700 & - features(res)[, "rt"] <= 2900)) - - ## Adjusted retention time AND grouping - od_xgrg <- groupFeatures(od_xgr, param = FeatureDensityParam()) - res <- filterRt(od_xgrg, rt = c(2700, 2900)) - checkEquals(hasDetectedFeatures(res), hasDetectedFeatures(od_xgrg)) - checkEquals(hasAlignedFeatures(res), hasAlignedFeatures(od_xgrg)) - checkEquals(hasAdjustedRtime(res), hasAdjustedRtime(od_xgrg)) - checkTrue(length(processHistory(res, type = "Feature detection")) == 1) - checkTrue(length(processHistory(res, type = "Feature alignment")) == 2) - checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) - ## Retention time has to be within the range. By default we're supposed to - ## filter by adjusted rtime. + checkTrue(!hasFeatures(res)) + + ## xod_xgrg + res <- filterRt(xod_xgrg, rt = c(2700, 2900)) checkTrue(all(rtime(res) >= 2700 & rtime(res) <= 2900)) + checkEquals(hasChromPeaks(res), hasChromPeaks(xod_xg)) + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_xgrg)[, "rt"] >= 2700 & + chromPeaks(xod_xgr)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_xgrg)[are_within,]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(all(adjustedRtime(res) >= 2700 & adjustedRtime(res) <= 2900)) checkTrue(!all(rtime(res, adjusted = FALSE) >= 2700 & rtime(res, adjusted = FALSE) <= 2900)) - ## Check if rtime is what we expect it to be: - keep_em <- rtime(od_xgrg) >= 2700 & rtime(od_xgrg) <= 2900 - checkEquals(rtime(res), rtime(od_xgrg)[keep_em]) - checkEquals(rtime(res, adjusted = FALSE), - rtime(od_xgrg, adjusted = FALSE)[keep_em]) - checkEquals(adjustedRtime(res), adjustedRtime(od_xgrg)[keep_em]) - ## Check features. - keep_em <- features(od_xgrg)[, "rt"] >= 2700 & features(od_xgrg)[, "rt"] <= 2900 - checkEquals(features(od_xgrg)[keep_em, ], features(res)) - ## Feature groups. - checkTrue(all(featureGroups(res)$rtmed >= 2700 & - featureGroups(res)$rtmed <= 2900)) - validObject(res) - ## Filtering for rt with no features drops also the adjusted rt. - res <- filterRt(od_xgrg, rt = c(4200, 4400)) - checkTrue(!hasDetectedFeatures(res)) - checkTrue(!hasAdjustedRtime(res)) - checkTrue(!hasAlignedFeatures(res)) - checkTrue(length(processHistory(res)) == 0) - ## Enforce filtering on adjusted: - ## checkEquals(filterRt(od_xgrg, rt = c(2700, 2900)), - ## filterRt(od_xgrg, rt = c(2700, 2900), adjusted = TRUE)) - ## Filter using raw retention times - res <- filterRt(od_xgrg, rt = c(2700, 2900), adjusted = FALSE) + checkTrue(length(processHistory(res, type = "Peak detection")) == 1) + checkTrue(length(processHistory(res, type = "Peak grouping")) == 2) + checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) + checkTrue(hasFeatures(res)) + checkTrue(all(featureDefinitions(res)$rtmed >= 2700 & + featureDefinitions(res)$rtmed <= 2900)) + ## Filter such that we don't have any chromPeaks. + res <- filterRt(xod_xgrg, rt = c(4200, 4400), adjusted = TRUE) + checkTrue(hasAdjustedRtime(res)) + checkTrue(all(adjustedRtime(res) >= 4200 & adjustedRtime(res) <= 4400)) + checkTrue(all(rtime(res) >= 4200 & rtime(res) <= 4400)) + checkTrue(!all(rtime(res, adjusted = FALSE) >= 4200 & + rtime(res, adjusted = FALSE) <= 4400)) + checkTrue(!hasChromPeaks(res)) + checkTrue(!hasFeatures(res)) + checkTrue(length(processHistory(res)) == 1) + checkTrue(length(processHistory(res, type = "Retention time correction")) == 1) + ## No rt + res <- filterRt(xod_xgrg, rt = c(10, 20)) + checkTrue(length(res) == 0) + ## filter using raw rt + res <- filterRt(xod_xgrg, rt = c(2700, 2900), adjusted = FALSE) checkTrue(!all(rtime(res) >= 2700 & rtime(res) <= 2900)) + checkEquals(hasChromPeaks(res), hasChromPeaks(xod_xg)) + checkTrue(all(chromPeaks(res)[, "rt"] >= 2700 & + chromPeaks(res)[, "rt"] <= 2900)) + are_within <- chromPeaks(xod_xgrg)[, "rt"] >= 2700 & + chromPeaks(xod_xgrg)[, "rt"] <= 2900 + checkEquals(chromPeaks(res), chromPeaks(xod_xgrg)[are_within,]) + checkTrue(hasAdjustedRtime(res)) + checkTrue(!all(adjustedRtime(res) >= 2700 & adjustedRtime(res) <= 2900)) checkTrue(all(rtime(res, adjusted = FALSE) >= 2700 & rtime(res, adjusted = FALSE) <= 2900)) - ## Features - can not really check here. - checkTrue(all(features(res)[, "rt"] >= 2700 & - features(res)[, "rt"] <= 2900)) - + checkTrue(hasFeatures(res)) + checkTrue(all(featureDefinitions(res)$rtmed >= 2700 & + featureDefinitions(res)$rtmed <= 2900)) } ## Test the coercion method. @@ -637,7 +822,7 @@ test_as_XCMSnExp_xcmsSet <- function() { res <- xcms:::.XCMSnExp2xcmsSet(od_x) res <- as(od_x, "xcmsSet") ## Results should be the same as in xs. - checkEquals(res@peaks, features(od_x)) + checkEquals(res@peaks, chromPeaks(od_x)) checkEquals(res@.processHistory, processHistory(od_x)) checkEquals(phenoData(res), pData(od_x)) checkEquals(filepaths(res), fileNames(od_x)) @@ -651,24 +836,24 @@ test_as_XCMSnExp_xcmsSet <- function() { ## res <- fillPeaks(res) ## Add groups. - od_2 <- groupFeatures(od_x, param = FeatureDensityParam()) - checkEquals(featureGroups(od_2)$featureidx, groupidx(res)) + od_2 <- groupChromPeaks(od_x, param = PeakDensityParam()) + checkEquals(featureDefinitions(od_2)$peakidx, groupidx(res)) ## rt correction - od_3 <- adjustRtime(od_2, param = FeatureGroupsParam(minFraction = 1, + od_3 <- adjustRtime(od_2, param = PeakGroupsParam(minFraction = 1, span = 0.4)) ## With groups. res <- as(od_2, "xcmsSet") checkEquals(res@groups, - S4Vectors::as.matrix(featureGroups(od_2)[, -ncol(featureGroups(od_2))])) - checkEquals(res@groupidx, featureGroups(od_2)$featureidx) + S4Vectors::as.matrix(featureDefinitions(od_2)[, -ncol(featureDefinitions(od_2))])) + checkEquals(res@groupidx, featureDefinitions(od_2)$peakidx) ## With adjusted retention time. res_2 <- retcor.peakgroups(res, missing = 0, span = 0.4) res <- as(od_3, "xcmsSet") checkTrue(any(unlist(res@rt$raw) != unlist(res@rt$corrected))) checkEquals(res@rt$corrected, res_2@rt$corrected) - checkEquals(features(od_3), peaks(res)) + checkEquals(chromPeaks(od_3), peaks(res)) checkEquals(peaks(res_2), peaks(res)) ## Test with different binning methods: @@ -696,73 +881,117 @@ test_MsFeatureData_class_validation <- function() { fd$a <- 5 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) rm("a", envir = fd) - ## Check features - fd$features <- 4 + ## Check chromPeaks + fd$chromPeaks <- 4 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) fdm <- matrix(ncol = 3, nrow = 5) colnames(fdm) <- c("a", "b", "sample") - fd$features <- fdm + fd$chromPeaks <- fdm checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) - rm("features", envir = fd) - ## featureGroups - fd$features <- xs_2@peaks - fd$featureGroups <- 4 + rm("chromPeaks", envir = fd) + ## featureDefinitions + fd$chromPeaks <- xs_2@peaks + fd$featureDefinitions <- 4 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) fg <- DataFrame(fdm) - fd$featureGroups <- fg + fd$featureDefinitions <- fg checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) fg <- DataFrame(xs_2@groups) - fg$featureidx <- xs_2@groupidx + fg$peakidx <- xs_2@groupidx fg_2 <- fg fg_2$mzmin <- "a" - fd$featureGroups <- fg_2 + fd$featureDefinitions <- fg_2 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) fg_2 <- fg - fg_2$featureidx[[1]] <- c(50000, 3) - fd$featureGroups <- fg_2 + fg_2$peakidx[[1]] <- c(50000, 3) + fd$featureDefinitions <- fg_2 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) ## adjustedRtime - fd$featureGroups <- fg + fd$featureDefinitions <- fg fd$adjustedRtime <- 4 checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) fd$adjustedRtime <- list(1:5, "b") checkTrue(!is.logical(xcms:::validateMsFeatureData(fd))) ## Now check that we pass if we put all correct data into the object: fd <- new("MsFeatureData") - fd$features <- xs_2@peaks - checkTrue(xcms:::validateMsFeatureData(fd)) + fd$chromPeaks <- xs_2@peaks + checkTrue(length(xcms:::validateMsFeatureData(fd)) == 0) fd$adjustedRtime <- xs_2@rt$corrected - checkTrue(xcms:::validateMsFeatureData(fd)) + checkTrue(length(xcms:::validateMsFeatureData(fd)) == 0) fg <- DataFrame(xs_2@groups) - fg$featureidx <- xs_2@groupidx - checkTrue(xcms:::validateMsFeatureData(fd)) + fg$peakidx <- xs_2@groupidx + checkTrue(length(xcms:::validateMsFeatureData(fd)) == 0) } test_MsFeatureData_class_accessors <- function() { fd <- new("MsFeatureData") library(S4Vectors) - checkTrue(!hasDetectedFeatures(fd)) + checkTrue(!hasChromPeaks(fd)) checkTrue(!hasAdjustedRtime(fd)) - checkTrue(!hasAlignedFeatures(fd)) - suppressWarnings(checkEquals(features(fd), NULL)) - suppressWarnings(checkEquals(featureGroups(fd), NULL)) + checkTrue(!hasFeatures(fd)) + suppressWarnings(checkEquals(chromPeaks(fd), NULL)) + suppressWarnings(checkEquals(featureDefinitions(fd), NULL)) suppressWarnings(checkEquals(adjustedRtime(fd), NULL)) - ## features - features(fd) <- xs_2@peaks - checkTrue(hasDetectedFeatures(fd)) - checkEquals(features(fd), xs_2@peaks) - ## featureGroups + ## chromPeaks + chromPeaks(fd) <- xs_2@peaks + checkTrue(hasChromPeaks(fd)) + checkEquals(chromPeaks(fd), xs_2@peaks) + ## featureDefinitions fg <- DataFrame(xs_2@groups) - fg$featureidx <- xs_2@groupidx - featureGroups(fd) <- fg - checkTrue(hasAlignedFeatures(fd)) - checkEquals(featureGroups(fd), fg) + fg$peakidx <- xs_2@groupidx + featureDefinitions(fd) <- fg + checkTrue(hasFeatures(fd)) + checkEquals(featureDefinitions(fd), fg) ## adjustedRtime adjustedRtime(fd) <- xs_2@rt$corrected checkTrue(hasAdjustedRtime(fd)) checkEquals(adjustedRtime(fd), xs_2@rt$corrected) } + +## Test extraction of chromatograms. +test_extractChromatograms <- function() { + ## Have: od_x: OnDiskMSNnExp + ## xod_x: XCMSnExp, with detected chromPeaks. + ## xod_xg: with feature groups. + ## xod_xgr: with adjusted retention times (no feature groups) + ## xod_xgrg: adjusted rt and feature groups. + + ## XCMSnExp: TIC - can NOT compare with the reported TIC, as that is + ## different! Eventually some background adjustment performed? + ## BPC - CDF don't habe a BPC. + rtr <- c(2600, 2700) + res <- xcms:::extractChromatograms(xod_x, aggregationFun = "max", rt = rtr) + checkTrue(all(rtime(res[[1]]) >= rtr[1])) + checkTrue(all(rtime(res[[1]]) <= rtr[2])) + checkTrue(all(rtime(res[[2]]) >= rtr[1])) + checkTrue(all(rtime(res[[2]]) <= rtr[2])) + checkTrue(all(rtime(res[[3]]) >= rtr[1])) + checkTrue(all(rtime(res[[3]]) <= rtr[2])) + tmp <- filterRt(filterFile(xod_x, file = 2), rt = rtr) + checkEquals(rtime(tmp), rtime(res[[2]])) + ints <- spectrapply(tmp, function(z) return(max(intensity(z)))) + checkEquals(unlist(ints), intensity(res[[2]])) + ## Check names + checkEquals(names(rtime(res[[1]])), names(intensity(res[[1]]))) + ## Assure we get the same with an OnDiskMSnExp and grouped XCMSnExp + res_2 <- xcms:::extractChromatograms(od_x, aggregationFun = "max", rt = rtr) + checkEquals(res, res_2) + res_3 <- xcms:::extractChromatograms(xod_xg, aggregationFun = "max", rt = rtr) + checkEquals(res, res_3) + + ## XCMSnExp: with mzrange and rtrange: + mzr <- c(120, 130) + tmp <- filterMz(xod_xg, mz = mzr) + featureDefinitions(tmp) + tmp <- filterRt(xod_xg, rt = rtr) + featureDefinitions(tmp) + res_2 <- xcms:::extractChromatograms(xod_xg, rt = rtr, mz = mzr) + ## + + ## XCMSnExp with adjusted rtime +} + ############################################################ ## Test getEIC alternatives. dontrun_getEIC_alternatives <- function() { @@ -774,16 +1003,30 @@ dontrun_getEIC_alternatives <- function() { system.file('cdf/KO/ko18.CDF', package = "faahKO")) od <- readMSData2(fls) cwp <- CentWaveParam(noise = 10000, snthresh = 40) - od_x <- detectFeatures(od, param = cwp) + od_x <- findChromPeaks(od, param = cwp) - rtr <- c(2600, 2601) + ## with this one we get 3 spectras back, one in each file. + rtr <- c(2787, 2788) res <- filterRt(od_x, rt = rtr) - od_xg <- groupFeatures(od_x, param = FeatureDensityParam()) - od_xgr <- adjustRtime(od_xg, param = FeatureGroupsParam(span = 0.4)) + ## ----------- + ## That's to test .extractChromatogram + mzr <- c(279, 279) + chrs <- extractChromatograms(od_x, mzrange = mzr) + ## input parameter + x <- od_x + rm(rtrange) + rm(mzrange) + mzrange <- mzr + aggregationFun <- "sum" + ## function call + ## ----------- + + od_xg <- groupChromPeaks(od_x, param = PeakDensityParam()) + od_xgr <- adjustRtime(od_xg, param = PeakGroupsParam(span = 0.4)) - rtr <- as.matrix(featureGroups(od_xg)[1:5, c("rtmin", "rtmax")]) - mzr <- as.matrix(featureGroups(od_xg)[1:5, c("mzmin", "mzmax")]) + rtr <- as.matrix(featureDefinitions(od_xg)[1:5, c("rtmin", "rtmax")]) + mzr <- as.matrix(featureDefinitions(od_xg)[1:5, c("mzmin", "mzmax")]) system.time( res1 <- xcms:::.extractMsData(od, rtrange = rtr[1, ], mzrange = mzr[1, ]) diff --git a/inst/unitTests/runit.binning.R b/inst/unitTests/runit.binning.R index 23405300a..3bdff1fea 100644 --- a/inst/unitTests/runit.binning.R +++ b/inst/unitTests/runit.binning.R @@ -642,9 +642,12 @@ test_breaks <- function() { ## brksR <- seq((200 - 0.1), (600), by = 0.2) brks <- breaks_on_binSize((200 - 0.1), (600), binSize = 0.2) - checkTrue(length(brks) > length(brksR)) - checkEquals(brks[-length(brks)], brksR) - checkEquals(brks[length(brks)], 600) + cmn <- 1:min(c(length(brks), length(brksR))) + checkEquals(brks[cmn], brksR[cmn]) + ## Now, that below breaks on a windows build machine (issue #127) + ## checkTrue(length(brks) > length(brksR)) + ## checkEquals(brks[-length(brks)], brksR) + ## checkEquals(brks[length(brks)], 600) } ############################################################ diff --git a/inst/unitTests/runit.do_adjustRtime.R b/inst/unitTests/runit.do_adjustRtime.R index 8f476c0c3..d035ad4ec 100644 --- a/inst/unitTests/runit.do_adjustRtime.R +++ b/inst/unitTests/runit.do_adjustRtime.R @@ -1,43 +1,43 @@ ## retention time correction methods and functionality related to adjusted ## retention times. -test_adjustRtime_FeatureGroups <- function() { +test_adjustRtime_PeakGroups <- function() { xod <- faahko_xod xs <- faahko_xs ## Group these xsg <- group(xs) - xodg <- groupFeatures(xod, - param = FeatureDensityParam(sampleGroups = xs$class)) - checkEquals(peaks(xsg), features(xodg)) - checkEquals(xsg@groupidx, featureGroups(xodg)$featureidx) + xodg <- groupChromPeaks(xod, + param = PeakDensityParam(sampleGroups = xs$class)) + checkEquals(peaks(xsg), chromPeaks(xodg)) + checkEquals(xsg@groupidx, featureDefinitions(xodg)$peakidx) checkTrue(length(processHistory(xodg, - type = xcms:::.PROCSTEP.FEATURE.DETECTION)) == 1) + type = xcms:::.PROCSTEP.PEAK.DETECTION)) == 1) checkTrue(length(processHistory(xodg, - type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)) == 1) + type = xcms:::.PROCSTEP.PEAK.GROUPING)) == 1) ## Now do the retention time correction xsr <- retcor(xsg, method = "peakgroups") minFr <- (length(fileNames(xod)) - 1) / length(fileNames(xod)) - p <- FeatureGroupsParam(minFraction = minFr) + p <- PeakGroupsParam(minFraction = minFr) xodr <- adjustRtime(xodg, param = p) ## Check that we've got process histories. checkTrue(validObject(xodr)) - checkTrue(hasDetectedFeatures(xodr)) - checkTrue(!hasAlignedFeatures(xodr)) + checkTrue(hasChromPeaks(xodr)) + checkTrue(!hasFeatures(xodr)) ## But we would like to keep the related process history step: checkTrue(hasAdjustedRtime(xodr)) - checkTrue(hasAlignedFeatures(xodg)) + checkTrue(hasFeatures(xodg)) ## We want to keep the process history step of the feature alignment! checkTrue(length(processHistory(xodr, - type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)) == 1) + type = xcms:::.PROCSTEP.PEAK.GROUPING)) == 1) checkTrue(length(processHistory(xodr, type = xcms:::.PROCSTEP.RTIME.CORRECTION)) == 1) ## Different from original: - checkTrue(sum(features(xod)[, "rt"] != features(xodr)[, "rt"]) > 200) - checkTrue(sum(features(xod)[, "rtmin"] != features(xodr)[, "rtmin"]) > 200) - checkTrue(sum(features(xod)[, "rtmax"] != features(xodr)[, "rtmax"]) > 200) + checkTrue(sum(chromPeaks(xod)[, "rt"] != chromPeaks(xodr)[, "rt"]) > 200) + checkTrue(sum(chromPeaks(xod)[, "rtmin"] != chromPeaks(xodr)[, "rtmin"]) > 200) + checkTrue(sum(chromPeaks(xod)[, "rtmax"] != chromPeaks(xodr)[, "rtmax"]) > 200) ## between xcmsSet and XCMSnExp - checkEquals(features(xodr), peaks(xsr)) + checkEquals(chromPeaks(xodr), peaks(xsr)) ## To compare the adjusted retention time we have to extract it by sample! ## Otherwise the ordering will not be the same, as rtime is ordered by ## retention time, but @rt$raw by sample. @@ -47,38 +47,38 @@ test_adjustRtime_FeatureGroups <- function() { checkEquals(unlist(rtime(xod, bySample = TRUE), use.names = FALSE), unlist(xs@rt$raw, use.names = FALSE)) ## Doing an additional grouping - xodrg <- groupFeatures(xodr, param = FeatureDensityParam(sampleGroups = - xs$class)) + xodrg <- groupChromPeaks(xodr, param = PeakDensityParam(sampleGroups = + xs$class)) checkTrue(length(processHistory(xodrg, - type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)) == 2) + type = xcms:::.PROCSTEP.PEAK.GROUPING)) == 2) checkTrue(hasAdjustedRtime(xodrg)) - checkTrue(hasAlignedFeatures(xodrg)) + checkTrue(hasFeatures(xodrg)) xsrg <- group(xsr) - checkEquals(xsrg@groupidx, featureGroups(xodrg)$featureidx) + checkEquals(xsrg@groupidx, featureDefinitions(xodrg)$peakidx) ## Mod settings: xsr <- retcor(xsg, method = "peakgroups", missing = 0, span = 1) - xodr <- adjustRtime(xodg, param = FeatureGroupsParam(minFraction = 1, + xodr <- adjustRtime(xodg, param = PeakGroupsParam(minFraction = 1, span = 1)) - checkEquals(features(xodr), peaks(xsr)) + checkEquals(chromPeaks(xodr), peaks(xsr)) checkEquals(unlist(adjustedRtime(xodr, bySample = TRUE), use.names = FALSE), unlist(xsr@rt$corrected, use.names = FALSE)) xsr <- retcor(xsg, method = "peakgroups", missing = 0, span = 1, smooth = "linear") - xodr <- adjustRtime(xodg, param = FeatureGroupsParam(minFraction = 1, + xodr <- adjustRtime(xodg, param = PeakGroupsParam(minFraction = 1, span = 1, smooth = "linear")) - checkEquals(features(xodr), peaks(xsr)) + checkEquals(chromPeaks(xodr), peaks(xsr)) checkEquals(unlist(adjustedRtime(xodr, bySample = TRUE), use.names = FALSE), unlist(xsr@rt$corrected, use.names = FALSE)) xsr <- retcor(xsg, method = "peakgroups", missing = 0, span = 1, family = "symmetric") - xodr <- adjustRtime(xodg, param = FeatureGroupsParam(minFraction = 1, + xodr <- adjustRtime(xodg, param = PeakGroupsParam(minFraction = 1, span = 1, family = "symmetric")) - checkEquals(features(xodr), peaks(xsr)) + checkEquals(chromPeaks(xodr), peaks(xsr)) checkEquals(unlist(adjustedRtime(xodr, bySample = TRUE), use.names = FALSE), unlist(xsr@rt$corrected, use.names = FALSE)) } @@ -140,7 +140,7 @@ dontrun_test_retcor.peakgroups <- function() { ## That's to evaluate the do_ function with the original code. Once the ## retcor.peakgroups calls the do_function we rename it to dontrun. -test_do_adjustRtime_featureGroups_implementation <- function() { +test_do_adjustRtime_peakGroups_implementation <- function() { xs <- faahko xsg <- group(xs) @@ -148,8 +148,8 @@ test_do_adjustRtime_featureGroups_implementation <- function() { xsa <- retcor(xsg, method = "peakgroups", missing = misSamp) minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, minFraction = minFr) checkEquals(xsa@rt$corrected, res) @@ -159,8 +159,8 @@ test_do_adjustRtime_featureGroups_implementation <- function() { xsa <- retcor(xsg, method = "peakgroups", missing = misSamp) minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, minFraction = minFr) checkEquals(xsa@rt$corrected, res) @@ -170,39 +170,39 @@ test_do_adjustRtime_featureGroups_implementation <- function() { xsa <- retcor(xsg, method = "peakgroups", missing = misSamp, extra = xtr) minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, - minFraction = minFr, extraFeatures = xtr) + minFraction = minFr, extraPeaks = xtr) checkEquals(xsa@rt$corrected, res) xsa <- retcor(xsg, method = "peakgroups", missing = misSamp, extra = xtr, smooth = "linear") minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, - minFraction = minFr, extraFeatures = xtr, + minFraction = minFr, extraPeaks = xtr, smooth = "linear") checkEquals(xsa@rt$corrected, res) xsa <- retcor(xsg, method = "peakgroups", missing = misSamp, extra = xtr, family = "symmetric") minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, - minFraction = minFr, extraFeatures = xtr, + minFraction = minFr, extraPeaks = xtr, family = "symmetric") checkEquals(xsa@rt$corrected, res) xsa <- retcor(xsg, method = "peakgroups", missing = misSamp, extra = xtr, span = 1) minFr <- (length(sampnames(xs)) - misSamp) / length(sampnames(xs)) - res <- do_adjustRtime_featureGroups(features = peaks(xs), - featureIndex = xsg@groupidx, + res <- do_adjustRtime_peakGroups(peaks = peaks(xs), + peakIndex = xsg@groupidx, rtime = xsg@rt$raw, - minFraction = minFr, extraFeatures = xtr, + minFraction = minFr, extraPeaks = xtr, span = 1) checkEquals(xsa@rt$corrected, res) } @@ -219,15 +219,15 @@ dontrun_do_adjustRtime_peakgroups_implementation <- function() { od <- readMSData2(faahko_files) - xod <- detectFeatures(od, param = CentWaveParam(noise = 100, + xod <- findChromPeaks(od, param = CentWaveParam(noise = 100, snthresh = 20)) xs <- xcmsSet(faahko_files, profparam = list(step = 0), method = "centWave", noise = 100, snthresh = 20) - checkEquals(features(xod), peaks(xs)) + checkEquals(chromPeaks(xod), peaks(xs)) ## feature grouping - p <- FeatureDensityParam(sampleGroups = rep(c("KO", "WT"), each = 3)) - xod <- groupFeatures(xod, param = p) + p <- PeakDensityParam(sampleGroups = rep(c("KO", "WT"), each = 3)) + xod <- groupChromPeaks(xod, param = p) xs <- group(xs, method = "density") ## Feature alignment on those: @@ -235,8 +235,8 @@ dontrun_do_adjustRtime_peakgroups_implementation <- function() { ## minFr <- 5/6 - res <- xcms:::do_adjustRtime_featureGroups(features = features(xod), - featureGroups(xod)$featureidx, + res <- xcms:::do_adjustRtime_peakGroups(peaks = chromPeaks(xod), + featureDefinitions(xod)$peakidx, rtime = rtime(xod, bySample = TRUE), minFraction = minFr) a <- unname(unlist(res, use.names = FALSE)) @@ -254,20 +254,20 @@ dontrun_do_adjustRtime_peakgroups_implementation <- function() { ## That's strange! ## cfun <- stepfun(rtr[-1] - diff(rtr) / 2, rtr - rtdevsmo) cfun <- stepfun(rtr[-1] - diff(rtr) / 2, rtc) - corFeat <- features(xod) + corFeat <- chromPeaks(xod) whichSamp <- which(corFeat[, "sample"] == 1) corFeat[whichSamp, c("rt", "rtmin", "rtmax")] <- cfun(corFeat[whichSamp, c("rt", "rtmin", "rtmax")]) checkEquals(corFeat[whichSamp, ], peaks(xs)[whichSamp, ]) - checkTrue(any(peaks(xs) != features(xod))) + checkTrue(any(peaks(xs) != chromPeaks(xod))) ## Do the backwards correction. adjFun <- stepfun(rtc[-1] - diff(rtc) / 2, rtr) origFeats <- corFeat origFeats[whichSamp, c("rt", "rtmin", "rtmax")] <- adjFun(corFeat[whichSamp, c("rt", "rtmin", "rtmax")]) - checkEquals(features(xod)[whichSamp, ], origFeats[whichSamp, ]) + checkEquals(chromPeaks(xod)[whichSamp, ], origFeats[whichSamp, ]) ## OK. } @@ -279,14 +279,14 @@ test_applyRtAdjustment <- function() { ## align em. xsa <- retcor(xsg, method = "peakgroups") - pksAdj <- xcms:::.applyRtAdjToFeatures(peaks(xsg), - rtraw = xsa@rt$raw, - rtadj = xsa@rt$corrected) + pksAdj <- xcms:::.applyRtAdjToChromPeaks(peaks(xsg), + rtraw = xsa@rt$raw, + rtadj = xsa@rt$corrected) checkEquals(pksAdj, peaks(xsa)) ## Reset em. - pksRaw <- xcms:::.applyRtAdjToFeatures(pksAdj, - rtraw = xsa@rt$corrected, - rtadj = xsa@rt$raw) + pksRaw <- xcms:::.applyRtAdjToChromPeaks(pksAdj, + rtraw = xsa@rt$corrected, + rtadj = xsa@rt$raw) checkEquals(pksRaw, peaks(xsg)) } @@ -297,7 +297,7 @@ test_obiwarp <- function() { od <- faahko_od xod <- faahko_xod ## Feature alignment on those: - ## object <- detectFeatures(faahko_od, param = CentWaveParam(noise = 10000, + ## object <- findChromPeaks(faahko_od, param = CentWaveParam(noise = 10000, ## snthresh = 40)) prm <- ObiwarpParam(binSize = 1) xs_2 <- retcor.obiwarp(xs, profStep = binSize(prm)) @@ -314,10 +314,18 @@ test_obiwarp <- function() { checkEquals(adjustedRtime(res_3, bySample = TRUE), res) checkEquals(adjustedRtime(res_3, bySample = TRUE), unname(split(unname(res_2), fromFile(od)))) - ## Check if features were corrected correctly - ## File issue on that! retcor.obiwarp does use round for the adjustment! + ## Check if peaks were corrected correctly + checkTrue(sum(chromPeaks(res_3)[, "rt"] == chromPeaks(xod)) < + nrow(chromPeaks(res_3)) / 2) + ## Dropping the adjusted rtime on these + hasAdjustedRtime(res_3) + tmp <- dropAdjustedRtime(res_3) + checkEquals(chromPeaks(tmp), chromPeaks(xod)) + + ## File issue on that! retcor.obiwarp does use round for the adjustment of + ## the peak! ## -> issue #122 - ## checkEquals(features(res_3), peaks(xs_2)) + ## checkEquals(chromPeaks(res_3), peaks(xs_2)) ## Manually specify center Sample centerSample(prm) <- 3 diff --git a/inst/unitTests/runit.do_detectFeatures_MSW.R b/inst/unitTests/runit.do_findChromPeaks_MSW.R similarity index 53% rename from inst/unitTests/runit.do_detectFeatures_MSW.R rename to inst/unitTests/runit.do_findChromPeaks_MSW.R index 1723c6bab..535c05711 100644 --- a/inst/unitTests/runit.do_detectFeatures_MSW.R +++ b/inst/unitTests/runit.do_findChromPeaks_MSW.R @@ -1,60 +1,60 @@ ############################################################ -## do_detectFeatures_MSW tests +## do_findPeaks_MSW tests xraw <- deepCopy(microtofq_xr) -test_do_detectFeatures_MSW <- function() { - feats1 <- xcms:::do_detectFeatures_MSW(xraw@env$intensity, - xraw@env$mz, - snthresh = 100) - feats2 <- xcms:::do_detectFeatures_MSW(xraw@env$intensity, - xraw@env$mz, - snthresh = 50) +test_do_findPeaks_MSW <- function() { + feats1 <- xcms:::do_findPeaks_MSW(xraw@env$intensity, + xraw@env$mz, + snthresh = 100) + feats2 <- xcms:::do_findPeaks_MSW(xraw@env$intensity, + xraw@env$mz, + snthresh = 50) checkTrue(nrow(feats2) > nrow(feats1)) } -test_detectFeatures_MSW <- function() { +test_findChromPeaks_MSW <- function() { ## library(MSnbase) ## od <- readMSData2(mzf) od <- microtofq_od ## Restrict to first spectrum od1 <- od[1] sp1 <- od[[1]] - res_1 <- do_detectFeatures_MSW(mz = mz(sp1), int = intensity(sp1)) + res_1 <- do_findPeaks_MSW(mz = mz(sp1), int = intensity(sp1)) mp <- MSWParam() - res_2 <- detectFeatures(od1, param = mp) - checkEquals(res_1, features(res_2)[, colnames(res_1), drop = FALSE]) + res_2 <- findChromPeaks(od1, param = mp) + checkEquals(res_1, chromPeaks(res_2)[, colnames(res_1), drop = FALSE]) ## Changing settings. snthresh(mp) <- 1 nearbyPeak(mp) <- FALSE - res_1 <- do_detectFeatures_MSW(mz = mz(sp1), int = intensity(sp1), - snthresh = 1, nearbyPeak = FALSE) - res_2 <- detectFeatures(od1, param = mp, return.type = "list") + res_1 <- do_findPeaks_MSW(mz = mz(sp1), int = intensity(sp1), + snthresh = 1, nearbyPeak = FALSE) + res_2 <- findChromPeaks(od1, param = mp, return.type = "list") checkEquals(res_1, res_2[[1]][, colnames(res_1)]) peakThr(mp) <- 200 - res_1 <- do_detectFeatures_MSW(mz = mz(sp1), int = intensity(sp1), - snthresh = 1, nearbyPeak = FALSE, - peakThr = 200) - res_2 <- detectFeatures(od1, param = mp, return.type = "list") + res_1 <- do_findPeaks_MSW(mz = mz(sp1), int = intensity(sp1), + snthresh = 1, nearbyPeak = FALSE, + peakThr = 200) + res_2 <- findChromPeaks(od1, param = mp, return.type = "list") checkEquals(res_1, res_2[[1]][, colnames(res_1)]) addParams(mp) <- list(forder = 2) - res_3 <- do_detectFeatures_MSW(mz = mz(sp1), int = intensity(sp1), - snthresh = 1, nearbyPeak = FALSE, - peakThr = 200, forder = 2) - res_4 <- detectFeatures(od1, param = mp, return.type = "list") + res_3 <- do_findPeaks_MSW(mz = mz(sp1), int = intensity(sp1), + snthresh = 1, nearbyPeak = FALSE, + peakThr = 200, forder = 2) + res_4 <- findChromPeaks(od1, param = mp, return.type = "list") checkEquals(res_3, res_4[[1]][, colnames(res_3)]) addParams(mp) <- list(forder = 2, dorder = 1) - res_3 <- do_detectFeatures_MSW(mz = mz(sp1), int = intensity(sp1), - snthresh = 1, nearbyPeak = FALSE, - peakThr = 200, forder = 2, dorder = 1) - res_4 <- detectFeatures(od1, param = mp, return.type = "list") + res_3 <- do_findPeaks_MSW(mz = mz(sp1), int = intensity(sp1), + snthresh = 1, nearbyPeak = FALSE, + peakThr = 200, forder = 2, dorder = 1) + res_4 <- findChromPeaks(od1, param = mp, return.type = "list") checkEquals(res_3, res_4[[1]][, colnames(res_3)]) } ############################################################ ## Test the implementation of the "do" function -dontrun_test_do_detectFeatures_MSW_impl <- function() { +dontrun_test_do_findPeaks_MSW_impl <- function() { library(xcms) library(RUnit) diff --git a/inst/unitTests/runit.do_detectFeatures_centWave.R b/inst/unitTests/runit.do_findChromPeaks_centWave.R similarity index 85% rename from inst/unitTests/runit.do_detectFeatures_centWave.R rename to inst/unitTests/runit.do_findChromPeaks_centWave.R index 56b0ec923..4bf20fb56 100644 --- a/inst/unitTests/runit.do_detectFeatures_centWave.R +++ b/inst/unitTests/runit.do_findChromPeaks_centWave.R @@ -1,4 +1,4 @@ -## Test detectFeatures centWave +## Test findChromPeaks centWave ## library(faahKO) fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"), @@ -13,20 +13,20 @@ fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"), xr <- deepCopy(faahko_xr_1) onDisk <- filterFile(faahko_od, file = 1) -test_do_detectFeatures_centWave <- function() { +test_do_findChromPeaks_centWave <- function() { ## xr <- xcmsRaw(fs[1], profstep = 0) ## We expect that changing a parameter has an influence on the result. mzVals <- xr@env$mz intVals <- xr@env$intensity ## Define the values per spectrum: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) - res1 <- do_detectFeatures_centWave(mz = mzVals, + res1 <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, snthresh = 200, noise = 4000) - res2 <- do_detectFeatures_centWave(mz = mzVals, + res2 <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, @@ -41,15 +41,15 @@ test_do_detectFeatures_centWave <- function() { intVals <- xr@env$intensity ## Define the values per spectrum: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) - res_2 <- do_detectFeatures_centWave(mz = mzVals, int = intVals, + res_2 <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, noise = 2000) checkEquals(res_1@.Data, res_2) } -## Evaluate the featureDetection method using the centWave method on +## Evaluate the peak detection method using the centWave method on ## OnDiskMSnExp and on MSnExp objects. -test_featureDetection_centWave <- function() { +test_findChromPeaks_centWave <- function() { ## Control library(MSnbase) ## xr <- xcmsRaw(fs[1], profstep = 0) @@ -65,30 +65,30 @@ test_featureDetection_centWave <- function() { ## OnDiskMSnExp ## onDisk <- readMSData2(fs[1], msLevel. = 1) cwp <- CentWaveParam(ppm = ppm, snthresh = snthresh, noise = 100000) - res <- detectFeatures(onDisk, param = cwp, return.type = "list") + res <- findChromPeaks(onDisk, param = cwp, return.type = "list") checkEquals(res[[1]], peaks(xs)@.Data) ## ## MSnExp ## inMem <- readMSData(f[1], msLevel. = 1) ## suppressWarnings( - ## res_2 <- detectFeatures(inMem, param = cwp, return.type = "list") + ## res_2 <- findChromPeaks(inMem, param = cwp, return.type = "list") ## ) ## checkEquals(res_2[[1]], peaks(xs)@.Data) ## returning an xcmsSet - res <- detectFeatures(onDisk, param = cwp, return.type = "xcmsSet") + res <- findChromPeaks(onDisk, param = cwp, return.type = "xcmsSet") checkEquals(peaks(res), peaks(xs)) ## suppressWarnings( - ## res <- detectFeatures(inMem, param = cwp, return.type = "xcmsSet") + ## res <- findChromPeaks(inMem, param = cwp, return.type = "xcmsSet") ## ) ## checkEquals(peaks(res), peaks(xs)) ## Return type XCMSnExp - res <- detectFeatures(onDisk, param = cwp) - checkTrue(hasDetectedFeatures(res)) + res <- findChromPeaks(onDisk, param = cwp) + checkTrue(hasChromPeaks(res)) checkTrue(!hasAdjustedRtime(res)) - checkTrue(!hasAlignedFeatures(res)) - checkEquals(peaks(xs)@.Data, features(res)) + checkTrue(!hasFeatures(res)) + checkEquals(peaks(xs)@.Data, chromPeaks(res)) } dontrun_test_benchmark_centWaves <- function() { @@ -106,10 +106,10 @@ dontrun_test_benchmark_centWaves <- function() { ## onDisk <- readMSData2(f[1], msLevel. = 1) register(SerialParam()) system.time( - tmp <- detectFeatures(onDisk, param = cwp) + tmp <- findChromPeaks(onDisk, param = cwp) ) ## 9.7sec system.time( - tmp <- detectFeatures(onDisk, param = cwp, return.type = "xcmsSet") + tmp <- findChromPeaks(onDisk, param = cwp, return.type = "xcmsSet") ) ## 12sec system.time( tmp <- xcmsSet(f[1], profparam = list(profstep = 0), ppm = ppm, @@ -119,16 +119,16 @@ dontrun_test_benchmark_centWaves <- function() { inMem <- readMSData(f[1], msLevel. = 1) register(SerialParam()) - ## detectFeatures,MSnExp and findPeaks.centWave should be about similar. + ## findChromPeaks,MSnExp and findPeaks.centWave should be about similar. microbenchmark(findPeaks.centWave(xr, ppm = ppm, snthresh = snthresh), - detectFeatures(inMem, param = cwp), times = 3) + findChromPeaks(inMem, param = cwp), times = 3) ## findPeaks.centWave is about 1 second faster. - ## detectFeatures,OnDiskMSnExp and xcmsSet should be about similar. + ## findChromPeaks,OnDiskMSnExp and xcmsSet should be about similar. microbenchmark(xcmsSet(f[1], profparam = list(profstep = 0), ppm = ppm, snthresh = snthresh, method = "centWave"), - detectFeatures(onDisk, param = cwp), - detectFeatures(inMem, param = cwp), + findChromPeaks(onDisk, param = cwp), + findChromPeaks(inMem, param = cwp), times = 3) } @@ -147,10 +147,10 @@ dontrun_test_benchmark_centWaves <- function() { ## onDisk <- readMSData2(f[1], msLevel. = 1) register(SerialParam()) system.time( - tmp <- detectFeatures(onDisk, param = cwp) + tmp <- findChromPeaks(onDisk, param = cwp) ) ## 9.7sec system.time( - tmp <- detectFeatures(onDisk, param = cwp, return.type = "xcmsSet") + tmp <- findChromPeaks(onDisk, param = cwp, return.type = "xcmsSet") ) ## 12sec system.time( tmp <- xcmsSet(f[1], profparam = list(profstep = 0), ppm = ppm, @@ -160,16 +160,16 @@ dontrun_test_benchmark_centWaves <- function() { inMem <- readMSData(f[1], msLevel. = 1) register(SerialParam()) - ## detectFeatures,MSnExp and findPeaks.centWave should be about similar. + ## findChromPeaks,MSnExp and findPeaks.centWave should be about similar. microbenchmark(findPeaks.centWave(xr, ppm = ppm, snthresh = snthresh), - detectFeatures(inMem, param = cwp), times = 3) + findChromPeaks(inMem, param = cwp), times = 3) ## findPeaks.centWave is about 1 second faster. - ## detectFeatures,OnDiskMSnExp and xcmsSet should be about similar. + ## findChromPeaks,OnDiskMSnExp and xcmsSet should be about similar. microbenchmark(xcmsSet(f[1], profparam = list(profstep = 0), ppm = ppm, snthresh = snthresh, method = "centWave"), - detectFeatures(onDisk, param = cwp), - detectFeatures(inMem, param = cwp), + findChromPeaks(onDisk, param = cwp), + findChromPeaks(inMem, param = cwp), times = 3) } @@ -179,7 +179,7 @@ dontrun_test_benchmark_centWaves <- function() { ############################################################ ## This is only relevant during development of the do_ function ## to evaluate that results are identical. -dontrun_test_do_detectFeatures_centWave_impl <- function() { +dontrun_test_do_findChromPeaks_centWave_impl <- function() { for (i in 1:length(fs)) { ppm = 25 diff --git a/inst/unitTests/runit.do_detectFeatures_centWave_isotopes.R b/inst/unitTests/runit.do_findChromPeaks_centWave_isotopes.R similarity index 83% rename from inst/unitTests/runit.do_detectFeatures_centWave_isotopes.R rename to inst/unitTests/runit.do_findChromPeaks_centWave_isotopes.R index 5298128ce..56b5a86c3 100644 --- a/inst/unitTests/runit.do_detectFeatures_centWave_isotopes.R +++ b/inst/unitTests/runit.do_findChromPeaks_centWave_isotopes.R @@ -10,20 +10,20 @@ mzVals <- xr@env$mz intVals <- xr@env$intensity ## f <- msdata::proteomics(full.names = TRUE, pattern = "TMT_Erwinia") -test_do_detectFeatures_centWaveWithPredIsoROIs <- function() { +test_do_findChromPeaks_centWaveWithPredIsoROIs <- function() { ## initial centWave: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) - feats_1 <- do_detectFeatures_centWave(mz = mzVals, int = intVals, + feats_1 <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, noise = 1500, verboseColumns = TRUE) - feats_2 <- do_detectFeatures_addPredIsoROIs(mz = mzVals, + feats_2 <- do_findChromPeaks_addPredIsoROIs(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, noise = 1500, - features. = feats_1) - all_f <- do_detectFeatures_centWaveWithPredIsoROIs(mz = mzVals, + peaks. = feats_1) + all_f <- do_findChromPeaks_centWaveWithPredIsoROIs(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, @@ -34,9 +34,9 @@ test_do_detectFeatures_centWaveWithPredIsoROIs <- function() { ## checkEquals(all_f, old_all@.Data) } -## Evaluate the featureDetection method using the centWaveWithPreIsoROIs method +## Evaluate the peak detection method using the centWaveWithPreIsoROIs method ## on OnDiskMSnExp and on MSnExp objects. -test_detectFeatures_centWaveWithPredIsoROIs <- function() { +test_findChromPeaks_centWaveWithPredIsoROIs <- function() { ## Control library(MSnbase) ##ppm <- 40 @@ -55,33 +55,33 @@ test_detectFeatures_centWaveWithPredIsoROIs <- function() { onDisk <- readMSData2(fs[1], msLevel. = 1) cwp <- CentWavePredIsoParam(snthresh = snth, noise = ns, snthreshIsoROIs = snthIso) - res <- detectFeatures(onDisk, param = cwp, return.type = "list") + res <- findChromPeaks(onDisk, param = cwp, return.type = "list") checkEquals(res[[1]], peaks(xs)@.Data) ## ## MSnExp ## inMem <- readMSData(fs[1], msLevel. = 1) - ## res_2 <- detectFeatures(inMem, param = cwp, return.type = "list") + ## res_2 <- findChromPeaks(inMem, param = cwp, return.type = "list") ## checkEquals(res_2[[1]], peaks(xs)@.Data) ## returning an xcmsSet - res <- detectFeatures(onDisk, param = cwp, return.type = "xcmsSet") + res <- findChromPeaks(onDisk, param = cwp, return.type = "xcmsSet") checkEquals(peaks(res), peaks(xs)) - ## res <- detectFeatures(inMem, param = cwp, return.type = "xcmsSet") + ## res <- findChromPeaks(inMem, param = cwp, return.type = "xcmsSet") ## checkEquals(peaks(res), peaks(xs)) ## Return an XCMSnExp - res <- detectFeatures(onDisk, param = cwp) - checkTrue(hasDetectedFeatures(res)) + res <- findChromPeaks(onDisk, param = cwp) + checkTrue(hasChromPeaks(res)) checkTrue(!hasAdjustedRtime(res)) - checkTrue(!hasAlignedFeatures(res)) - checkEquals(peaks(xs)@.Data, features(res)) + checkTrue(!hasFeatures(res)) + checkEquals(peaks(xs)@.Data, chromPeaks(res)) ## Check on the full data. ## xs <- xcmsSet(fs, profparam = list(profstep = 0), snthresh = snth, ## method = "centWaveWithPredictedIsotopeROIs", noise = ns, ## snthreshIsoROIs = snthIso) ## onDisk <- readMSData2(fs, msLevel. = 1) - ## res <- detectFeatures(onDisk, param = cwp) + ## res <- findChromPeaks(onDisk, param = cwp) ## checkEquals(features(res), peaks(xs)@.Data) } @@ -90,15 +90,15 @@ test_detectFeatures_centWaveWithPredIsoROIs <- function() { dontrun_test_impl_centWave_add <- function() { ## Using the do functions: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) - do_1 <- do_detectFeatures_centWave(mz = mzVals, int = intVals, + do_1 <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, verboseColumns = TRUE) - do_2 <- do_detectFeatures_addPredIsoROIs(mz = mzVals, int = intVals, + do_2 <- do_findChromPeaks_addPredIsoROIs(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, - features. = do_1) - do_3 <- do_detectFeatures_centWaveWithPredIsoROIs(mz = mzVals, int = intVals, + peaks. = do_1) + do_3 <- do_findChromPeaks_centWaveWithPredIsoROIs(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect) checkEquals(do_2, do_3) @@ -116,7 +116,7 @@ dontrun_test_impl_centWave_add <- function() { checkEquals(fp_2, xs_2) ## - do_4 <- do_detectFeatures_centWaveWithPredIsoROIs(mz = mzVals, int = intVals, + do_4 <- do_findChromPeaks_centWaveWithPredIsoROIs(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, noise = 500, diff --git a/inst/unitTests/runit.do_detectFeatures_massifquant.R b/inst/unitTests/runit.do_findChromPeaks_massifquant.R similarity index 92% rename from inst/unitTests/runit.do_detectFeatures_massifquant.R rename to inst/unitTests/runit.do_findChromPeaks_massifquant.R index 13443d2b4..633c7cd83 100644 --- a/inst/unitTests/runit.do_detectFeatures_massifquant.R +++ b/inst/unitTests/runit.do_findChromPeaks_massifquant.R @@ -1,5 +1,5 @@ ############################################################ -## do_detectFeatures_massifquant tests +## do_findChromPeaks_massifquant tests fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"), system.file('cdf/KO/ko16.CDF', package = "faahKO"), system.file('cdf/KO/ko18.CDF', package = "faahKO"), @@ -15,18 +15,18 @@ mzf <- c(system.file("microtofq/MM14.mzML", package = "msdata"), ############################################################ ## Simple test comparing results from various massifquant runs and ## centWave analyses. -test_do_detectFeatures_massifquant <- function() { +test_do_findChromPeaks_massifquant <- function() { res <- findPeaks.massifquant(xr, snthresh = 100) mz <- xr@env$mz int <- xr@env$intensity valsPerSpect <- diff(c(xr@scanindex, length(mz))) scantime <- xr@scantime - res_2 <- do_detectFeatures_massifquant(mz = mz, int = int, + res_2 <- do_findChromPeaks_massifquant(mz = mz, int = int, valsPerSpect = valsPerSpect, scantime = scantime) checkEquals(res@.Data, res_2) ## With centWave: - res_3 <- do_detectFeatures_massifquant(mz = mz, int = int, + res_3 <- do_findChromPeaks_massifquant(mz = mz, int = int, valsPerSpect = valsPerSpect, scantime = scantime, withWave = TRUE, snthresh = 100, noise = 4000) @@ -42,36 +42,36 @@ test_do_detectFeatures_massifquant <- function() { int <- xsub@env$intensity valsPerSpect <- diff(c(xsub@scanindex, length(mz))) scantime <- xsub@scantime - res_2 <- do_detectFeatures_massifquant(mz = mz, int = int, + res_2 <- do_findChromPeaks_massifquant(mz = mz, int = int, valsPerSpect = valsPerSpect, scantime = scantime) checkIdentical(res_1@.Data, res_2) } -## Evaluate the featureDetection method using massifquant on MSnExp and +## Evaluate the peak detection method using massifquant on MSnExp and ## OnDiskMSnExp objects. -test_featureDetection_massifquant <- function() { +test_findChromPeaks_massifquant <- function() { library(MSnbase) mqp <- MassifquantParam(ppm = 20, criticalValue = 1.2) res <- xcmsSet(mzf[1], method = "massifquant", ppm = 20, criticalValue = 1.2) ## onDisk onDisk <- readMSData2(mzf[1]) - res_o <- detectFeatures(onDisk, param = mqp, return.type = "xcmsSet") + res_o <- findChromPeaks(onDisk, param = mqp, return.type = "xcmsSet") checkEquals(peaks(res_o), peaks(res)) checkEquals(res_o@rt$raw, res@rt$raw, checkNames = FALSE) ## Full data ## onDisk <- readMSData2(mzf) - ## res <- detectFeatures(onDisk, param = mqp) + ## res <- findChromPeaks(onDisk, param = mqp) ## xs <- xcmsSet(mzf, method = "massifquant", ppm = 20, criticalValue = 1.2) - ## checkTrue(hasDetectedFeatures(res)) + ## checkTrue(hasChromPeaks(res)) ## checkTrue(!hasAdjustedRtime(res)) - ## checkTrue(!hasAlignedFeatures(res)) - ## checkEquals(peaks(xs)@.Data, features(res)) + ## checkTrue(!hasFeatures(res)) + ## checkEquals(peaks(xs)@.Data, chromPeaks(res)) ## inMem ## inMem <- readMSData(mzf[1], msLevel. = 1) - ## res_i <- detectFeatures(inMem, param = mqp, return.type = "xcmsSet") + ## res_i <- findChromPeaks(inMem, param = mqp, return.type = "xcmsSet") ## checkEquals(peaks(res_i), peaks(res)) ## checkEquals(res_i@rt$raw, res@rt$raw, checkNames = FALSE) } @@ -80,7 +80,7 @@ test_featureDetection_massifquant <- function() { ############################################################ ## Test the implementation of the "do" function, i.e. whether ## the results are the same between versions and implementations. -dontrun_test_do_detectFeatures_massifquant_impl <- function() { +dontrun_test_do_findChromPeaks_massifquant_impl <- function() { library(xcms) library(RUnit) @@ -110,7 +110,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit <- 2 unions <- 1 withWave <- 0 - ## Now, this method calls do_detectFeatures_massifquant. + ## Now, this method calls do_findChromPeaks_massifquant. a <- findPeaks.massifquant(xr, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, criticalValue = criticalValue, @@ -125,7 +125,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { ## LLL: compare the _orig method ## 1) check if scanrange works between both. ## 2) compare the orig_ with the do - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -156,7 +156,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a@.Data, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -184,7 +184,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -211,7 +211,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -238,7 +238,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a@.Data, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -265,7 +265,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a@.Data, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, @@ -292,7 +292,7 @@ dontrun_test_do_detectFeatures_massifquant_impl <- function() { consecMissedLimit = consecMissedLimit, unions = unions, withWave = withWave) checkEquals(a, b) - d <- do_detectFeatures_massifquant(mz, int, scantime = scantime, + d <- do_findChromPeaks_massifquant(mz, int, scantime = scantime, valsPerSpect = valsPerSpect, ppm = ppm, peakwidth = peakwidth, snthresh = snthresh, diff --git a/inst/unitTests/runit.do_detectFeatures_matchedFilter.R b/inst/unitTests/runit.do_findChromPeaks_matchedFilter.R similarity index 95% rename from inst/unitTests/runit.do_detectFeatures_matchedFilter.R rename to inst/unitTests/runit.do_findChromPeaks_matchedFilter.R index 07e776c1b..aaac3ad79 100644 --- a/inst/unitTests/runit.do_detectFeatures_matchedFilter.R +++ b/inst/unitTests/runit.do_findChromPeaks_matchedFilter.R @@ -1,4 +1,4 @@ -## Testo detectFeatures matchedFilter +## Testo findChromPeaks matchedFilter ## library(xcms) ## library(RUnit) @@ -13,7 +13,7 @@ fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"), ## system.file("microtofq/MM8.mzML", package = "msdata")) -test_do_detectFeatures_matchedFilter <- function() { +test_do_findChromPeaks_matchedFilter <- function() { ## xr <- xcmsRaw(fs[1], profstep = 0) xr <- deepCopy(faahko_xr_1) ## We expect that changing a parameter has an influence on the result. @@ -21,19 +21,19 @@ test_do_detectFeatures_matchedFilter <- function() { intVals <- xr@env$intensity ## Define the values per spectrum: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) - res1 <- do_detectFeatures_matchedFilter(mz = mzVals, + res1 <- do_findChromPeaks_matchedFilter(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, binSize = 10) - res2 <- do_detectFeatures_matchedFilter(mz = mzVals, + res2 <- do_findChromPeaks_matchedFilter(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, binSize = 10, snthresh = 100) checkTrue(nrow(res1) > nrow(res2)) - res2 <- do_detectFeatures_matchedFilter(mz = mzVals, + res2 <- do_findChromPeaks_matchedFilter(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect, @@ -41,10 +41,10 @@ test_do_detectFeatures_matchedFilter <- function() { checkTrue(nrow(res1) > nrow(res2)) } -## Evaluate the featureDetection method using matchedFilter on MSnExp and +## Evaluate the peak detection method using matchedFilter on MSnExp and ## OnDiskMSnExp objects. For now we can't read CDF files, so we have to restrict ## to provided mzML files. -test_featureDetection_matchedFilter <- function() { +test_findChromPeaks_matchedFilter <- function() { library(MSnbase) mfp <- MatchedFilterParam(binSize = 20, impute = "lin") res <- xcmsSet(fs[1], method = "matchedFilter", profmethod = "binlin", @@ -52,23 +52,23 @@ test_featureDetection_matchedFilter <- function() { ## onDisk ## onDisk <- readMSData2(fs[1]) onDisk <- filterFile(faahko_od, file = 1) - res_o <- detectFeatures(onDisk, param = mfp, return.type = "xcmsSet") + res_o <- findChromPeaks(onDisk, param = mfp, return.type = "xcmsSet") checkEquals(peaks(res_o), peaks(res)) checkEquals(res_o@rt$raw, res@rt$raw, checkNames = FALSE) ## inMem ## inMem <- readMSData(mzf, msLevel. = 1) - ## res_i <- detectFeatures(inMem, param = mfp, return.type = "xcmsSet") + ## res_i <- findChromPeaks(inMem, param = mfp, return.type = "xcmsSet") ## checkEquals(peaks(res_i), peaks(res)) ## checkEquals(res_i@rt$raw, res@rt$raw, checkNames = FALSE) ## xs <- xcmsSet(fs, , method = "matchedFilter", profmethod = "binlin", ## step = binSize(mfp)) ## onDisk <- readMSData2(fs) - ## res <- detectFeatures(onDisk, param = mfp) - ## checkTrue(hasDetectedFeatures(res)) + ## res <- findChromPeaks(onDisk, param = mfp) + ## checkTrue(hasChromPeaks(res)) ## checkTrue(!hasAdjustedRtime(res)) - ## checkTrue(!hasAlignedFeatures(res)) - ## checkEquals(peaks(xs)@.Data, features(res)) + ## checkTrue(!hasFeatures(res)) + ## checkEquals(peaks(xs)@.Data, chromPeaks(res)) ## checkEquals(processParam(processHistory(res)[[1]]), mfp) } @@ -81,16 +81,16 @@ dontrun_benchmark_detecfFeatures_matchedFilter <- function() { inMem <- readMSData(mzf, msLevel. = 1) microbenchmark(xcmsSet(mzf, method = "matchedFilter", profmethod = "binlin", step = binSize(mfp)), - detectFeatures(onDisk, param = mfp, return.type = "xcmsSet"), - detectFeatures(inMem, param = mfp, return.type = "xcmsSet"), + findChromPeaks(onDisk, param = mfp, return.type = "xcmsSet"), + findChromPeaks(inMem, param = mfp, return.type = "xcmsSet"), times = 3) ## netCDF. onDisk <- readMSData2(fs) inMem <- readMSData(fs, msLevel. = 1) microbenchmark(xcmsSet(fs, method = "matchedFilter", profmethod = "binlin", step = binSize(mfp)), - detectFeatures(onDisk, param = mfp, return.type = "xcmsSet"), - detectFeatures(inMem, param = mfp, return.type = "xcmsSet"), + findChromPeaks(onDisk, param = mfp, return.type = "xcmsSet"), + findChromPeaks(inMem, param = mfp, return.type = "xcmsSet"), times = 3) } @@ -98,7 +98,7 @@ dontrun_benchmark_detecfFeatures_matchedFilter <- function() { ## Compare each individual function to the original one changing ## settings. ## Comparing each of the functions to the original one: -## A: do_detectFeatures_matchedFilter (original code) +## A: do_findChromPeaks_matchedFilter (original code) ## B: .matchedFilter_binYonX_iter ## C: .matchedFilter_no_iter ## D: .matchedFilter_binYonX_no_iter @@ -106,7 +106,7 @@ dontrun_benchmark_detecfFeatures_matchedFilter <- function() { ## https://github.com/sneumann/xcms/issues/47 ## A description of the results is provided in section "Implementation and ## comparison for matchedFilter" section of "new_functionality.org". -dontrun_test_do_detectFeatures_matchedFilter_impl <- function() { +dontrun_test_do_findChromPeaks_matchedFilter_impl <- function() { library(xcms) library(RUnit) @@ -120,7 +120,7 @@ dontrun_test_do_detectFeatures_matchedFilter_impl <- function() { cat("Comparison of results from different implementations:\n") cat("- orig: the original findPeaks.matchedFilter method.\n") - cat("- A: do_detectFeatures_matchedFilter (containing original code).\n") + cat("- A: do_findChromPeaks_matchedFilter (containing original code).\n") cat(paste0("- B: .matchedFilter_binYonX_iter: new function using binYonX", " for binning and imputeLinInterpol for interpolation. Uses", " iterative buffering like the original code.")) @@ -360,7 +360,7 @@ dontrun_test_do_detectFeatures_matchedFilter_impl <- function() { xr@profparam <- profparam ## The reference is the old code. ## Have to use the _orig method here, since the "official" one uses - ## already do_detectFeatures... + ## already do_findChromPeaks... orig <- xcms:::findPeaks.matchedFilter_orig(xr, fwhm = fwhm, sigma = sigma, diff --git a/inst/unitTests/runit.do_groupFeatures.R b/inst/unitTests/runit.do_groupChromPeaks.R similarity index 58% rename from inst/unitTests/runit.do_groupFeatures.R rename to inst/unitTests/runit.do_groupChromPeaks.R index b4d0146fa..df734c9d8 100644 --- a/inst/unitTests/runit.do_groupFeatures.R +++ b/inst/unitTests/runit.do_groupChromPeaks.R @@ -1,4 +1,4 @@ -## Unit tests for all do_groupFeatures_* functions and methods/functions related +## Unit tests for all do_groupChromPeaks_* functions and methods/functions related ## to feature grouping. ## General functions/methods @@ -6,8 +6,8 @@ test_groupval_XCMSnExp <- function() { od_x <- faahko_xod xs <- faahko_xs - p <- FeatureDensityParam(sampleGroups = xs$class) - od_x <- groupFeatures(od_x, param = p) + p <- PeakDensityParam(sampleGroups = xs$class) + od_x <- groupChromPeaks(od_x, param = p) xs <- group(xs, method = "density") @@ -24,70 +24,70 @@ test_groupval_XCMSnExp <- function() { ## density ## -test_groupFeatures_FeatureDensityParam <- function() { +test_groupChromPeaks_PeakDensityParam <- function() { od_x <- faahko_xod xs <- faahko_xs - fdp <- FeatureDensityParam(sampleGroups = xs$class) - od_x <- groupFeatures(od_x, param = fdp) + fdp <- PeakDensityParam(sampleGroups = xs$class) + od_x <- groupChromPeaks(od_x, param = fdp) xs <- group(xs, method = "density") - checkEquals(xs@groupidx, featureGroups(od_x)$featureidx) - fg <- featureGroups(od_x) + checkEquals(xs@groupidx, featureDefinitions(od_x)$peakidx) + fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(xs@groups, fg) checkTrue(length(processHistory(od_x)) == 2) - ph <- processHistory(od_x, type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + ph <- processHistory(od_x, type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), fdp) - fdp2 <- FeatureDensityParam(sampleGroups = xs$class, binSize = 2, + fdp2 <- PeakDensityParam(sampleGroups = xs$class, binSize = 2, minFraction = 0.8) - od_x <- groupFeatures(od_x, param = fdp2) + od_x <- groupChromPeaks(od_x, param = fdp2) xs <- group(xs, method = "density", minfrac = 0.8, mzwid = 2) - checkEquals(xs@groupidx, featureGroups(od_x)$featureidx) - fg <- featureGroups(od_x) + checkEquals(xs@groupidx, featureDefinitions(od_x)$peakidx) + fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(xs@groups, fg) checkTrue(length(processHistory(od_x)) == 2) - ph <- processHistory(od_x, type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + ph <- processHistory(od_x, type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), fdp2) } -test_do_groupFeatures_density <- function() { +test_do_groupChromPeaks_density <- function() { fts <- peaks(faahko) - res <- do_groupFeatures_density(fts, sampleGroups = sampclass(faahko)) - res_2 <- do_groupFeatures_density(fts, sampleGroups = sampclass(faahko), + res <- do_groupChromPeaks_density(fts, sampleGroups = sampclass(faahko)) + res_2 <- do_groupChromPeaks_density(fts, sampleGroups = sampclass(faahko), minFraction = 0.9) - checkTrue(nrow(res$featureGroups) > nrow(res_2$featureGroups)) + checkTrue(nrow(res$featureDefinitions) > nrow(res_2$featureDefinitions)) } -dontrun_do_groupFeatures_density_parallel <- function() { +dontrun_do_groupChromPeaks_density_parallel <- function() { library(xcms) library(faahKO) library(RUnit) data(faahko) fts <- peaks(faahko) - res <- xcms:::do_groupFeatures_density_par(fts, sampclass(faahko)) - res_2 <- do_groupFeatures_density(fts, sampclass(faahko)) - checkEquals(res$featureGroups, res_2$featureGroups) - checkEquals(res$featureIndex, res_2$featureIndex) + res <- xcms:::do_groupChromPeaks_density_par(fts, sampclass(faahko)) + res_2 <- do_groupChromPeaks_density(fts, sampclass(faahko)) + checkEquals(res$featureDefinitions, res_2$featureDefinitions) + checkEquals(res$peakIndex, res_2$peakIndex) - res <- xcms:::do_groupFeatures_density_par(fts, sampclass(faahko), bw = 10) - res_2 <- do_groupFeatures_density(fts, sampclass(faahko), bw = 10) - checkEquals(res$featureGroups, res_2$featureGroups) - checkEquals(res$featureIndex, res_2$featureIndex) + res <- xcms:::do_groupChromPeaks_density_par(fts, sampclass(faahko), bw = 10) + res_2 <- do_groupChromPeaks_density(fts, sampclass(faahko), bw = 10) + checkEquals(res$featureDefinitions, res_2$featureDefinitions) + checkEquals(res$peakIndex, res_2$peakIndex) - res <- xcms:::do_groupFeatures_density_par(fts, sampclass(faahko), + res <- xcms:::do_groupChromPeaks_density_par(fts, sampclass(faahko), minFraction = 0.9) - res_2 <- do_groupFeatures_density(fts, sampclass(faahko), minFraction = 0.9) - checkEquals(res$featureGroups, res_2$featureGroups) - checkEquals(res$featureIndex, res_2$featureIndex) + res_2 <- do_groupChromPeaks_density(fts, sampclass(faahko), minFraction = 0.9) + checkEquals(res$featureDefinitions, res_2$featureDefinitions) + checkEquals(res$peakIndex, res_2$peakIndex) } -## This is to ensure that the do_groupFeatures_density yields identical results +## This is to ensure that the do_groupChromPeaks_density yields identical results ## than the group.density method. Once we're sure of that we rename this to ## "dontrun" and replace the code within the group.density method. -dontrun_do_groupFeatures_density_compare <- function() { +dontrun_do_groupChromPeaks_density_compare <- function() { xs <- faahko fts <- peaks(xs) @@ -98,7 +98,7 @@ dontrun_do_groupFeatures_density_compare <- function() { minSmp <- 1 mzW <- 0.25 maxFts <- 50 - ftGrps <- xcms:::do_groupFeatures_density(features = fts, + ftGrps <- xcms:::do_groupChromPeaks_density(peaks = fts, sampleGroups = smpGrp, bw = theBw, minFraction = minFr, @@ -108,8 +108,8 @@ dontrun_do_groupFeatures_density_compare <- function() { xs$class <- smpGrp res_x <- group.density(xs, bw = theBw, minfrac = minFr, minsamp = minSmp, mzwid = mzW, max = maxFts) - checkEquals(res_x@groups, ftGrps$featureGroups) - checkEquals(res_x@groupidx, ftGrps$featureIndex) + checkEquals(res_x@groups, ftGrps$featureDefinitions) + checkEquals(res_x@groupidx, ftGrps$peakIndex) ## o All one group, different bw smpGrp <- rep(1, length(filepaths(xs))) theBw <- 10 @@ -117,7 +117,7 @@ dontrun_do_groupFeatures_density_compare <- function() { minSmp <- 1 mzW <- 0.25 maxFts <- 50 - ftGrps <- xcms:::do_groupFeatures_density(features = fts, + ftGrps <- xcms:::do_groupChromPeaks_density(peaks = fts, sampleGroups = smpGrp, bw = theBw, minFraction = minFr, @@ -127,8 +127,8 @@ dontrun_do_groupFeatures_density_compare <- function() { xs$class <- smpGrp res_x <- group.density(xs, bw = theBw, minfrac = minFr, minsamp = minSmp, mzwid = mzW, max = maxFts) - checkEquals(res_x@groups, ftGrps$featureGroups) - checkEquals(res_x@groupidx, ftGrps$featureIndex) + checkEquals(res_x@groups, ftGrps$featureDefinitions) + checkEquals(res_x@groupidx, ftGrps$peakIndex) ## o Three groups, minfrac smpGrp <- c(1, 1, 2, 2, 3, 3, 3, 3, 2, 2, 3, 3) theBw <- 30 @@ -136,7 +136,7 @@ dontrun_do_groupFeatures_density_compare <- function() { minSmp <- 1 mzW <- 0.4 maxFts <- 50 - ftGrps <- xcms:::do_groupFeatures_density(features = fts, + ftGrps <- xcms:::do_groupChromPeaks_density(peaks = fts, sampleGroups = smpGrp, bw = theBw, minFraction = minFr, @@ -146,8 +146,8 @@ dontrun_do_groupFeatures_density_compare <- function() { xs$class <- smpGrp res_x <- group.density(xs, bw = theBw, minfrac = minFr, minsamp = minSmp, mzwid = mzW, max = maxFts) - checkEquals(res_x@groups, ftGrps$featureGroups) - checkEquals(res_x@groupidx, ftGrps$featureIndex) + checkEquals(res_x@groups, ftGrps$featureDefinitions) + checkEquals(res_x@groupidx, ftGrps$peakIndex) ## o change also minSmp and maxFts smpGrp <- c(1, 1, 2, 2, 3, 3, 1, 1, 2, 2, 3, 3) theBw <- 30 @@ -155,7 +155,7 @@ dontrun_do_groupFeatures_density_compare <- function() { minSmp <- 2 mzW <- 0.4 maxFts <- 10 - ftGrps <- xcms:::do_groupFeatures_density(features = fts, + ftGrps <- xcms:::do_groupChromPeaks_density(peaks = fts, sampleGroups = smpGrp, bw = theBw, minFraction = minFr, @@ -165,12 +165,12 @@ dontrun_do_groupFeatures_density_compare <- function() { xs$class <- smpGrp res_x <- group.density(xs, bw = theBw, minfrac = minFr, minsamp = minSmp, mzwid = mzW, max = maxFts) - checkEquals(res_x@groups, ftGrps$featureGroups) - checkEquals(res_x@groupidx, ftGrps$featureIndex) + checkEquals(res_x@groups, ftGrps$featureDefinitions) + checkEquals(res_x@groupidx, ftGrps$peakIndex) } -dontrun_groupFeatures_density_implementation <- function() { +dontrun_groupChromPeaks_density_implementation <- function() { library(faahKO) data("faahko") ## 1) check whether the bins are really overlapping. @@ -239,25 +239,25 @@ fticr_xs <- xcmsSet(method="MSW", files=fticrf[1:2], scales=c(1,7), fticr_od <- readMSData2(fticrf[1:2], msLevel. = 1) p <- MSWParam(scales = c(1, 7), peakThr = 80000, ampTh = 0.005, SNR.method = "data.mean", winSize.noise = 500) -fticr_xod <- detectFeatures(fticr_od, param = p) +fticr_xod <- findChromPeaks(fticr_od, param = p) -test_do_groupFeatures_mzClust <- function() { +test_do_groupPeaks_mzClust <- function() { fts <- peaks(fticr_xs) - res <- do_groupFeatures_mzClust(features = fts, + res <- do_groupPeaks_mzClust(peaks = fts, sampleGroups = sampclass(fticr_xs)) - res_2 <- do_groupFeatures_mzClust(features = fts, + res_2 <- do_groupPeaks_mzClust(peaks = fts, sampleGroups = sampclass(fticr_xs), minFraction = 0, absMz = 2) - checkTrue(nrow(res$featureGroups) > nrow(res_2$featureGroups)) + checkTrue(nrow(res$featureDefinitions) > nrow(res_2$featureDefinitions)) res_x <- group(fticr_xs, method = "mzClust") - checkEquals(res_x@groups, res$featureGroups) - checkEquals(res_x@groupidx, res$featureIndex) + checkEquals(res_x@groups, res$featureDefinitions) + checkEquals(res_x@groupidx, res$peakIndex) } ## This is to compare the function to the group.mzClust method. Once all is fine ## rename it to "dontrun" -dontrun_test_groupFeatures_mzClust_compare <- function() { +dontrun_test_groupPeaks_mzClust_compare <- function() { library(RUnit) library(xcms) library(msdata) @@ -274,64 +274,64 @@ dontrun_test_groupFeatures_mzClust_compare <- function() { od <- readMSData2(mzdatafiles, msLevel. = 1) p <- MSWParam(scales = c(1, 7), ampTh = 0.005, peakThr = 80000, SNR.method = 'data.mean', winSize.noise = 500) - xod <- detectFeatures(od, param = p) - res <- do_groupFeatures_mzClust(features(xod), sampleGroups = sampclass(xs)) + xod <- findChromPeaks(od, param = p) + res <- do_groupPeaks_mzClust(chromPeaks(xod), sampleGroups = sampclass(xs)) - checkEquals(peaks(xs), features(xod)) - checkEquals(res$featureGroups, xsg@groups) - checkEquals(res$featureIndex, xsg@groupidx) + checkEquals(peaks(xs), chromPeaks(xod)) + checkEquals(res$featureDefinitions, xsg@groups) + checkEquals(res$peakIndex, xsg@groupidx) ## Check with different class ordering! sc_orig <- sampclass(xs) sc <- c(2, 2, 1, 1, 4, 4, 4, 3, 3, 3) sampclass(xs) <- factor(sc) xsg <- group(xs, method="mzClust", minfrac = 0.2) - res <- do_groupFeatures_mzClust(features(xod), sampleGroups = sc, + res <- do_groupPeaks_mzClust(chromPeaks(xod), sampleGroups = sc, minFraction = 0.2) - checkEquals(res$featureGroups, xsg@groups) - checkEquals(res$featureIndex, xsg@groupidx) + checkEquals(res$featureDefinitions, xsg@groups) + checkEquals(res$peakIndex, xsg@groupidx) sc <- c("z", "z", "b", "a", "a", "a", "z", "b", "e", "e") sampclass(xs) <- factor(sc) xsg <- group(xs, method="mzClust", minfrac = 0.2, mzppm = 40) - res <- do_groupFeatures_mzClust(features(xod), sampleGroups = sc, + res <- do_groupPeaks_mzClust(chromPeaks(xod), sampleGroups = sc, minFraction = 0.1, ppm = 40) - checkEquals(res$featureGroups, xsg@groups) - checkEquals(res$featureIndex, xsg@groupidx) + checkEquals(res$featureDefinitions, xsg@groups) + checkEquals(res$peakIndex, xsg@groupidx) xsg <- group(xs, method="mzClust", minfrac = 0.2, mzppm = 40, mzabs = 0.1) - res <- do_groupFeatures_mzClust(features(xod), sampleGroups = sc, + res <- do_groupPeaks_mzClust(chromPeaks(xod), sampleGroups = sc, minFraction = 0.1, ppm = 40, absMz = 0.1) - checkEquals(res$featureGroups, xsg@groups) - checkEquals(res$featureIndex, xsg@groupidx) + checkEquals(res$featureDefinitions, xsg@groups) + checkEquals(res$peakIndex, xsg@groupidx) } -test_groupFeatures_MzClustParam <- function() { +test_groupPeaks_MzClustParam <- function() { p <- MzClustParam(sampleGroups = sampclass(fticr_xs)) - fticr_xod2 <- groupFeatures(fticr_xod, param = p) + fticr_xod2 <- groupChromPeaks(fticr_xod, param = p) fticr_xs2 <- group(fticr_xs, method = "mzClust") - checkEquals(fticr_xs2@groupidx, featureGroups(fticr_xod2)$featureidx) - fg <- featureGroups(fticr_xod2) + checkEquals(fticr_xs2@groupidx, featureDefinitions(fticr_xod2)$peakidx) + fg <- featureDefinitions(fticr_xod2) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(fticr_xs2@groups, fg) checkTrue(length(processHistory(fticr_xod2)) == 2) ph <- processHistory(fticr_xod2, - type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), p) p2 <- MzClustParam(sampleGroups = fticr_xs$class, absMz = 1, minFraction = 0.8) - fticr_xod2 <- groupFeatures(fticr_xod, param = p2) + fticr_xod2 <- groupChromPeaks(fticr_xod, param = p2) fticr_xs2 <- group(fticr_xs, method = "mzClust", minfrac = 0.8, mzabs = 1) - checkEquals(fticr_xs2@groupidx, featureGroups(fticr_xod2)$featureidx) - fg <- featureGroups(fticr_xod2) + checkEquals(fticr_xs2@groupidx, featureDefinitions(fticr_xod2)$peakidx) + fg <- featureDefinitions(fticr_xod2) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(fticr_xs2@groups, fg) checkTrue(length(processHistory(fticr_xod2)) == 2) ph <- processHistory(fticr_xod2, - type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), p2) } @@ -339,7 +339,7 @@ test_groupFeatures_MzClustParam <- function() { ## nearest ## -test_do_groupFeatures_nearest <- function() { +test_do_groupChromPeaks_nearest <- function() { xs <- faahko features <- peaks(xs) sampleGroups <- sampclass(xs) @@ -348,37 +348,37 @@ test_do_groupFeatures_nearest <- function() { rtCheck <- 15 kNN <- 10 - res <- do_groupFeatures_nearest(features, sampleGroups) - res_2 <- do_groupFeatures_nearest(features, sampleGroups, absRt = 3) - checkTrue(nrow(res$featureGroups) < nrow(res_2$featureGroups)) + res <- do_groupChromPeaks_nearest(features, sampleGroups) + res_2 <- do_groupChromPeaks_nearest(features, sampleGroups, absRt = 3) + checkTrue(nrow(res$featureDefinitions) < nrow(res_2$featureDefinitions)) res_x <- group(xs, method = "nearest") - checkEquals(res_x@groups, res$featureGroups) + checkEquals(res_x@groups, res$featureDefinitions) } -test_groupFeatures_NearestFeaturesParam <- function() { +test_groupChromPeaks_NearestPeaksParam <- function() { od_x <- faahko_xod xs <- faahko_xs - p <- NearestFeaturesParam(sampleGroups = xs$class) - od_x <- groupFeatures(od_x, param = p) + p <- NearestPeaksParam(sampleGroups = xs$class) + od_x <- groupChromPeaks(od_x, param = p) xs <- group(xs, method = "nearest") - checkEquals(xs@groupidx, featureGroups(od_x)$featureidx) - fg <- featureGroups(od_x) + checkEquals(xs@groupidx, featureDefinitions(od_x)$peakidx) + fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(xs@groups, fg) checkTrue(length(processHistory(od_x)) == 2) - ph <- processHistory(od_x, type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + ph <- processHistory(od_x, type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), p) - fdp2 <- NearestFeaturesParam(sampleGroups = xs$class, kNN = 3) - od_x <- groupFeatures(od_x, param = fdp2) + fdp2 <- NearestPeaksParam(sampleGroups = xs$class, kNN = 3) + od_x <- groupChromPeaks(od_x, param = fdp2) xs <- group(xs, method = "nearest", kNN = 3) - checkEquals(xs@groupidx, featureGroups(od_x)$featureidx) - fg <- featureGroups(od_x) + checkEquals(xs@groupidx, featureDefinitions(od_x)$peakidx) + fg <- featureDefinitions(od_x) fg <- S4Vectors::as.matrix(fg[, -ncol(fg)]) checkEquals(xs@groups, fg) checkTrue(length(processHistory(od_x)) == 2) - ph <- processHistory(od_x, type = xcms:::.PROCSTEP.FEATURE.ALIGNMENT)[[1]] + ph <- processHistory(od_x, type = xcms:::.PROCSTEP.PEAK.GROUPING)[[1]] checkEquals(processParam(ph), fdp2) } @@ -402,76 +402,76 @@ dontrun_test_nearest_impl <- function() { res <- group(xs, method = "nearest") ## Oh, nasty warnings! These were ## already there in version 1.51.0! ## 1.48.0: Yup. - res_2 <- do_groupFeatures_nearest(features, sampleGroups) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sampleGroups) + res_2 <- do_groupChromPeaks_nearest(features, sampleGroups) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sampleGroups) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) ## change sample grouping. sc <- c("b", "b", "a", "a", "z", "z", "a", "b", "e", "e", "e", "e") sampclass(xs) <- sc ## levels are NOT ordered. res <- group(xs, method = "nearest") - res_2 <- do_groupFeatures_nearest(features, sc) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sc) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + res_2 <- do_groupChromPeaks_nearest(features, sc) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sc) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) ## Use sample assignment with ordered levels. sampclass(xs) <- factor(sc) ## this re-orders levels! res_3 <- group(xs, method = "nearest") - res_4 <- do_groupFeatures_nearest(features, factor(sc)) + res_4 <- do_groupChromPeaks_nearest(features, factor(sc)) checkEquals(res_3@groups, res@groups) ## Now, the do functions does NOT re-order levels! - checkEquals(res@groups[, 1:7], res_4$featureGroups[, 1:7]) + checkEquals(res@groups[, 1:7], res_4$featureDefinitions[, 1:7]) checkEquals(res@groups[, levels(factor(sc))], - res_4$featureGroups[, levels(factor(sc))]) - checkEquals(res@groupidx, res_4$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, factor(sc)) - checkEquals(res_n$featureIndex, res_4$featureIndex) - checkEquals(res_n$featureGroups, res_4$featureGroups) + res_4$featureDefinitions[, levels(factor(sc))]) + checkEquals(res@groupidx, res_4$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, factor(sc)) + checkEquals(res_n$peakIndex, res_4$peakIndex) + checkEquals(res_n$featureDefinitions, res_4$featureDefinitions) ## Now change settings. sampclass(xs) <- sc res <- group(xs, method = "nearest", mzVsRTbalance = 5) - res_2 <- do_groupFeatures_nearest(features, sc, mzVsRtBalance = 5) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sc, mzVsRtBalance = 5) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + res_2 <- do_groupChromPeaks_nearest(features, sc, mzVsRtBalance = 5) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sc, mzVsRtBalance = 5) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) res <- group(xs, method = "nearest", kNN = 3) - res_2 <- do_groupFeatures_nearest(features, sc, kNN = 3) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sc, kNN) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + res_2 <- do_groupChromPeaks_nearest(features, sc, kNN = 3) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sc, kNN) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) res <- group(xs, method = "nearest", mzCheck = 0.5) - res_2 <- do_groupFeatures_nearest(features, sc, absMz = 0.5) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sc, absMz = 0.5) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + res_2 <- do_groupChromPeaks_nearest(features, sc, absMz = 0.5) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sc, absMz = 0.5) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) res <- group(xs, method = "nearest", rtCheck = 3) - res_2 <- do_groupFeatures_nearest(features, sc, absRt = 3) - checkEquals(res@groups, res_2$featureGroups) - checkEquals(res@groupidx, res_2$featureIndex) - res_n <- xcms:::do_groupFeatures_nearest_mod(features, sc, absRt = 3) - checkEquals(res_n$featureIndex, res_2$featureIndex) - checkEquals(res_n$featureGroups, res_2$featureGroups) + res_2 <- do_groupChromPeaks_nearest(features, sc, absRt = 3) + checkEquals(res@groups, res_2$featureDefinitions) + checkEquals(res@groupidx, res_2$peakIndex) + res_n <- xcms:::do_groupChromPeaks_nearest_mod(features, sc, absRt = 3) + checkEquals(res_n$peakIndex, res_2$peakIndex) + checkEquals(res_n$featureDefinitions, res_2$featureDefinitions) ## library(profvis) ## profvis({ - ## res_2 <- xcms:::do_groupFeatures_nearest(features, sampleGroups) + ## res_2 <- xcms:::do_groupChromPeaks_nearest(features, sampleGroups) ## }) } diff --git a/inst/unitTests/runit.new_scanrange_subsetting.R b/inst/unitTests/runit.new_scanrange_subsetting.R index bf5c5c2ef..f1184d3d2 100644 --- a/inst/unitTests/runit.new_scanrange_subsetting.R +++ b/inst/unitTests/runit.new_scanrange_subsetting.R @@ -22,7 +22,7 @@ test_scanrange_centWave <- function() { ## Compare with do_ xsub <- xraw[90:345] - res_3 <- do_detectFeatures_centWave(mz = xsub@env$mz, + res_3 <- do_findChromPeaks_centWave(mz = xsub@env$mz, int = xsub@env$intensity, scantime = xsub@scantime, noise = 5000, diff --git a/inst/unitTests/runit.processHistory.R b/inst/unitTests/runit.processHistory.R index c5c228d12..c3f109c8b 100644 --- a/inst/unitTests/runit.processHistory.R +++ b/inst/unitTests/runit.processHistory.R @@ -86,15 +86,15 @@ test_XProcessHistory_class <- function() { checkTrue(inherits(ph, "ProcessHistory")) ph <- xcms:::XProcessHistory(info = "some info", - type = xcms:::.PROCSTEP.FEATURE.DETECTION) + type = xcms:::.PROCSTEP.PEAK.DETECTION) checkEquals(ph@info, "some info") - checkEquals(ph@type, xcms:::.PROCSTEP.FEATURE.DETECTION) + checkEquals(ph@type, xcms:::.PROCSTEP.PEAK.DETECTION) ph@type <- "other" checkException(validObject(ph)) ph <- xcms:::XProcessHistory(info = "some info", - type = xcms:::.PROCSTEP.FEATURE.DETECTION, + type = xcms:::.PROCSTEP.PEAK.DETECTION, param = CentWaveParam()) checkTrue(is(ph@param, "CentWaveParam")) diff --git a/inst/unitTests/runit.useOriginalCode.R b/inst/unitTests/runit.useOriginalCode.R index 33adb0a02..ba166953e 100644 --- a/inst/unitTests/runit.useOriginalCode.R +++ b/inst/unitTests/runit.useOriginalCode.R @@ -29,12 +29,12 @@ dontrun_test_matchedFilter_orig_code <- function() { step <- 0.2 orig <- useOriginalCode() - res_new <- xcms:::do_detectFeatures_matchedFilter(mz, int, + res_new <- xcms:::do_findChromPeaks_matchedFilter(mz, int, scantime, valsPerSpect, binSize = step) useOriginalCode(TRUE) - res_old <- xcms:::do_detectFeatures_matchedFilter(mz, int, + res_old <- xcms:::do_findChromPeaks_matchedFilter(mz, int, scantime, valsPerSpect, binSize = step) diff --git a/man/Chromatogram-class.Rd b/man/Chromatogram-class.Rd new file mode 100644 index 000000000..789a753d6 --- /dev/null +++ b/man/Chromatogram-class.Rd @@ -0,0 +1,117 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R, R/functions-Chromatogram.R, R/methods-Chromatogram.R +\docType{class} +\name{Chromatogram-class} +\alias{Chromatogram} +\alias{Chromatogram-class} +\alias{aggregationFun} +\alias{aggregationFun,Chromatogram-method} +\alias{as.data.frame,Chromatogram-method} +\alias{fromFile,Chromatogram-method} +\alias{intensity,Chromatogram-method} +\alias{length,Chromatogram-method} +\alias{mzrange,Chromatogram-method} +\alias{rtime,Chromatogram-method} +\alias{show,Chromatogram-method} +\title{Representation of chromatographic MS data} +\usage{ +Chromatogram(rtime = numeric(), intensity = numeric(), mz = c(0, 0), + filterMz = c(0, 0), fromFile = integer(), aggregationFun = character()) + +\S4method{show}{Chromatogram}(object) + +\S4method{rtime}{Chromatogram}(object) + +\S4method{intensity}{Chromatogram}(object) + +\S4method{mzrange}{Chromatogram}(object, filter = FALSE) + +\S4method{aggregationFun}{Chromatogram}(object) + +\S4method{fromFile}{Chromatogram}(object) + +\S4method{length}{Chromatogram}(x) + +\S4method{as.data.frame}{Chromatogram}(x) +} +\arguments{ +\item{rtime}{\code{numeric} with the retention times (length has to be equal +to the length of \code{intensity}).} + +\item{intensity}{\code{numeric} with the intensity values (length has to be +equal to the length of \code{rtime}).} + +\item{mz}{\code{numeric(2)} representing the mz value range (min, max) +on which the chromatogram was created. This is supposed to contain the +\emph{real} range of mz values in contrast to the \code{filterMz} below. +If not applicable use \code{mzrange = c(0, 0)}.} + +\item{filterMz}{\code{numeric(2)} representing the mz value range (min, +max) that was used to filter the original object on mz dimension. If not +applicable use \code{filterMz = c(0, 0)}.} + +\item{fromFile}{\code{integer(1)} the index of the file within the +\code{\link{OnDiskMSnExp}} or \code{\link{XCMSnExp}} from which the +chromatogram was extracted.} + +\item{aggregationFun}{\code{character} string specifying the function that +was used to aggregate intensity values for the same retention time across the +mz range. Supported are \code{"sum"} (total ion chromatogram), \code{"max"} +(base peak chromatogram), \code{"min"} and \code{"mean"}.} + +\item{object}{A \code{Chromatogram} object.} + +\item{filter}{For \code{mz}: whether the mz range used to filter the +original object should be returned (\code{filter = TRUE}), or the mz range +calculated on the real data (\code{filter = FALSE}).} + +\item{x}{For \code{as.data.frame} and \code{length}: a \code{Chromatogram} +object.} +} +\description{ +The \code{Chromatogram} class is designed to store +chromatographic MS data, i.e. pairs of retention time and intensity values. +Instances of the class can be created with the \code{Chromatogram} +constructor function but in most cases the dedicated methods for +\code{\link{OnDiskMSnExp}} and \code{\link{XCMSnExp}} objects extracting +chromatograms should be used instead. + +\code{Chromatogram}: create an instance of the +\code{Chromatogram} class. + +\code{rtime} returns the retention times for the rentention time +- intensity pairs stored in the chromatogram. + +\code{intensity} returns the intensity for the rentention time +- intensity pairs stored in the chromatogram. + +\code{mz} get or set the mz range of the +chromatogram. + +\code{aggregationFun,aggregationFun<-} get or set the +aggregation function. + +\code{fromFile} returns the value from the \code{fromFile} slot. + +\code{length} returns the length (number of retention time - +intensity pairs) of the chromatogram. + +\code{as.data.frame} returns the \code{rtime} and +\code{intensity} values from the object as \code{data.frame}. +} +\details{ +The \code{mz}, \code{filterMz} are stored as a \code{numeric(2)} +representing a range even if the chromatogram represent the chromatogram for +a single ion (represented as a single mz value). Representing the \code{mz} +as a range allows this class also to be used for a total ion chromatogram +or base peak chromatogram. +} +\section{Slots}{ + +\describe{ +\item{\code{rtime,intensity,mzrange,filterMzrange,fromFile,aggregationFun}}{See corresponding parameter above.} +}} +\author{ +Johannes Rainer +} + diff --git a/man/ProcessHistory-class.Rd b/man/ProcessHistory-class.Rd index 607d5e3d0..f07f90577 100644 --- a/man/ProcessHistory-class.Rd +++ b/man/ProcessHistory-class.Rd @@ -56,7 +56,7 @@ of the files/samples on which the processing step was applied. \description{ Objects of the type \code{ProcessHistory} allow to keep track of any data processing step in an metabolomics experiment. They are created -by the data processing methods, such as \code{\link{detectFeatures}} and +by the data processing methods, such as \code{\link{findChromPeaks}} and added to the corresponding results objects. Thus, usually, users don't need to create them. @@ -84,7 +84,9 @@ the processing step was applied. \describe{ \item{\code{type}}{character(1): string defining the type of the processing step. This string has to match predefined values defined in the internal variable -\code{.PROCSTEPS}.} +\code{.PROCSTEPS} (allowed values are \code{"Unknown"}, +\code{"Peak detection"}, \code{"Peak grouping"} and +\code{"Retention time correction"}).} \item{\code{date}}{character(1): date time stamp when the processing step was started.} diff --git a/man/XCMSnExp-class.Rd b/man/XCMSnExp-class.Rd index 04d15fd9d..877fc4644 100644 --- a/man/XCMSnExp-class.Rd +++ b/man/XCMSnExp-class.Rd @@ -12,36 +12,36 @@ \alias{adjustedRtime<-} \alias{adjustedRtime<-,MsFeatureData-method} \alias{adjustedRtime<-,XCMSnExp-method} +\alias{chromPeaks} +\alias{chromPeaks,MsFeatureData-method} +\alias{chromPeaks,XCMSnExp-method} +\alias{chromPeaks<-} +\alias{chromPeaks<-,MsFeatureData-method} +\alias{chromPeaks<-,XCMSnExp-method} \alias{dropAdjustedRtime} \alias{dropAdjustedRtime,MsFeatureData-method} \alias{dropAdjustedRtime,XCMSnExp-method} -\alias{dropFeatureGroups} -\alias{dropFeatureGroups,MsFeatureData-method} -\alias{dropFeatureGroups,XCMSnExp-method} -\alias{dropFeatures} -\alias{dropFeatures,MsFeatureData-method} -\alias{dropFeatures,XCMSnExp-method} -\alias{featureGroups} -\alias{featureGroups,MsFeatureData-method} -\alias{featureGroups,XCMSnExp-method} -\alias{featureGroups<-} -\alias{featureGroups<-,MsFeatureData-method} -\alias{featureGroups<-,XCMSnExp-method} -\alias{features} -\alias{features,MsFeatureData-method} -\alias{features,XCMSnExp-method} -\alias{features<-} -\alias{features<-,MsFeatureData-method} -\alias{features<-,XCMSnExp-method} +\alias{dropChromPeaks} +\alias{dropChromPeaks,MsFeatureData-method} +\alias{dropChromPeaks,XCMSnExp-method} +\alias{dropFeatureDefinitions} +\alias{dropFeatureDefinitions,MsFeatureData-method} +\alias{dropFeatureDefinitions,XCMSnExp-method} +\alias{featureDefinitions} +\alias{featureDefinitions,MsFeatureData-method} +\alias{featureDefinitions,XCMSnExp-method} +\alias{featureDefinitions<-} +\alias{featureDefinitions<-,MsFeatureData-method} +\alias{featureDefinitions<-,XCMSnExp-method} \alias{hasAdjustedRtime} \alias{hasAdjustedRtime,MsFeatureData-method} \alias{hasAdjustedRtime,XCMSnExp-method} -\alias{hasAlignedFeatures} -\alias{hasAlignedFeatures,MsFeatureData-method} -\alias{hasAlignedFeatures,XCMSnExp-method} -\alias{hasDetectedFeatures} -\alias{hasDetectedFeatures,MsFeatureData-method} -\alias{hasDetectedFeatures,XCMSnExp-method} +\alias{hasChromPeaks} +\alias{hasChromPeaks,MsFeatureData-method} +\alias{hasChromPeaks,XCMSnExp-method} +\alias{hasFeatures} +\alias{hasFeatures,MsFeatureData-method} +\alias{hasFeatures,XCMSnExp-method} \alias{intensity,XCMSnExp-method} \alias{mz,XCMSnExp-method} \alias{processHistory} @@ -59,9 +59,9 @@ \S4method{hasAdjustedRtime}{MsFeatureData}(object) -\S4method{hasAlignedFeatures}{MsFeatureData}(object) +\S4method{hasFeatures}{MsFeatureData}(object) -\S4method{hasDetectedFeatures}{MsFeatureData}(object) +\S4method{hasChromPeaks}{MsFeatureData}(object) \S4method{adjustedRtime}{MsFeatureData}(object) @@ -69,17 +69,17 @@ \S4method{dropAdjustedRtime}{MsFeatureData}(object) -\S4method{featureGroups}{MsFeatureData}(object) +\S4method{featureDefinitions}{MsFeatureData}(object) -\S4method{featureGroups}{MsFeatureData}(object) <- value +\S4method{featureDefinitions}{MsFeatureData}(object) <- value -\S4method{dropFeatureGroups}{MsFeatureData}(object) +\S4method{dropFeatureDefinitions}{MsFeatureData}(object) -\S4method{features}{MsFeatureData}(object) +\S4method{chromPeaks}{MsFeatureData}(object) -\S4method{features}{MsFeatureData}(object) <- value +\S4method{chromPeaks}{MsFeatureData}(object) <- value -\S4method{dropFeatures}{MsFeatureData}(object) +\S4method{dropChromPeaks}{MsFeatureData}(object) \S4method{profMat}{OnDiskMSnExp}(object, method = "bin", step = 0.1, baselevel = NULL, basespace = NULL, mzrange. = NULL, fileIndex, ...) @@ -88,21 +88,21 @@ \S4method{hasAdjustedRtime}{XCMSnExp}(object) -\S4method{hasAlignedFeatures}{XCMSnExp}(object) +\S4method{hasFeatures}{XCMSnExp}(object) -\S4method{hasDetectedFeatures}{XCMSnExp}(object) +\S4method{hasChromPeaks}{XCMSnExp}(object) \S4method{adjustedRtime}{XCMSnExp}(object, bySample = FALSE) \S4method{adjustedRtime}{XCMSnExp}(object) <- value -\S4method{featureGroups}{XCMSnExp}(object) +\S4method{featureDefinitions}{XCMSnExp}(object) -\S4method{featureGroups}{XCMSnExp}(object) <- value +\S4method{featureDefinitions}{XCMSnExp}(object) <- value -\S4method{features}{XCMSnExp}(object, bySample = FALSE) +\S4method{chromPeaks}{XCMSnExp}(object, bySample = FALSE) -\S4method{features}{XCMSnExp}(object) <- value +\S4method{chromPeaks}{XCMSnExp}(object) <- value \S4method{rtime}{XCMSnExp}(object, bySample = FALSE, adjusted = hasAdjustedRtime(object)) @@ -115,9 +115,9 @@ \S4method{processHistory}{XCMSnExp}(object, fileIndex, type) -\S4method{dropFeatures}{XCMSnExp}(object) +\S4method{dropChromPeaks}{XCMSnExp}(object) -\S4method{dropFeatureGroups}{XCMSnExp}(object, keepAdjRtime = FALSE, +\S4method{dropFeatureDefinitions}{XCMSnExp}(object, keepAdjRtime = FALSE, dropLastN = -1) \S4method{dropAdjustedRtime}{XCMSnExp}(object) @@ -126,21 +126,21 @@ baselevel = NULL, basespace = NULL, mzrange. = NULL, fileIndex, ...) } \arguments{ -\item{object}{For \code{adjustedRtime}, \code{featureGroups}, -\code{features}, \code{hasAdjustedRtime}, \code{hasAlignedFeatures} and -\code{hasDetectedFeatures} either a \code{MsFeatureData} or a \code{XCMSnExp} +\item{object}{For \code{adjustedRtime}, \code{featureDefinitions}, +\code{chromPeaks}, \code{hasAdjustedRtime}, \code{hasFeatures} and +\code{hasChromPeaks} either a \code{MsFeatureData} or a \code{XCMSnExp} object, for all other methods a \code{XCMSnExp} object.} \item{value}{For \code{adjustedRtime<-}: a \code{list} (length equal to the number of samples) with numeric vectors representing the adjusted retention times per scan. -For \code{featureGroups<-}: a \code{DataFrame} with feature -alignment information. See return value for the \code{featureGroups} method -for the expected format. +For \code{featureDefinitions<-}: a \code{DataFrame} with peak +grouping information. See return value for the \code{featureDefinitions} +method for the expected format. -For \code{features<-}: a \code{matrix} with information on -detected features. See return value for the \code{features} method for the +For \code{chromPeaks<-}: a \code{matrix} with information on +detected peaks. See return value for the \code{chromPeaks} method for the expected format.} \item{method}{The profile matrix generation method. Allowed are \code{"bin"}, @@ -181,20 +181,20 @@ retention times reported in the files) should be returned.} \item{type}{For \code{processHistory}: restrict returned \code{\link{ProcessHistory}} objects to analysis steps of a certain type. -Supported values are \code{"Unknown"}, \code{"Feature detection"}, -\code{"Feature alignment"} and \code{"Retention time correction"}.} - -\item{keepAdjRtime}{For \code{dropFeatureGroups,XCMSnExp}: logical(1) -defining whether eventually present retention time adjustment should not be -dropped. By default dropping feature groups drops retention time adjustment -results too.} - -\item{dropLastN}{For \code{dropFeatureGroups,XCMSnExp}: numeric(1) defining -the number of feature alignment related process history steps to remove. By -default \code{dropLastN = -1}, dropping the features removes all process -history steps related to feature alignment. Setting e.g. \code{dropLastN = 1} -will only remove the most recent feature alignment related process history -step.} +Supported values are \code{"Unknown"}, \code{"Peak detection"}, +\code{"Peak grouping"} and \code{"Retention time correction"}.} + +\item{keepAdjRtime}{For \code{dropFeatureDefinitions,XCMSnExp}: +\code{logical(1)} defining whether eventually present retention time +adjustment should not be dropped. By default dropping feature definitions +drops retention time adjustment results too.} + +\item{dropLastN}{For \code{dropFeatureDefinitions,XCMSnExp}: +\code{numeric(1)} defining the number of peak grouping related process +history steps to remove. By default \code{dropLastN = -1}, dropping the +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.} } \value{ For \code{profMat}: a \code{list} with a the profile matrix @@ -208,28 +208,30 @@ within the object. If \code{bySample = TRUE } a \code{list} (length equal to the number of samples) with adjusted retention times grouped by sample. Returns \code{NULL} if no adjusted retention times are present. -For \code{featureGroups}: a \code{DataFrame} with feature alignment -information, each row corresponding to one group of aligned features (across -samples) and columns \code{"mzmed"} (median mz value), \code{"mzmin"} -(minimal mz value), \code{"mzmax"} (maximum mz value), \code{"rtmed"} (median -retention time), \code{"rtmin"} (minimal retention time), \code{"rtmax"} -(maximal retention time) and \code{"featureidx"}. Column \code{"featureidx"} -contains a \code{list} with indices of features (rows) in the matrix returned -by the \code{features} method that belong to that feature group. The method -returns \code{NULL} if no aligned feature information is present. - -For \code{features}: if \code{bySample = FALSE} a \code{matrix} with +For \code{featureDefinitions}: a \code{DataFrame} with peak grouping +information, each row corresponding to one mz-rt feature (grouped peaks +within and across samples) and columns \code{"mzmed"} (median mz value), +\code{"mzmin"} (minimal mz value), \code{"mzmax"} (maximum mz value), +\code{"rtmed"} (median retention time), \code{"rtmin"} (minimal retention +time), \code{"rtmax"} (maximal retention time) and \code{"peakidx"}. +Column \code{"peakidx"} contains a \code{list} with indices of +chromatographic peaks (rows) in the matrix returned by the \code{chromPeaks} +method that belong to that feature group. The method returns \code{NULL} if +no feature definitions are present. + +For \code{chromPeaks}: if \code{bySample = FALSE} a \code{matrix} with at least the following columns: \code{"mz"} (mz value for the largest intensity), \code{"mzmin"} (minimal mz value), \code{"mzmax"} (maximal mz value), \code{"rt"} (retention time for the peak apex), \code{"rtmin"} (minimal retention time), \code{"rtmax"} (maximal retention time), -\code{"into"} (integrated, original, intensity of the feature) and -\code{"sample"} (sample index in which the feature was identified). -Depending on the employed feature detection algorithm and the +\code{"into"} (integrated, original, intensity of the peak) and +\code{"sample"} (sample index in which the peak was identified). +Depending on the employed peak detection algorithm and the \code{verboseColumns} parameter of it additional columns might be returned. -For \code{bySample = TRUE} the features are returned as a \code{list} of -matrices, each containing the features of a specific sample. For sample in -which no feastures were detected a matrix with 0 rows is returned. +For \code{bySample = TRUE} the chronatographic peaks are returned as a +\code{list} of matrices, each containing the chromatographic peak of a +specific sample. For sample in which no feastures were detected a matrix +with 0 rows is returned. For \code{rtime}: if \code{bySample = FALSE} a numeric vector with the retention times of each scan, if \code{bySample = TRUE} a \code{list} of @@ -256,25 +258,26 @@ data processing steps that have been performed. \description{ The \code{MsFeatureData} class is designed to encapsule all data related to the preprocessing of metabolomics data using the \code{xcms} -package, i.e. it contains a \code{matrix} with the features identified by the -feature detection, a \code{DataFrame} with the information on aligned -features across samples and a \code{list} with the adjusted retention times -per sample. +package, i.e. it contains a \code{matrix} with the chromatographic peaks +identified by the peak detection, a \code{DataFrame} with the definition on +grouped chromatographic peaks across samples and a \code{list} with the +adjusted retention times per sample. The \code{XCMSnExp} object is designed to contain all results -from metabolomics data preprocessing (feature detection, feature alignment -and retention time correction). The corresponding elements in the -\code{msFeatureData} slot are \code{"features"} (a \code{matrix}), -\code{"featureGroups"} (a \code{DataFrame}) and \code{"adjustedRtime"} (a -\code{list} of numeric vectors). Note that these should not be accessed -directly but rather \emph{via} their accessor methods. Along with the results, -the object contains the processing history that allow to track each -processing step along with the used settings. The object also directly -extends the \code{\link[MSnbase]{OnDiskMSnExp}} object hence allowing easy -access to the full data on which the feature detection was performed. +from metabolomics data preprocessing (chromatographic peak detection, peak +grouping (correspondence) and retention time correction). The corresponding +elements in the \code{msFeatureData} slot are \code{"chromPeaks"} +(a \code{matrix}), \code{"featureDefinitions"} (a \code{DataFrame}) and +\code{"adjustedRtime"} (a \code{list} of numeric vectors). Note that these +should not be accessed directly but rather \emph{via} their accessor methods. +Along with the results, the object contains the processing history that +allow to track each processing step along with the used settings. The object +also directly extends the \code{\link[MSnbase]{OnDiskMSnExp}} object hence +allowing easy access to the full data on which the peak detection was +performed. Objects from this class should not be created directly, they are returned as -result from the \code{\link{detectFeatures}} method. +result from the \code{\link{findChromPeaks}} method. \code{XCMSnExp} objects can be coerced into \code{\linkS4class{xcmsSet}} objects using the \code{as} method. @@ -289,33 +292,34 @@ methods. \code{hasAdjustedRtime}: whether the object provides adjusted retention times. -\code{hasAlignedFeatures}: whether the object contains feature -alignment results. +\code{hasFeatures}: whether the object contains correspondence +results (i.e. features). -\code{hasDetectedFeatures}: whether the object contains feature +\code{hasChromPeaks}: whether the object contains peak detection results. \code{adjustedRtime},\code{adjustedRtime<-}: extract/set adjusted retention times. \code{adjustedRtime<-} should not be called manually, it is called internally by the \code{\link{adjustRtime}} methods. For \code{XCMSnExp} objects, \code{adjustedRtime<-} does also apply -the retention time adjustment to the features in the object. +the retention time adjustment to the chromatographic peaks in the object. The \code{bySample} parameter allows to specify whether the adjusted retention time should be grouped by sample (file). -\code{featureGroups}, \code{featureGroups<-}: extract -or set the feature alignment results. +\code{featureDefinitions}, \code{featureDefinitions<-}: extract +or set the correspondence results, i.e. the mz-rt features (peak groups). -\code{features}, \code{features<-}: extract or set -the matrix containing the information on identified features. Parameter -\code{bySample} allows to specify whether features should be returned -ungrouped (default \code{bySample = FALSE}) or grouped by sample ( -\code{bySample = TRUE}). The \code{features<-} method for \code{XCMSnExp} -objects removes also all feature alignment and retention time correction -results. +\code{chromPeaks}, \code{chromPeaks<-}: extract or set +the matrix containing the information on identified chromatographic peaks. +Parameter \code{bySample} allows to specify whether peaks should be +returned ungrouped (default \code{bySample = FALSE}) or grouped by sample ( +\code{bySample = TRUE}). The \code{chromPeaks<-} method for \code{XCMSnExp} +objects removes also all correspondence (peak grouping) and retention time +correction (alignment) results. See description of the return value for details on the returned matrix. Users -usually don't have to use the \code{features<-} method directly as detected -features are added to the object by the \code{\link{detectFeatures}} method. +usually don't have to use the \code{chromPeaks<-} method directly as detected +chromatographic peaks are added to the object by the +\code{\link{findChromPeaks}} method. \code{rtime}: extracts the retention time for each scan. The \code{bySample} parameter allows to return the values grouped @@ -351,28 +355,31 @@ eventually along with their settings (\code{Param} parameter class). Optional arguments \code{fileIndex} and \code{type} allow to restrict to process steps of a certain type or performed on a certain file. -\code{dropFeatures}: drops any identified features -and returns the object without that information. Note that for -\code{XCMSnExp} objects the method drops all results from a feature alignment -or retention time adjustment too. For \code{XCMSnExp} objects the method -drops also any related process history steps. - -\code{dropFeatureGroups}: drops aligned feature -results (i.e. feature groups) and returns the object -without that information. Note that for \code{XCMSnExp} objects the method -will also drop retention time adjustment results, if these were performed -after the last feature alignment (i.e. which base on the results from the -feature alignment that are going to be removed). For \code{XCMSnExp} objects -also all related process history steps are removed. +\code{dropChromPeaks}: drops any identified chromatographic +peaks and returns the object without that information. Note that for +\code{XCMSnExp} objects the method drops all results from a correspondence +(peak grouping) or alignment (retention time adjustment) too. +For \code{XCMSnExp} objects the method drops also any related process +history steps. + +\code{dropFeatureDefinitions}: drops the results from a +correspondence (peak grouping) analysis, i.e. the definition of the mz-rt +features and returns the object without that information. Note that for +\code{XCMSnExp} objects the method will also drop retention time adjustment +results, if these were performed after the last peak grouping (i.e. which +base on the results from the peak grouping that are going to be removed). +For \code{XCMSnExp} objects also all related process history steps are +removed. \code{dropAdjustedRtime}: drops any retention time adjustment information and returns the object without adjusted retention time. For \code{XCMSnExp} object this also reverts the retention times -reported for the features in the feature matrix to the original, raw, ones -(after feature detection). Note that for \code{XCMSnExp} objects the method -drops also all feature alignment results if these were performed \emph{after} -the retention time adjustment. For \code{XCMSnExp} objects the method drops -also any related process history steps. +reported for the chromatographic peaks in the peak matrix to the original, +raw, ones (after chromatographic peak detection). Note that for +\code{XCMSnExp} objects the method drops also all peak grouping results +if these were performed \emph{after} the retention time adjustment. +For \code{XCMSnExp} objects the method drops also any related process history +steps. } \section{Slots}{ @@ -381,14 +388,15 @@ also any related process history steps. tracking all individual analysis steps that have been performed.} \item{\code{msFeatureData}}{\code{MsFeatureData} class extending \code{environment} -and containing the results from a feature detection (element -\code{"features"}), feature alignment (element \code{"featureGroups"}) and -retention time correction (element \code{""}) steps.} +and containing the results from a chromatographic peak detection (element +\code{"chromPeaks"}), peak grouping (element \code{"featureDefinitions"}) +and retention time correction (element \code{"adjustedRtime"}) steps.} }} \note{ -The \code{"features"} element in the \code{msFeatureData} slot is +The \code{"chromPeaks"} element in the \code{msFeatureData} slot is equivalent to the \code{@peaks} slot of the \code{xcmsSet} object, the -\code{"featureGroups"} contains information from the \code{} +\code{"featureDefinitions"} contains information from the \code{@groups} and +\code{@groupidx} slots from an \code{xcmsSet} object. } \examples{ @@ -396,24 +404,24 @@ equivalent to the \code{@peaks} slot of the \code{xcmsSet} object, the library(faahKO) od <- readMSData2(c(system.file("cdf/KO/ko15.CDF", package = "faahKO"), system.file("cdf/KO/ko16.CDF", package = "faahKO"))) -## Now we perform a feature detection on this data set using the +## Now we perform a chromatographic peak detection on this data set using the ## matched filter method. We are tuning the settings such that it performs ## faster. mfp <- MatchedFilterParam(binSize = 4) -xod <- detectFeatures(od, param = mfp) +xod <- findChromPeaks(od, param = mfp) -## The results from the feature detection are now stored in the XCMSnExp +## The results from the peak detection are now stored in the XCMSnExp ## object xod -## The detected features can be accessed with the features method. -head(features(xod)) +## The detected peaks can be accessed with the chromPeaks method. +head(chromPeaks(xod)) -## The settings of the feature detection can be accessed with the -## processHistory method +## The settings of the chromatographic peak detection can be accessed with +## the processHistory method processHistory(xod) -## Also the parameter class for the feature detection can be accessed +## Also the parameter class for the peak detection can be accessed processParam(processHistory(xod)[[1]]) ## The XCMSnExp inherits all methods from the pSet and OnDiskMSnExp classes @@ -441,16 +449,16 @@ head(split(spctr, fromFile(xod))[[1]]) ## ## XCMSnExp objects can be filtered by file, retention time, mz values or ## MS level. For some of these filter preprocessing results (mostly -## retention time correction and feature alignment results) will be dropped. +## retention time correction and peak grouping results) will be dropped. ## Below we filter the XCMSnExp object by file to extract the results for ## only the second file. xod_2 <- filterFile(xod, file = 2) xod_2 -## Now the objects contains only the idenfified features for the second file -head(features(xod_2)) +## Now the objects contains only the idenfified peaks for the second file +head(chromPeaks(xod_2)) -head(features(xod)[features(xod)[, "sample"] == 2, ]) +head(chromPeaks(xod)[chromPeaks(xod)[, "sample"] == 2, ]) ########## ## Coercing to an xcmsSet object @@ -468,12 +476,12 @@ Johannes Rainer \code{\link[MSnbase]{OnDiskMSnExp}}, \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{pSet}} for a complete list of inherited methods. -\code{\link{detectFeatures}} for available feature detection methods +\code{\link{findChromPeaks}} for available peak detection methods returning a \code{XCMSnExp} object as a result. -\code{\link{groupFeatures}} for available feature grouping methods -and \code{\link{groupval,XCMSnExp-method}} for the method to extract feature -grouping results. +\code{\link{groupChromPeaks}} for available peak grouping +methods and \code{\link{featureDefinitions}} for the method to extract +the feature definitions representing the peak grouping results. \code{\link{adjustRtime}} for retention time adjustment methods. } diff --git a/man/XCMSnExp-feature-grouping-results.Rd b/man/XCMSnExp-feature-grouping-results.Rd deleted file mode 100644 index ad76d022a..000000000 --- a/man/XCMSnExp-feature-grouping-results.Rd +++ /dev/null @@ -1,59 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods-XCMSnExp.R -\docType{methods} -\name{groupval,XCMSnExp-method} -\alias{groupval,XCMSnExp-method} -\title{Accessing feature grouping results} -\usage{ -\S4method{groupval}{XCMSnExp}(object, method = c("medret", "maxint"), - value = "index", intensity = "into") -} -\arguments{ -\item{object}{A \code{\link{XCMSnExp}} object providing the feature grouping -results.} - -\item{method}{\code{character} specifying the method to resolve -multi-feature mappings within the same sample, i.e. to define the -\emph{representative} feature for a feature groups in samples where more than -one feature was assigned to the feature group. If \code{"medret"}: select the -feature closest to the median retention time of the feature group. -If \code{"maxint"}: select the feature yielding the largest signal.} - -\item{value}{\code{character} specifying the name of the column in -\code{features(object)} that should be returned or \code{"index"} (the -default) to return the index of the feature in the \code{features(object)} -matrix corresponding to the \emph{representative} feature for the feature -group in the respective sample.} - -\item{intensity}{\code{character} specifying the name of the column in the -\code{features(objects)} matrix containing the intensity value of the -feature that should be used for the conflict resolution if -\code{method = "maxint"}.} -} -\value{ -For \code{groupval}: a \code{matrix} with feature values, columns -representing samples, rows feature groups. The order of the feature groups -matches the order found in the \code{featureGroups(object)} \code{DataFrame}. -An \code{NA} is reported for feature groups without corresponding -features in the respective sample(s). -} -\description{ -\code{groupval,XCMSnExp}: extract a \code{matrix} for feature -values with rows representing feature groups and columns samples. Parameter -\code{value} allows to define which column from the \code{\link{features}} -matrix should be returned. Multiple features from the same sample can be -assigned to a feature group. Parameter \code{method} allows to specify the -method to be used in such cases to chose from which of the features the value -should be returned. -} -\author{ -Johannes Rainer -} -\seealso{ -\code{\link{XCMSnExp}} for information on the data object. -\code{\link{featureGroups}} to extract the \code{DataFrame} with the -feature group definition. -\code{\link{hasAlignedFeatures}} to evaluate whether the -\code{\link{XCMSnExp}} provides feature groups. -} - diff --git a/man/XCMSnExp-filter-methods.Rd b/man/XCMSnExp-filter-methods.Rd index 48f6b6d0e..499cd56ad 100644 --- a/man/XCMSnExp-filter-methods.Rd +++ b/man/XCMSnExp-filter-methods.Rd @@ -14,7 +14,7 @@ The methods listed on this page allow to filter and subset \code{\link{XCMSnExp}} to enable subsetting also on the preprocessing results.} \usage{ -\S4method{filterFile}{XCMSnExp}(object, file) +\S4method{filterFile}{XCMSnExp}(object, file, keepAdjustedRtime = FALSE) \S4method{filterMz}{XCMSnExp}(object, mz, msLevel., ...) @@ -29,6 +29,11 @@ within the object to subset the object by file or \code{character} specifying the file names to sub set. The indices are expected to be increasingly ordered, if not they are ordered internally.} +\item{keepAdjustedRtime}{For \code{filterFile}: \code{logical(1)} defining +whether the adjusted retention times should be kept, even if features are +being removed (and the retention time correction being potentially performed +on these features).} + \item{mz}{For \code{filterMz}: \code{numeric(2)} defining the lower and upper mz value for the filtering.} @@ -50,25 +55,29 @@ All methods return an \code{\link{XCMSnExp}} object. } \description{ \code{filterFile}: allows to reduce the -\code{\link{XCMSnExp}} to data from only certain files. Identified features -for these files are retained while eventually all present feature -alignment/grouping information and adjusted retention times are dropped.. +\code{\link{XCMSnExp}} to data from only certain files. Identified +chromatographic peaks for these files are retained while all eventually +present features (peak grouping information) are dropped. By default also +adjusted retention times are removed. This can be overwritten by setting +\code{keepAdjustedRtime = TRUE}, but users should use this option with +caution. \code{filterMz}: filters the data set based on the -provided mz value range. All features and feature groups (aligned features) -falling completely within the provided mz value range are retained (if their -minimal mz value is \code{>= mz[1]} and the maximal mz value \code{<= mz[2]}. -Adjusted retention times, if present, are not altered by the filtering. +provided mz value range. All chromatographic peaks and features (grouped +peaks) falling completely within the provided mz value range are retained +(if their minimal mz value is \code{>= mz[1]} and the maximal mz value +\code{<= mz[2]}. Adjusted retention times, if present, are not altered by +the filtering. \code{filterRt}: filters the data set based on the -provided retention time range. All features and feature groups within -the specified retention time window are retained (i.e. if the retention time -corresponding to the feature's peak is within the specified rt range). -If retention time correction has been performed, the method will by default -filter the object by adjusted retention times. The argument \code{adjusted} -allows to specify manually whether filtering should be performed by raw or -adjusted retention times. Filtering by retention time does not drop any -preprocessing results. +provided retention time range. All chromatographic peaks and features +(grouped peaks) the specified retention time window are retained (i.e. if +the retention time corresponding to the peak's apex is within the specified +rt range). If retention time correction has been performed, the method will +by default filter the object by adjusted retention times. +The argument \code{adjusted} allows to specify manually whether filtering +should be performed by raw or adjusted retention times. Filtering by +retention time does not drop any preprocessing results. The method returns an empty object if no spectrum or feature is within the specified retention time range. } @@ -89,21 +98,40 @@ fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"), ## Read the files od <- readMSData2(fs) -## Perform feature detection on them using default matched filter settings. +## Perform peak detection on them using default matched filter settings. mfp <- MatchedFilterParam() -xod <- detectFeatures(od, param = mfp) +xod <- findChromPeaks(od, param = mfp) ## Subset the dataset to the first and third file. xod_sub <- filterFile(xod, file = c(1, 3)) -## The number of features per file for the full object -table(features(xod)[, "sample"]) +## The number of chromatographic peaks per file for the full object +table(chromPeaks(xod)[, "sample"]) -## The number of features per file for the subset -table(features(xod_sub)[, "sample"]) +## The number of chromatographic peaks per file for the subset +table(chromPeaks(xod_sub)[, "sample"]) basename(fileNames(xod)) basename(fileNames(xod_sub)) + +## Filter on mz values; chromatographic peaks and features within the +## mz range are retained (as well as adjusted retention times). +xod_sub <- filterMz(xod, mz = c(300, 400)) +head(chromPeaks(xod_sub)) +nrow(chromPeaks(xod_sub)) +nrow(chromPeaks(xod)) + +## Filter on rt values. All chromatographic peaks and features within the +## retention time range are retained. Filtering is performed by default on +## adjusted retention times, if present. +xod_sub <- filterRt(xod, rt = c(2700, 2900)) + +range(rtime(xod_sub)) +head(chromPeaks(xod_sub)) +range(chromPeaks(xod_sub)[, "rt"]) + +nrow(chromPeaks(xod)) +nrow(chromPeaks(xod_sub)) } \author{ Johannes Rainer diff --git a/man/XCMSnExp-inherited-methods.Rd b/man/XCMSnExp-inherited-methods.Rd index be90057fe..762706e36 100644 --- a/man/XCMSnExp-inherited-methods.Rd +++ b/man/XCMSnExp-inherited-methods.Rd @@ -127,8 +127,11 @@ and examples. The \code{pickPeaks} method performs peak picking. See \code{\link[MSnbase]{pickPeaks}} documentation for details and examples. -The \code{removePeaks} method removes peaks (intensities) lower than a -threshold. Note that these peaks are not features! See \code{\link[MSnbase]{removePeaks}} documentation for details and examples. +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}} +documentation for details and examples. The \code{smooth} method smooths spectra. See \code{\link[MSnbase]{smooth}} documentation for details and examples. diff --git a/man/XCMSnExp-peak-grouping-results.Rd b/man/XCMSnExp-peak-grouping-results.Rd new file mode 100644 index 000000000..785fbb6c7 --- /dev/null +++ b/man/XCMSnExp-peak-grouping-results.Rd @@ -0,0 +1,59 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methods-XCMSnExp.R +\docType{methods} +\name{groupval,XCMSnExp-method} +\alias{groupval,XCMSnExp-method} +\title{Accessing mz-rt feature data values} +\usage{ +\S4method{groupval}{XCMSnExp}(object, method = c("medret", "maxint"), + value = "index", intensity = "into") +} +\arguments{ +\item{object}{A \code{\link{XCMSnExp}} object providing the feature +definitions.} + +\item{method}{\code{character} specifying the method to resolve +multi-peak mappings within the same sample, i.e. to define the +\emph{representative} peak for a feature in samples where more than +one peak was assigned to the feature. If \code{"medret"}: select the +peak closest to the median retention time of the feature. +If \code{"maxint"}: select the peak yielding the largest signal.} + +\item{value}{\code{character} specifying the name of the column in +\code{chromPeaks(object)} that should be returned or \code{"index"} (the +default) to return the index of the peak in the \code{chromPeaks(object)} +matrix corresponding to the \emph{representative} peak for the feature +in the respective sample.} + +\item{intensity}{\code{character} specifying the name of the column in the +\code{chromPeaks(objects)} matrix containing the intensity value of the +peak that should be used for the conflict resolution if +\code{method = "maxint"}.} +} +\value{ +For \code{groupval}: a \code{matrix} with feature values, columns +representing samples, rows features. The order of the features +matches the order found in the \code{featureDefinitions(object)} +\code{DataFrame}. An \code{NA} is reported for features without corresponding +chromatographic peak in the respective sample(s). +} +\description{ +\code{groupval,XCMSnExp}: extract a \code{matrix} for feature +values with rows representing features and columns samples. Parameter +\code{value} allows to define which column from the \code{\link{chromPeaks}} +matrix should be returned. Multiple chromatographic peaks from the same +sample can be assigned to a feature. Parameter \code{method} allows to +specify the method to be used in such cases to chose from which of the peaks +the value should be returned. +} +\author{ +Johannes Rainer +} +\seealso{ +\code{\link{XCMSnExp}} for information on the data object. +\code{\link{featureDefinitions}} to extract the \code{DataFrame} with the +feature definitions. +\code{\link{hasFeatures}} to evaluate whether the +\code{\link{XCMSnExp}} provides feature definitions. +} + diff --git a/man/adjustRtime-featureGroups.Rd b/man/adjustRtime-featureGroups.Rd deleted file mode 100644 index fac7de50f..000000000 --- a/man/adjustRtime-featureGroups.Rd +++ /dev/null @@ -1,228 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R -\docType{class} -\name{adjustRtime-featureGroups} -\alias{FeatureGroupsParam} -\alias{FeatureGroupsParam-class} -\alias{adjustRtime,XCMSnExp,FeatureGroupsParam-method} -\alias{adjustRtime-featureGroups} -\alias{extraFeatures} -\alias{extraFeatures,FeatureGroupsParam-method} -\alias{extraFeatures<-} -\alias{extraFeatures<-,FeatureGroupsParam-method} -\alias{family} -\alias{family,FeatureGroupsParam-method} -\alias{family<-} -\alias{family<-,FeatureGroupsParam-method} -\alias{minFraction,FeatureGroupsParam-method} -\alias{minFraction<-,FeatureGroupsParam-method} -\alias{show,FeatureGroupsParam-method} -\alias{smooth} -\alias{smooth,FeatureGroupsParam-method} -\alias{smooth<-} -\alias{smooth<-,FeatureGroupsParam-method} -\alias{span} -\alias{span,FeatureGroupsParam-method} -\alias{span<-} -\alias{span<-,FeatureGroupsParam-method} -\title{Retention time correction based on alignment of house keeping feature -groups} -\usage{ -FeatureGroupsParam(minFraction = 0.9, extraFeatures = 1, smooth = "loess", - span = 0.2, family = "gaussian") - -\S4method{show}{FeatureGroupsParam}(object) - -\S4method{minFraction}{FeatureGroupsParam}(object) - -\S4method{minFraction}{FeatureGroupsParam}(object) <- value - -\S4method{extraFeatures}{FeatureGroupsParam}(object) - -\S4method{extraFeatures}{FeatureGroupsParam}(object) <- value - -\S4method{smooth}{FeatureGroupsParam}(x) - -\S4method{smooth}{FeatureGroupsParam}(object) <- value - -\S4method{span}{FeatureGroupsParam}(object) - -\S4method{span}{FeatureGroupsParam}(object) <- value - -\S4method{family}{FeatureGroupsParam}(object) - -\S4method{family}{FeatureGroupsParam}(object) <- value - -\S4method{adjustRtime}{XCMSnExp,FeatureGroupsParam}(object, param) -} -\arguments{ -\item{minFraction}{numeric(1) between 0 and 1 defining the minimum required -fraction of samples in which features for the feature group were identified. -Feature groups passing this criteria will aligned across samples and retention -times of individual spectra will be adjusted based on this alignment. For -\code{minFraction = 1} the feature group has to contain features in all -samples of the experiment.} - -\item{extraFeatures}{numeric(1) defining the maximal number of additional -features for all samples to be assigned to a feature group for retention time -correction. For a data set with 6 samples, \code{extraFeatures = 1} uses all -feature groups with a total feature count \code{<= 6 + 1}. The total feature -count is the total number of features being assigned to a feature group and -considers also multiple features within a sample being assigned to the group.} - -\item{smooth}{character defining the function to be used, to interpolate -corrected retention times for all feature groups. Either \code{"loess"} or -\code{"linear"}.} - -\item{span}{numeric(1) defining the degree of smoothing (if -\code{smooth = "loess"}). This parameter is passed to the internal call -to \code{\link{loess}}.} - -\item{family}{character defining the method to be used for loess smoothing. -Allowed values are \code{"gaussian"} and \code{"symmetric"}.See -\code{\link{loess}} for more information.} - -\item{object}{For \code{adjustRtime}: an \code{\link{XCMSnExp}} object -containing the results from a previous feature detection (see -\code{\link{detectFeatures}}) and alignment analysis (see -\code{\link{groupFeatures}}). - -For all other methods: a \code{FeatureGroupsParam} object.} - -\item{value}{The value for the slot.} - -\item{x}{a \code{FeatureGroupsParam} object.} - -\item{param}{A \code{FeatureGroupsParam} object containing all settings for -the retention time correction method..} -} -\value{ -The \code{FeatureGroupsParam} function returns a -\code{FeatureGroupsParam} class instance with all of the settings -specified for retention time adjustment based on \emph{house keeping} -feature groups. - -For \code{adjustRtime}: a \code{\link{XCMSnExp}} object with the -results of the retention time adjustment step. These can be accessed with the -\code{\link{adjustedRtime}} method. Retention time correction does also adjust -the retention time of the identified features (accessed \emph{via} -\code{\link{features}}. Note that retention time correction drops -all previous alignment results from the result object. -} -\description{ -This method performs retention time adjustment based on the -alignment of feature groups present in all/most samples (hence corresponding -to house keeping compounds). First the retention time deviation of these -feature groups is described by fitting either a polynomial -(\code{smooth = "loess"}) or a linear (\code{smooth = "linear"}) model to the -data points. These models are subsequently used to adjust the retention time -of each spectrum in each sample. - -The \code{FeatureGroupsParam} class allows to specify all -settings for the retention time adjustment based on \emph{house keeping} -feature groups present in most samples. -Instances should be created with the \code{FeatureGroupsParam} constructor. - -\code{minFraction},\code{minFraction<-}: getter and setter -for the \code{minFraction} slot of the object. - -\code{extraFeatures},\code{extraFeatures<-}: getter and setter -for the \code{extraFeatures} slot of the object. - -\code{smooth},\code{smooth<-}: getter and setter -for the \code{smooth} slot of the object. - -\code{span},\code{span<-}: getter and setter -for the \code{span} slot of the object. - -\code{family},\code{family<-}: getter and setter -for the \code{family} slot of the object. - -\code{adjustRtime,XCMSnExp,FeatureGroupsParam}: -performs retention time correction based on the alignment of feature groups -found in all/most samples. -} -\section{Slots}{ - -\describe{ -\item{\code{.__classVersion__,minFraction,extraFeatures,smooth,span,family}}{See corresponding parameter above. \code{.__classVersion__} stores -the version from the class. Slots values should exclusively be accessed -\emph{via} the corresponding getter and setter methods listed above.} -}} -\note{ -These methods and classes are part of the updated and modernized -\code{xcms} user interface which will eventually replace the -\code{\link{group}} methods. All of the settings to the alignment algorithm -can be passed with a \code{FeatureGroupsParam} object. - -Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause -all feature grouping (alignment) results to be dropped. -} -\examples{ -############################## -## feature detection and alignment. -## -## Below we perform first a feature detection (using the matchedFilter -## method) on some of the test files from the faahKO package followed by -## a feature alignment. -library(faahKO) -library(MSnbase) -fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, - full.names = TRUE) - -## Reading 2 of the KO samples -raw_data <- readMSData2(fls[1:2]) - -## Perform the feature detection using the matchedFilter method. -mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -res <- detectFeatures(raw_data, param = mfp) - -head(features(res)) -## The number of features identified per sample: -table(features(res)[, "sample"]) - -## Performing the feature alignment using the "feature density" method. -p <- FeatureDensityParam(sampleGroups = c(1, 1)) -res <- groupFeatures(res, param = p) - -## Perform the retention time adjustment using feature groups found in both -## files. -fgp <- FeatureGroupsParam(minFraction = 1) -res <- adjustRtime(res, param = fgp) - -## Any grouping information was dropped -hasAlignedFeatures(res) - -## Plot the raw against the adjusted retention times. -plot(rtime(raw_data), rtime(res), pch = 16, cex = 0.25, col = fromFile(res)) - -## Adjusterd retention times can be accessed using -## rtime(object, adjusted = TRUE) and adjustedRtime -all.equal(rtime(res), adjustedRtime(res)) - -## To get the raw, unadjusted retention times: -all.equal(rtime(res, adjusted = FALSE), rtime(raw_data)) - -## To extract the retention times grouped by sample/file: -rts <- rtime(res, bySample = TRUE) -} -\author{ -Colin Smith, Johannes Rainer -} -\references{ -Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and -Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite -Profiling Using Nonlinear Peak Alignment, Matching, and Identification" -\emph{Anal. Chem.} 2006, 78:779-787. -} -\seealso{ -The \code{\link{do_adjustRtime_featureGroups}} core -API function and \code{\link{retcor.peakgroups}} for the old user interface. - -\code{\link{XCMSnExp}} for the object containing the results of -the feature alignment. - -Other retention time correction methods: \code{\link{adjustRtime-obiwarp}}, - \code{\link{adjustRtime}} -} - diff --git a/man/adjustRtime-obiwarp.Rd b/man/adjustRtime-obiwarp.Rd index 73bc46338..271e9482b 100644 --- a/man/adjustRtime-obiwarp.Rd +++ b/man/adjustRtime-obiwarp.Rd @@ -100,16 +100,17 @@ ObiwarpParam(binSize = 1, centerSample = integer(), response = 1L, \S4method{adjustRtime}{XCMSnExp,ObiwarpParam}(object, param) } \arguments{ -\item{binSize}{numeric(1) defining the bin size (in mz dimension) to be used -for the \emph{profile matrix} generation. See \code{step} parameter in -\code{\link{profile-matrix}} documentation for more details.} +\item{binSize}{\code{numeric(1)} defining the bin size (in mz dimension) +to be used for the \emph{profile matrix} generation. See \code{step} +parameter in \code{\link{profile-matrix}} documentation for more details.} -\item{centerSample}{integer(1) defining the index of the center sample in the -experiment. It defaults to \code{floor(median(1:length(fileNames(object))))}.} +\item{centerSample}{\code{integer(1)} defining the index of the center sample +in the experiment. It defaults to +\code{floor(median(1:length(fileNames(object))))}.} -\item{response}{numeric(1) defining the \emph{responsiveness} of warping with -\code{response = 0} giving linear warping on start and end points and -\code{response = 100} warping using all bijective anchors.} +\item{response}{\code{numeric(1)} defining the \emph{responsiveness} of +warping with \code{response = 0} giving linear warping on start and end +points and \code{response = 100} warping using all bijective anchors.} \item{distFun}{character defining the distance function to be used. Allowed values are \code{"cor"} (Pearson's correlation), \code{"cor_opt"} (calculate @@ -117,28 +118,28 @@ only 10\% diagonal band of distance matrix; better runtime), \code{"cov"} (covariance), \code{"prd"} (product) and \code{"euc"} (Euclidian distance). The default value is \code{distFun = "cor_opt"}.} -\item{gapInit}{numeric(1) defining the penalty for gap opening. The default -value for \code{gapInit} depends on the value of \code{distFun}: for +\item{gapInit}{\code{numeric(1)} defining the penalty for gap opening. The +default value for \code{gapInit} depends on the value of \code{distFun}: for \code{distFun = "cor"} and \code{distFun = "cor_opt"} it is \code{0.3}, for \code{distFun = "cov"} and \code{distFun = "prd"} \code{0.0} and for \code{distFun = "euc"} \code{0.9}.} -\item{gapExtend}{numeric(1) defining the penalty for gap enlargement. The -default value for \code{gapExtend} depends on the value of \code{distFun}, +\item{gapExtend}{\code{numeric(1)} defining the penalty for gap enlargement. +The default value for \code{gapExtend} depends on the value of \code{distFun}, for \code{distFun = "cor"} and \code{distFun = "cor_opt"} it is \code{2.4}, for \code{distFun = "cov"} \code{11.7}, for \code{distFun = "euc"} \code{1.8} and for \code{distFun = "prd"} {7.8}.} -\item{factorDiag}{numeric(1) defining the local weight applied to diagonal -moves in the alignment.} +\item{factorDiag}{\code{numeric(1)} defining the local weight applied to +diagonal moves in the alignment.} -\item{factorGap}{numeric(1) defining the local weight for gap moves in the -alignment.} +\item{factorGap}{\code{numeric(1)} defining the local weight for gap moves +in the alignment.} -\item{localAlignment}{logical(1) whether a local alignment should be +\item{localAlignment}{\code{logical(1)} whether a local alignment should be performed instead of the default global alignment.} -\item{initPenalty}{numeric(1) defining the penalty for initiating an +\item{initPenalty}{\code{numeric(1)} defining the penalty for initiating an alignment (for local alignment only).} \item{object}{For \code{adjustRtime}: an \code{\link{XCMSnExp}} object. @@ -146,7 +147,7 @@ alignment (for local alignment only).} For all other methods: a \code{ObiwarpParam} object.} \item{param}{A \code{ObiwarpParam} object containing all settings for -the retention time correction method.} +the alignment method.} \item{value}{The value for the slot.} } @@ -159,9 +160,9 @@ For \code{adjustRtime,XCMSnExp,ObiwarpParam}: a \code{\link{XCMSnExp}} object with the results of the retention time adjustment step. These can be accessed with the \code{\link{adjustedRtime}} method. Retention time correction does also adjust the retention time of the -identified features (accessed \emph{via} \code{\link{features}}. Note that -retention time correction drops all previous alignment results from the -result object. +identified chromatographic peaks (accessed \emph{via} +\code{\link{chromPeaks}}. Note that retention time correction drops all +previous peak grouping results from the result object. For \code{adjustRtime,OnDiskMSnExp,ObiwarpParam}: a \code{numeric} with the adjusted retention times per spectra (in the same order than \code{rtime}). @@ -172,7 +173,7 @@ Obiwarp method [Prince 2006]. It is based on the code at \url{http://obi-warp.sourceforge.net} but supports alignment of multiple samples by aligning each against a \emph{center} sample. The alignment is performed directly on the \code{\link{profile-matrix}} and can hence be -performed independently of the feature detection or feature grouping. +performed independently of the peak detection or peak grouping. The \code{ObiwarpParam} class allows to specify all settings for the retention time adjustment based on the \emph{obiwarp} @@ -210,8 +211,8 @@ for the \code{localAlignment} slot of the object. for the \code{initPenalty} slot of the object. \code{adjustRtime,XCMSnExp,ObiwarpParam}: -performs retention time correction based on the alignment of feature groups -found in all/most samples. +performs retention time correction/alignment based on the total mz-rt data +using the \emph{obiwarp} method. } \section{Slots}{ @@ -227,7 +228,7 @@ These methods and classes are part of the updated and modernized can be passed with a \code{ObiwarpParam} object. Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause -all feature grouping (alignment) results to be dropped. +all peak grouping (correspondence) results to be dropped. } \examples{ library(faahKO) @@ -252,9 +253,10 @@ resL <- split(res, fromFile(raw_data)) ############################## ## Perform retention time correction on an XCMSnExp: ## -## Perform first the feature detection using the matchedFilter method. +## Perform first the chromatographic peak detection using the matchedFilter +## method. mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -res <- detectFeatures(raw_data, param = mfp) +res <- findChromPeaks(raw_data, param = mfp) ## Performing the retention time adjustment using obiwarp. res_2 <- adjustRtime(res, param = ObiwarpParam()) @@ -262,9 +264,9 @@ res_2 <- adjustRtime(res, param = ObiwarpParam()) head(rtime(res_2)) head(rtime(raw_data)) -## Also the retention times of the detected features were adjusted. -tail(features(res)) -tail(features(res_2)) +## Also the retention times of the detected peaks were adjusted. +tail(chromPeaks(res)) +tail(chromPeaks(res_2)) } \author{ Colin Smith, Johannes Rainer @@ -273,14 +275,18 @@ Colin Smith, Johannes Rainer John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of ESI-LC-MS Proteomics Data Sets by Ordered Bijective Interpolated Warping" \emph{Anal. Chem.} 2006, 78(17):6140-6152. + +John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of +ESI-LC-MS Proteomic Data Sets by Ordered Bijective Interpolated Warping" +\emph{Anal. Chem.} 2006, 78 (17), 6140-6152. } \seealso{ \code{\link{retcor.obiwarp}} for the old user interface. \code{\link{XCMSnExp}} for the object containing the results of -the feature alignment. +the alignment. -Other retention time correction methods: \code{\link{adjustRtime-featureGroups}}, +Other retention time correction methods: \code{\link{adjustRtime-peakGroups}}, \code{\link{adjustRtime}} } diff --git a/man/adjustRtime-peakGroups.Rd b/man/adjustRtime-peakGroups.Rd new file mode 100644 index 000000000..38eb593d7 --- /dev/null +++ b/man/adjustRtime-peakGroups.Rd @@ -0,0 +1,231 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R +\docType{class} +\name{adjustRtime-peakGroups} +\alias{PeakGroupsParam} +\alias{PeakGroupsParam-class} +\alias{adjustRtime,XCMSnExp,PeakGroupsParam-method} +\alias{adjustRtime-peakGroups} +\alias{extraPeaks} +\alias{extraPeaks,PeakGroupsParam-method} +\alias{extraPeaks<-} +\alias{extraPeaks<-,PeakGroupsParam-method} +\alias{family} +\alias{family,PeakGroupsParam-method} +\alias{family<-} +\alias{family<-,PeakGroupsParam-method} +\alias{minFraction,PeakGroupsParam-method} +\alias{minFraction<-,PeakGroupsParam-method} +\alias{show,PeakGroupsParam-method} +\alias{smooth} +\alias{smooth,PeakGroupsParam-method} +\alias{smooth<-} +\alias{smooth<-,PeakGroupsParam-method} +\alias{span} +\alias{span,PeakGroupsParam-method} +\alias{span<-} +\alias{span<-,PeakGroupsParam-method} +\title{Retention time correction based on alignment of house keeping peak +groups} +\usage{ +PeakGroupsParam(minFraction = 0.9, extraPeaks = 1, smooth = "loess", + span = 0.2, family = "gaussian") + +\S4method{show}{PeakGroupsParam}(object) + +\S4method{minFraction}{PeakGroupsParam}(object) + +\S4method{minFraction}{PeakGroupsParam}(object) <- value + +\S4method{extraPeaks}{PeakGroupsParam}(object) + +\S4method{extraPeaks}{PeakGroupsParam}(object) <- value + +\S4method{smooth}{PeakGroupsParam}(x) + +\S4method{smooth}{PeakGroupsParam}(object) <- value + +\S4method{span}{PeakGroupsParam}(object) + +\S4method{span}{PeakGroupsParam}(object) <- value + +\S4method{family}{PeakGroupsParam}(object) + +\S4method{family}{PeakGroupsParam}(object) <- value + +\S4method{adjustRtime}{XCMSnExp,PeakGroupsParam}(object, param) +} +\arguments{ +\item{minFraction}{\code{numeric(1)} between 0 and 1 defining the minimum +required fraction of samples in which peaks for the peak group were +identified. Peak groups passing this criteria will aligned across samples +and retention times of individual spectra will be adjusted based on this +alignment. For \code{minFraction = 1} the peak group has to contain peaks +in all samples of the experiment.} + +\item{extraPeaks}{\code{numeric(1)} defining the maximal number of additional +peaks for all samples to be assigned to a peak group (i.e. feature) for +retention time correction. For a data set with 6 samples, +\code{extraPeaks = 1} uses all peak groups with a total peak count +\code{<= 6 + 1}. The total peak count is the total number of peaks being +assigned to a peak group and considers also multiple peaks within a sample +being assigned to the group.} + +\item{smooth}{character defining the function to be used, to interpolate +corrected retention times for all peak groups. Either \code{"loess"} or +\code{"linear"}.} + +\item{span}{\code{numeric(1)} defining the degree of smoothing (if +\code{smooth = "loess"}). This parameter is passed to the internal call +to \code{\link{loess}}.} + +\item{family}{character defining the method to be used for loess smoothing. +Allowed values are \code{"gaussian"} and \code{"symmetric"}.See +\code{\link{loess}} for more information.} + +\item{object}{For \code{adjustRtime}: an \code{\link{XCMSnExp}} object +containing the results from a previous chromatographic peak detection (see +\code{\link{findChromPeaks}}) and alignment analysis (see +\code{\link{groupChromPeaks}}). + +For all other methods: a \code{PeakGroupsParam} object.} + +\item{value}{The value for the slot.} + +\item{x}{a \code{PeakGroupsParam} object.} + +\item{param}{A \code{PeakGroupsParam} object containing all settings for +the retention time correction method..} +} +\value{ +The \code{PeakGroupsParam} function returns a +\code{PeakGroupsParam} class instance with all of the settings +specified for retention time adjustment based on \emph{house keeping} +features/peak groups. + +For \code{adjustRtime}: a \code{\link{XCMSnExp}} object with the +results of the retention time adjustment step. These can be accessed with the +\code{\link{adjustedRtime}} method. Retention time correction does also adjust +the retention time of the identified chromatographic peaks (accessed +\emph{via} \code{\link{chromPeaks}}. Note that retention time correction +drops all previous alignment results from the result object. +} +\description{ +This method performs retention time adjustment based on the +alignment of chromatographic peak groups present in all/most samples (hence +corresponding to house keeping compounds). First the retention time deviation +of these peak groups is described by fitting either a polynomial +(\code{smooth = "loess"}) or a linear (\code{smooth = "linear"}) model to the +data points. These models are subsequently used to adjust the retention time +of each spectrum in each sample. + +The \code{PeakGroupsParam} class allows to specify all +settings for the retention time adjustment based on \emph{house keeping} +peak groups present in most samples. +Instances should be created with the \code{PeakGroupsParam} constructor. + +\code{minFraction},\code{minFraction<-}: getter and setter +for the \code{minFraction} slot of the object. + +\code{extraPeaks},\code{extraPeaks<-}: getter and setter +for the \code{extraPeaks} slot of the object. + +\code{smooth},\code{smooth<-}: getter and setter +for the \code{smooth} slot of the object. + +\code{span},\code{span<-}: getter and setter +for the \code{span} slot of the object. + +\code{family},\code{family<-}: getter and setter +for the \code{family} slot of the object. + +\code{adjustRtime,XCMSnExp,PeakGroupsParam}: +performs retention time correction based on the alignment of peak groups +(features) found in all/most samples. +} +\section{Slots}{ + +\describe{ +\item{\code{.__classVersion__,minFraction,extraPeaks,smooth,span,family}}{See corresponding parameter above. \code{.__classVersion__} stores +the version from the class. Slots values should exclusively be accessed +\emph{via} the corresponding getter and setter methods listed above.} +}} +\note{ +These methods and classes are part of the updated and modernized +\code{xcms} user interface which will eventually replace the +\code{\link{group}} methods. All of the settings to the alignment algorithm +can be passed with a \code{PeakGroupsParam} object. + +This method requires that a correspondence has been performed on the +data (see \code{\link{groupChromPeaks}}). Calling \code{adjustRtime} on an +\code{XCMSnExp} object will cause all peak grouping (correspondence) results +to be dropped after rt correction. +} +\examples{ +############################## +## Chromatographic peak detection and grouping. +## +## Below we perform first a peak detection (using the matchedFilter +## method) on some of the test files from the faahKO package followed by +## a peak grouping. +library(faahKO) +library(xcms) +fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, + full.names = TRUE) + +## Reading 2 of the KO samples +raw_data <- readMSData2(fls[1:2]) + +## Perform the peak detection using the matchedFilter method. +mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) +res <- findChromPeaks(raw_data, param = mfp) + +head(chromPeaks(res)) +## The number of peaks identified per sample: +table(chromPeaks(res)[, "sample"]) + +## Performing the peak grouping using the "peak density" method. +p <- PeakDensityParam(sampleGroups = c(1, 1)) +res <- groupChromPeaks(res, param = p) + +## Perform the retention time adjustment using peak groups found in both +## files. +fgp <- PeakGroupsParam(minFraction = 1) +res <- adjustRtime(res, param = fgp) + +## Any grouping information was dropped +hasFeatures(res) + +## Plot the raw against the adjusted retention times. +plot(rtime(raw_data), rtime(res), pch = 16, cex = 0.25, col = fromFile(res)) + +## Adjusterd retention times can be accessed using +## rtime(object, adjusted = TRUE) and adjustedRtime +all.equal(rtime(res), adjustedRtime(res)) + +## To get the raw, unadjusted retention times: +all.equal(rtime(res, adjusted = FALSE), rtime(raw_data)) + +## To extract the retention times grouped by sample/file: +rts <- rtime(res, bySample = TRUE) +} +\author{ +Colin Smith, Johannes Rainer +} +\references{ +Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and +Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite +Profiling Using Nonlinear Peak Alignment, Matching, and Identification" +\emph{Anal. Chem.} 2006, 78:779-787. +} +\seealso{ +The \code{\link{do_adjustRtime_peakGroups}} core +API function and \code{\link{retcor.peakgroups}} for the old user interface. + +\code{\link{XCMSnExp}} for the object containing the results of +the alignment. + +Other retention time correction methods: \code{\link{adjustRtime-obiwarp}}, + \code{\link{adjustRtime}} +} + diff --git a/man/adjustRtime.Rd b/man/adjustRtime.Rd index 00df1cf10..2daa40358 100644 --- a/man/adjustRtime.Rd +++ b/man/adjustRtime.Rd @@ -2,18 +2,21 @@ % Please edit documentation in R/DataClasses.R \name{adjustRtime} \alias{adjustRtime} -\title{Retention time correction methods.} +\title{Alignment: Retention time correction methods.} \description{ The \code{adjustRtime} method(s) perform retention time -correction between chromatograms of different samples. These methods are -part of the modernized \code{xcms} user interface. +correction (alignment) between chromatograms of different samples. These +methods are part of the modernized \code{xcms} user interface. -The implemented feature alignment methods are: +The implemented retention time adjustment methods are: \describe{ -\item{featureGroups}{retention time correction based on aligment of feature -groups present in most/all samples. -See \code{\link{adjustRtime-featureGroups}} for more details.} +\item{peakGroups}{retention time correction based on aligment of features +(peak groups) present in most/all samples. +See \code{\link{adjustRtime-peakGroups}} for more details.} +\item{obiwarp}{alignment based on the complete mz-rt data. This method does +not require any identified peaks or defined features. See +\code{\link{adjustRtime-obiwarp}} for more details.} } } \author{ @@ -23,7 +26,7 @@ Johannes Rainer \code{\link{retcor}} for the \emph{old} retention time correction methods. -Other retention time correction methods: \code{\link{adjustRtime-featureGroups}}, - \code{\link{adjustRtime-obiwarp}} +Other retention time correction methods: \code{\link{adjustRtime-obiwarp}}, + \code{\link{adjustRtime-peakGroups}} } diff --git a/man/chromatographic-peak-detection.Rd b/man/chromatographic-peak-detection.Rd new file mode 100644 index 000000000..1294663b5 --- /dev/null +++ b/man/chromatographic-peak-detection.Rd @@ -0,0 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R +\name{chromatographic-peak-detection} +\alias{chromatographic-peak-detection} +\alias{findChromPeaks} +\title{Chromatographic peak detection methods.} +\description{ +The \code{findChromPeaks} methods perform the chromatographic +peak detection on LC/GC-MS data and are part of the modernized \code{xcms} +user interface. + +The implemented peak detection methods in chromatographic space are: +\describe{ +\item{centWave}{chromatographic peak detection using the \emph{centWave} +method. See \code{\link{centWave}} for more details.} + +\item{centWave with predicted isotopes}{peak detection using a two-step +centWave-based approach considering also feature isotopes. See +\code{\link{centWaveWithPredIsoROIs}} for more details.} + +\item{matchedFilter}{peak detection in chromatographic space. See +\code{\link{matchedFilter}} for more details.} + +\item{massifquant}{peak detection using the Kalman filter-based +method. See \code{\link{massifquant}} for more details.} + +\item{MSW}{single-spectrum non-chromatography MS data peak detection. +See \code{\link{MSW}} for more details.} + +} +} +\author{ +Johannes Rainer +} +\seealso{ +\code{\link{findPeaks}} for the \emph{old} peak detection +methods. + +Other peak detection methods: \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, + \code{\link{findChromPeaks-centWave}}, + \code{\link{findChromPeaks-massifquant}}, + \code{\link{findChromPeaks-matchedFilter}}, + \code{\link{findPeaks-MSW}} +} + diff --git a/man/detectFeatures.Rd b/man/detectFeatures.Rd deleted file mode 100644 index eb37f0b9e..000000000 --- a/man/detectFeatures.Rd +++ /dev/null @@ -1,43 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DataClasses.R -\name{detectFeatures} -\alias{detectFeatures} -\title{Feature detection methods.} -\description{ -The \code{detectFeature} methods are part of the modernized -\code{xcms} user interface. - -The implemented feature detection methods are: -\describe{ -\item{centWave}{feature detection using the \emph{centWave} method. -See \code{\link{centWave}} for more details.} - -\item{centWave with predicted isotopes}{feature detection using a two-step -centWave-based approach considering also feature isotopes. See -\code{\link{centWaveWithPredIsoROIs}} for more details.} - -\item{matchedFilter}{peak detection in chromatographic space. See -\code{\link{matchedFilter}} for more details.} - -\item{massifquant}{peak detection using the Kalman filter-based feature -method. See \code{\link{massifquant}} for more details.} - -\item{MSW}{single-spectrum non-chromatography MS data feature detection. -See \code{\link{MSW}} for more details.} - -} -} -\author{ -Johannes Rainer -} -\seealso{ -\code{\link{findPeaks}} for the \emph{old} feature detection -methods. - -Other feature detection methods: \code{\link{featureDetection-MSW}}, - \code{\link{featureDetection-centWaveWithPredIsoROIs}}, - \code{\link{featureDetection-centWave}}, - \code{\link{featureDetection-massifquant}}, - \code{\link{featureDetection-matchedFilter}} -} - diff --git a/man/do_adjustRtime_featureGroups.Rd b/man/do_adjustRtime_featureGroups.Rd deleted file mode 100644 index 70e182c26..000000000 --- a/man/do_adjustRtime_featureGroups.Rd +++ /dev/null @@ -1,79 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_adjustRtime-functions.R -\name{do_adjustRtime_featureGroups} -\alias{do_adjustRtime_featureGroups} -\title{Align spectrum retention times across samples using feature groups -found in most samples} -\usage{ -do_adjustRtime_featureGroups(features, featureIndex, rtime, minFraction = 0.9, - extraFeatures = 1, smooth = c("loess", "linear"), span = 0.2, - family = c("gaussian", "symmetric")) -} -\arguments{ -\item{features}{a \code{matrix} or \code{data.frame} with the identified -features in the samples.} - -\item{featureIndex}{a \code{list} of indices that provides the grouping -information of the features (across and within samples).} - -\item{rtime}{A \code{list} of \code{numeric} vectors with the retention times -per file/sample.} - -\item{minFraction}{numeric(1) between 0 and 1 defining the minimum required -fraction of samples in which features for the feature group were identified. -Feature groups passing this criteria will aligned across samples and retention -times of individual spectra will be adjusted based on this alignment. For -\code{minFraction = 1} the feature group has to contain features in all -samples of the experiment.} - -\item{extraFeatures}{numeric(1) defining the maximal number of additional -features for all samples to be assigned to a feature group for retention time -correction. For a data set with 6 samples, \code{extraFeatures = 1} uses all -feature groups with a total feature count \code{<= 6 + 1}. The total feature -count is the total number of features being assigned to a feature group and -considers also multiple features within a sample being assigned to the group.} - -\item{smooth}{character defining the function to be used, to interpolate -corrected retention times for all feature groups. Either \code{"loess"} or -\code{"linear"}.} - -\item{span}{numeric(1) defining the degree of smoothing (if -\code{smooth = "loess"}). This parameter is passed to the internal call -to \code{\link{loess}}.} - -\item{family}{character defining the method to be used for loess smoothing. -Allowed values are \code{"gaussian"} and \code{"symmetric"}.See -\code{\link{loess}} for more information.} -} -\value{ -A \code{list} with \code{numeric} vectors with the adjusted retention -times grouped by sample. -} -\description{ -The function performs retention time correction by assessing -the retention time deviation across all samples using feature groups containg -features present in most/all samples. The retention time deviation -for these feature groups in each sample is described by fitting either a -polynomial (\code{smooth = "loess"}) or a linear (\code{smooth = "linear"}) -model to the data points. The models are subsequently used to adjust the -retention time for each spectrum in each sample. -} -\details{ -The alignment bases on the presence of compounds that can be found -in all/most samples of an experiment. The retention times of individual -spectra are then adjusted based on the alignment of the feature groups -corresponding to these \emph{house keeping compounds}. The paraneters -\code{minFraction} and \code{extraFeatures} can be used to fine tune which -feature groups should be used for the alignment (i.e. which feature groups -most likely correspond to the above mentioned house keeping compounds). -} -\author{ -Colin Smith, Johannes Rainer -} -\references{ -Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and -Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite -Profiling Using Nonlinear Peak Alignment, Matching, and Identification" -\emph{Anal. Chem.} 2006, 78:779-787. -} - diff --git a/man/do_adjustRtime_peakGroups.Rd b/man/do_adjustRtime_peakGroups.Rd new file mode 100644 index 000000000..99215f152 --- /dev/null +++ b/man/do_adjustRtime_peakGroups.Rd @@ -0,0 +1,81 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/do_adjustRtime-functions.R +\name{do_adjustRtime_peakGroups} +\alias{do_adjustRtime_peakGroups} +\title{Align spectrum retention times across samples using peak groups +found in most samples} +\usage{ +do_adjustRtime_peakGroups(peaks, peakIndex, rtime, minFraction = 0.9, + extraPeaks = 1, smooth = c("loess", "linear"), span = 0.2, + family = c("gaussian", "symmetric")) +} +\arguments{ +\item{peaks}{a \code{matrix} or \code{data.frame} with the identified +chromatographic peaks in the samples.} + +\item{peakIndex}{a \code{list} of indices that provides the grouping +information of the chromatographic peaks (across and within samples).} + +\item{rtime}{A \code{list} of \code{numeric} vectors with the retention times +per file/sample.} + +\item{minFraction}{\code{numeric(1)} between 0 and 1 defining the minimum +required fraction of samples in which peaks for the peak group were +identified. Peak groups passing this criteria will aligned across samples +and retention times of individual spectra will be adjusted based on this +alignment. For \code{minFraction = 1} the peak group has to contain peaks +in all samples of the experiment.} + +\item{extraPeaks}{\code{numeric(1)} defining the maximal number of additional +peaks for all samples to be assigned to a peak group (i.e. feature) for +retention time correction. For a data set with 6 samples, +\code{extraPeaks = 1} uses all peak groups with a total peak count +\code{<= 6 + 1}. The total peak count is the total number of peaks being +assigned to a peak group and considers also multiple peaks within a sample +being assigned to the group.} + +\item{smooth}{character defining the function to be used, to interpolate +corrected retention times for all peak groups. Either \code{"loess"} or +\code{"linear"}.} + +\item{span}{\code{numeric(1)} defining the degree of smoothing (if +\code{smooth = "loess"}). This parameter is passed to the internal call +to \code{\link{loess}}.} + +\item{family}{character defining the method to be used for loess smoothing. +Allowed values are \code{"gaussian"} and \code{"symmetric"}.See +\code{\link{loess}} for more information.} +} +\value{ +A \code{list} with \code{numeric} vectors with the adjusted retention +times grouped by sample. +} +\description{ +The function performs retention time correction by assessing +the retention time deviation across all samples using peak groups (features) +containg chromatographic peaks present in most/all samples. The retention +time deviation for these features in each sample is described by fitting +either a polynomial (\code{smooth = "loess"}) or a linear +(\code{smooth = "linear"}) model to the data points. The models are +subsequently used to adjust the retention time for each spectrum in each +sample. +} +\details{ +The alignment bases on the presence of compounds that can be found +in all/most samples of an experiment. The retention times of individual +spectra are then adjusted based on the alignment of the features +corresponding to these \emph{house keeping compounds}. The paraneters +\code{minFraction} and \code{extraPeaks} can be used to fine tune which +features should be used for the alignment (i.e. which features +most likely correspond to the above mentioned house keeping compounds). +} +\author{ +Colin Smith, Johannes Rainer +} +\references{ +Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and +Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite +Profiling Using Nonlinear Peak Alignment, Matching, and Identification" +\emph{Anal. Chem.} 2006, 78:779-787. +} + diff --git a/man/do_detectFeatures_centWaveWithPredIsoROIs.Rd b/man/do_detectFeatures_centWaveWithPredIsoROIs.Rd deleted file mode 100644 index 3ce77c2ab..000000000 --- a/man/do_detectFeatures_centWaveWithPredIsoROIs.Rd +++ /dev/null @@ -1,180 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_detectFeatures-functions.R -\name{do_detectFeatures_centWaveWithPredIsoROIs} -\alias{do_detectFeatures_addPredIsoROIs} -\alias{do_detectFeatures_centWaveWithPredIsoROIs} -\title{Core API function for two-step centWave feature detection with feature isotopes} -\usage{ -do_detectFeatures_centWaveWithPredIsoROIs(mz, int, scantime, valsPerSpect, - ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), - mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, - fitgauss = FALSE, noise = 0, verboseColumns = FALSE, roiList = list(), - firstBaselineCheck = TRUE, roiScales = NULL, snthreshIsoROIs = 6.25, - maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, - polarity = "unknown") - -do_detectFeatures_addPredIsoROIs(mz, int, scantime, valsPerSpect, ppm = 25, - peakwidth = c(20, 50), snthresh = 6.25, prefilter = c(3, 100), - mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, - fitgauss = FALSE, noise = 0, verboseColumns = FALSE, features. = NULL, - maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, - polarity = "unknown") -} -\arguments{ -\item{mz}{Numeric vector with the individual m/z values from all scans/ -spectra of one file/sample.} - -\item{int}{Numeric vector with the individual intensity values from all -scans/spectra of one file/sample.} - -\item{scantime}{Numeric vector of length equal to the number of -spectra/scans of the data representing the retention time of each scan.} - -\item{valsPerSpect}{Numeric vector with the number of values for each -spectrum.} - -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} - -\item{peakwidth}{numeric(2) with the expected approximate -feature/peak width in chromatographic space. Given as a range (min, max) -in seconds.} - -\item{snthresh}{For \code{do_detectFeatures_addPredIsoROIs}: -numeric(1) defining the signal to noise threshold for the centWave algorithm. -For \code{do_detectFeatures_centWaveWithPredIsoROIs}: numeric(1) defining the -signal to noise threshold for the initial (first) centWave run.} - -\item{prefilter}{numeric(2): \code{c(k, I)} specifying the prefilter -step for the first analysis step (ROI detection). Mass traces are only -retained if they contain at least \code{k} peaks with intensity \code{>= I}.} - -\item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} - -\item{integrate}{Integration method. For \code{integrate = 1} peak limits -are found through descent on the mexican hat filtered data, for -\code{integrate = 2} the descent is done on the real data. The latter method -is more accurate but prone to noise, while the former is more robust, but -less exact.} - -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} - -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} - -\item{noise}{numeric(1) allowing to set a minimum intensity required -for centroids to be considered in the first analysis step (centroids with -intensity \code{< noise} are omitted from ROI detection).} - -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} - -\item{roiList}{An optional list of regions-of-interest (ROI) representing -detected mass traces. If ROIs are submitted the first analysis step is -omitted and feature detection is performed on the submitted ROIs. Each -ROI is expected to have the following elements specified: -\code{scmin} (start scan index), \code{scmax} (end scan index), -\code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} -(number of scans), \code{intensity} (summed intensity). Each ROI should be -represented by a \code{list} of elements or a single row \code{data.frame}.} - -\item{firstBaselineCheck}{logical(1). If \code{TRUE} continuous -data within regions of interest is checked to be above the first baseline.} - -\item{roiScales}{Optional numeric vector with length equal to \code{roiList} -defining the scale for each region of interest in \code{roiList} that should -be used for the centWave-wavelets.} - -\item{snthreshIsoROIs}{numeric(1) defining the signal to noise ratio cutoff -to be used in the second centWave run to identify features for predicted -isotope ROIs.} - -\item{maxCharge}{integer(1) defining the maximal isotope charge. Isotopes -will be defined for charges \code{1:maxCharge}.} - -\item{maxIso}{integer(1) defining the number of isotope peaks that should be -predicted for each feature identified in the first centWave run.} - -\item{mzIntervalExtension}{logical(1) whether the mz range for the predicted -isotope ROIs should be extended to increase detection of low intensity peaks.} - -\item{polarity}{character(1) specifying the polarity of the data. Currently -not used, but has to be \code{"positive"}, \code{"negative"} or -\code{"unknown"} if provided.} - -\item{features.}{A matrix or \code{xcmsPeaks} object such as one returned by -a call to \code{link{do_detectFeatures_centWave}} or -\code{link{findPeaks.centWave}} (both with \code{verboseColumns = TRUE}) -with the features for which isotopes should be predicted and used for an -additional feature detectoin using the centWave method. Required columns are: -\code{"mz"}, \code{"mzmin"}, \code{"mzmax"}, \code{"scmin"}, \code{"scmax"}, -\code{"scale"} and \code{"into"}.} -} -\value{ -A matrix, each row representing an identified feature. All non-overlapping -features identified in both centWave runs are reported. -The matrix columns are: -\describe{ -\item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} -\item{rt}{Retention time of the feature's midpoint.} -\item{rtmin}{Minimum retention time of the feature.} -\item{rtmax}{Maximum retention time of the feature.} -\item{into}{Integrated (original) intensity of the feature.} -\item{intb}{Per-feature baseline corrected integrated feature intensity.} -\item{maxo}{Maximum intensity of the feature.} -\item{sn}{Signal to noise ratio, defined as \code{(maxo - baseline)/sd}, -\code{sd} being the standard deviation of local chromatographic noise.} -\item{egauss}{RMSE of Gaussian fit.} -} -Additional columns for \code{verboseColumns = TRUE}: -\describe{ -\item{mu}{Gaussian parameter mu.} -\item{sigma}{Gaussian parameter sigma.} -\item{h}{Gaussian parameter h.} -\item{f}{Region number of the m/z ROI where the peak was localized.} -\item{dppm}{m/z deviation of mass trace across scanns in ppk.} -\item{scale}{Scale on which the feature was localized.} -\item{scpos}{Peak position found by wavelet analysis (scan number).} -\item{scmin}{Left peak limit found by wavelet analysis (scan number).} -\item{scmax}{Right peak limit found by wavelet analysis (scan numer).} -} -} -\description{ -The \code{do_detectFeatures_centWaveWithPredIsoROIs} performs a -two-step centWave based feature detection: features are identified using -centWave followed by a prediction of the location of the identified features' -isotopes in the mz-retention time space. These locations are fed as -\emph{regions of interest} (ROIs) to a subsequent centWave run. All non -overlapping features from these two feature detection runs are reported as -the final list of identified features. - -The \code{do_detectFeatures_centWaveAddPredIsoROIs} performs -centWave based feature detection based in regions of interest (ROIs) -representing predicted isotopes for the features submitted with argument -\code{features.}. The function returns a matrix with the identified features -consisting of all input features and features representing predicted isotopes -of these (if found by the centWave algorithm). -} -\details{ -For more details on the centWave algorithm see -\code{\link{centWave}}. -} -\author{ -Hendrik Treutler, Johannes Rainer -} -\seealso{ -Other core feature detection functions: \code{\link{do_detectFeatures_MSW}}, - \code{\link{do_detectFeatures_centWave}}, - \code{\link{do_detectFeatures_massifquant}}, - \code{\link{do_detectFeatures_matchedFilter}} -} - diff --git a/man/do_detectFeatures_centWave.Rd b/man/do_findChromPeaks_centWave.Rd similarity index 60% rename from man/do_detectFeatures_centWave.Rd rename to man/do_findChromPeaks_centWave.Rd index 954f5c7c9..eb9f3af5d 100644 --- a/man/do_detectFeatures_centWave.Rd +++ b/man/do_findChromPeaks_centWave.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_detectFeatures-functions.R -\name{do_detectFeatures_centWave} -\alias{do_detectFeatures_centWave} -\title{Core API function for centWave feature detection} +% Please edit documentation in R/do_findChromPeaks-functions.R +\name{do_findChromPeaks_centWave} +\alias{do_findChromPeaks_centWave} +\title{Core API function for centWave peak detection} \usage{ -do_detectFeatures_centWave(mz, int, scantime, valsPerSpect, ppm = 25, +do_findChromPeaks_centWave(mz, int, scantime, valsPerSpect, ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, fitgauss = FALSE, noise = 0, verboseColumns = FALSE, roiList = list(), @@ -23,26 +23,26 @@ spectra/scans of the data representing the retention time of each scan.} \item{valsPerSpect}{Numeric vector with the number of values for each spectrum.} -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} -\item{peakwidth}{numeric(2) with the expected approximate -feature/peak width in chromatographic space. Given as a range (min, max) +\item{peakwidth}{\code{numeric(2)} with the expected approximate +peak width in chromatographic space. Given as a range (min, max) in seconds.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{prefilter}{numeric(2): \code{c(k, I)} specifying the prefilter +\item{prefilter}{\code{numeric(2)}: \code{c(k, I)} specifying the prefilter step for the first analysis step (ROI detection). Mass traces are only retained if they contain at least \code{k} peaks with intensity \code{>= I}.} \item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} \item{integrate}{Integration method. For \code{integrate = 1} peak limits are found through descent on the mexican hat filtered data, for @@ -50,29 +50,30 @@ are found through descent on the mexican hat filtered data, for is more accurate but prone to noise, while the former is more robust, but less exact.} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} -\item{noise}{numeric(1) allowing to set a minimum intensity required +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity \code{< noise} are omitted from ROI detection).} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} \item{roiList}{An optional list of regions-of-interest (ROI) representing detected mass traces. If ROIs are submitted the first analysis step is -omitted and feature detection is performed on the submitted ROIs. Each -ROI is expected to have the following elements specified: +omitted and chromatographic peak detection is performed on the submitted +ROIs. Each ROI is expected to have the following elements specified: \code{scmin} (start scan index), \code{scmax} (end scan index), \code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} (number of scans), \code{intensity} (summed intensity). Each ROI should be represented by a \code{list} of elements or a single row \code{data.frame}.} -\item{firstBaselineCheck}{logical(1). If \code{TRUE} continuous +\item{firstBaselineCheck}{\code{logical(1)}. If \code{TRUE} continuous data within regions of interest is checked to be above the first baseline.} \item{roiScales}{Optional numeric vector with length equal to \code{roiList} @@ -80,17 +81,18 @@ defining the scale for each region of interest in \code{roiList} that should be used for the centWave-wavelets.} } \value{ -A matrix, each row representing an identified feature, with columns: +A matrix, each row representing an identified chromatographic peak, +with columns: \describe{ -\item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} -\item{rt}{Retention time of the feature's midpoint.} -\item{rtmin}{Minimum retention time of the feature.} -\item{rtmax}{Maximum retention time of the feature.} -\item{into}{Integrated (original) intensity of the feature.} -\item{intb}{Per-feature baseline corrected integrated feature intensity.} -\item{maxo}{Maximum intensity of the feature.} +\item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +\item{mzmin}{Minimum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} +\item{rt}{Retention time of the peak's midpoint.} +\item{rtmin}{Minimum retention time of the peak.} +\item{rtmax}{Maximum retention time of the peak.} +\item{into}{Integrated (original) intensity of the peak.} +\item{intb}{Per-peak baseline corrected integrated peak intensity.} +\item{maxo}{Maximum intensity of the peak.} \item{sn}{Signal to noise ratio, defined as \code{(maxo - baseline)/sd}, \code{sd} being the standard deviation of local chromatographic noise.} \item{egauss}{RMSE of Gaussian fit.} @@ -102,15 +104,16 @@ Additional columns for \code{verboseColumns = TRUE}: \item{h}{Gaussian parameter h.} \item{f}{Region number of the m/z ROI where the peak was localized.} \item{dppm}{m/z deviation of mass trace across scanns in ppk.} -\item{scale}{Scale on which the feature was localized.} +\item{scale}{Scale on which the peak was localized.} \item{scpos}{Peak position found by wavelet analysis (scan number).} \item{scmin}{Left peak limit found by wavelet analysis (scan number).} \item{scmax}{Right peak limit found by wavelet analysis (scan numer).} } } \description{ -This function performs peak density and wavelet based feature -detection for high resolution LC/MS data in centroid mode [Tautenhahn 2008]. +This function performs peak density and wavelet based +chromatographic peak detection for high resolution LC/MS data in centroid +mode [Tautenhahn 2008]. } \details{ This algorithm is most suitable for high resolution @@ -126,7 +129,7 @@ of interest are passed with the \code{roiList} parameter. The \emph{centWave} was designed to work on centroided mode, thus it is expected that such data is presented to the function. -This function exposes core feature detection functionality of +This function exposes core chromatographic peak detection functionality of the \emph{centWave} method. While this function can be called directly, users will generally call the corresponding method for the data object instead. @@ -137,7 +140,7 @@ library(faahKO) fs <- system.file('cdf/KO/ko15.CDF', package = "faahKO") xr <- xcmsRaw(fs, profstep = 0) -## Extracting the data from the xcmsRaw for do_detectFeatures_centWave +## Extracting the data from the xcmsRaw for do_findChromPeaks_centWave mzVals <- xr@env$mz intVals <- xr@env$intensity ## Define the values per spectrum: @@ -146,7 +149,7 @@ valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) ## Calling the function. We're using a large value for noise to speed up ## the call in the example performance - in a real use case we would either ## set the value to a reasonable value or use the default value. -res <- do_detectFeatures_centWave(mz = mzVals, int = intVals, +res <- do_findChromPeaks_centWave(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect, noise = 10000) head(res) } @@ -161,9 +164,9 @@ sensitive feature detection for high resolution LC/MS" \emph{BMC Bioinformatics} \seealso{ \code{\link{centWave}} for the standard user interface method. -Other core feature detection functions: \code{\link{do_detectFeatures_MSW}}, - \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}}, - \code{\link{do_detectFeatures_massifquant}}, - \code{\link{do_detectFeatures_matchedFilter}} +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}} } diff --git a/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd b/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd new file mode 100644 index 000000000..9e9f8877a --- /dev/null +++ b/man/do_findChromPeaks_centWaveWithPredIsoROIs.Rd @@ -0,0 +1,182 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/do_findChromPeaks-functions.R +\name{do_findChromPeaks_centWaveWithPredIsoROIs} +\alias{do_findChromPeaks_addPredIsoROIs} +\alias{do_findChromPeaks_centWaveWithPredIsoROIs} +\title{Core API function for two-step centWave peak detection with isotopes} +\usage{ +do_findChromPeaks_centWaveWithPredIsoROIs(mz, int, scantime, valsPerSpect, + ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), + mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, + fitgauss = FALSE, noise = 0, verboseColumns = FALSE, roiList = list(), + firstBaselineCheck = TRUE, roiScales = NULL, snthreshIsoROIs = 6.25, + maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, + polarity = "unknown") + +do_findChromPeaks_addPredIsoROIs(mz, int, scantime, valsPerSpect, ppm = 25, + peakwidth = c(20, 50), snthresh = 6.25, prefilter = c(3, 100), + mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, + fitgauss = FALSE, noise = 0, verboseColumns = FALSE, peaks. = NULL, + maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, + polarity = "unknown") +} +\arguments{ +\item{mz}{Numeric vector with the individual m/z values from all scans/ +spectra of one file/sample.} + +\item{int}{Numeric vector with the individual intensity values from all +scans/spectra of one file/sample.} + +\item{scantime}{Numeric vector of length equal to the number of +spectra/scans of the data representing the retention time of each scan.} + +\item{valsPerSpect}{Numeric vector with the number of values for each +spectrum.} + +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} + +\item{peakwidth}{\code{numeric(2)} with the expected approximate +peak width in chromatographic space. Given as a range (min, max) +in seconds.} + +\item{snthresh}{For \code{do_findChromPeaks_addPredIsoROIs}: +numeric(1) defining the signal to noise threshold for the centWave algorithm. +For \code{do_findChromPeaks_centWaveWithPredIsoROIs}: numeric(1) defining the +signal to noise threshold for the initial (first) centWave run.} + +\item{prefilter}{\code{numeric(2)}: \code{c(k, I)} specifying the prefilter +step for the first analysis step (ROI detection). Mass traces are only +retained if they contain at least \code{k} peaks with intensity \code{>= I}.} + +\item{mzCenterFun}{Name of the function to calculate the m/z center of the +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} + +\item{integrate}{Integration method. For \code{integrate = 1} peak limits +are found through descent on the mexican hat filtered data, for +\code{integrate = 2} the descent is done on the real data. The latter method +is more accurate but prone to noise, while the former is more robust, but +less exact.} + +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} + +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} + +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required +for centroids to be considered in the first analysis step (centroids with +intensity \code{< noise} are omitted from ROI detection).} + +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} + +\item{roiList}{An optional list of regions-of-interest (ROI) representing +detected mass traces. If ROIs are submitted the first analysis step is +omitted and chromatographic peak detection is performed on the submitted +ROIs. Each ROI is expected to have the following elements specified: +\code{scmin} (start scan index), \code{scmax} (end scan index), +\code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} +(number of scans), \code{intensity} (summed intensity). Each ROI should be +represented by a \code{list} of elements or a single row \code{data.frame}.} + +\item{firstBaselineCheck}{\code{logical(1)}. If \code{TRUE} continuous +data within regions of interest is checked to be above the first baseline.} + +\item{roiScales}{Optional numeric vector with length equal to \code{roiList} +defining the scale for each region of interest in \code{roiList} that should +be used for the centWave-wavelets.} + +\item{snthreshIsoROIs}{\code{numeric(1)} defining the signal to noise ratio +cutoff to be used in the second centWave run to identify peaks for predicted +isotope ROIs.} + +\item{maxCharge}{\code{integer(1)} defining the maximal isotope charge. +Isotopes will be defined for charges \code{1:maxCharge}.} + +\item{maxIso}{\code{integer(1)} defining the number of isotope peaks that +should be predicted for each peak identified in the first centWave run.} + +\item{mzIntervalExtension}{\code{logical(1)} whether the mz range for the +predicted isotope ROIs should be extended to increase detection of low +intensity peaks.} + +\item{polarity}{\code{character(1)} specifying the polarity of the data. +Currently not used, but has to be \code{"positive"}, \code{"negative"} or +\code{"unknown"} if provided.} + +\item{peaks.}{A matrix or \code{xcmsPeaks} object such as one returned by +a call to \code{link{do_findChromPeaks_centWave}} or +\code{link{findPeaks.centWave}} (both with \code{verboseColumns = TRUE}) +with the peaks for which isotopes should be predicted and used for an +additional peak detectoin using the centWave method. Required columns are: +\code{"mz"}, \code{"mzmin"}, \code{"mzmax"}, \code{"scmin"}, \code{"scmax"}, +\code{"scale"} and \code{"into"}.} +} +\value{ +A matrix, each row representing an identified chromatographic peak. All +non-overlapping peaks identified in both centWave runs are reported. +The matrix columns are: +\describe{ +\item{mz}{Intensity weighted mean of m/z values of the peaks across scans.} +\item{mzmin}{Minimum m/z of the peaks.} +\item{mzmax}{Maximum m/z of the peaks.} +\item{rt}{Retention time of the peak's midpoint.} +\item{rtmin}{Minimum retention time of the peak.} +\item{rtmax}{Maximum retention time of the peak.} +\item{into}{Integrated (original) intensity of the peak.} +\item{intb}{Per-peak baseline corrected integrated peak intensity.} +\item{maxo}{Maximum intensity of the peak.} +\item{sn}{Signal to noise ratio, defined as \code{(maxo - baseline)/sd}, +\code{sd} being the standard deviation of local chromatographic noise.} +\item{egauss}{RMSE of Gaussian fit.} +} +Additional columns for \code{verboseColumns = TRUE}: +\describe{ +\item{mu}{Gaussian parameter mu.} +\item{sigma}{Gaussian parameter sigma.} +\item{h}{Gaussian parameter h.} +\item{f}{Region number of the m/z ROI where the peak was localized.} +\item{dppm}{m/z deviation of mass trace across scanns in ppk.} +\item{scale}{Scale on which the peak was localized.} +\item{scpos}{Peak position found by wavelet analysis (scan number).} +\item{scmin}{Left peak limit found by wavelet analysis (scan number).} +\item{scmax}{Right peak limit found by wavelet analysis (scan numer).} +} +} +\description{ +The \code{do_findChromPeaks_centWaveWithPredIsoROIs} performs a +two-step centWave based peak detection: chromatographic peaks are identified +using centWave followed by a prediction of the location of the identified +peaks' isotopes in the mz-retention time space. These locations are fed as +\emph{regions of interest} (ROIs) to a subsequent centWave run. All non +overlapping peaks from these two peak detection runs are reported as +the final list of identified peaks. + +The \code{do_findChromPeaks_centWaveAddPredIsoROIs} performs +centWave based peak detection based in regions of interest (ROIs) +representing predicted isotopes for the peaks submitted with argument +\code{peaks.}. The function returns a matrix with the identified peaks +consisting of all input peaks and peaks representing predicted isotopes +of these (if found by the centWave algorithm). +} +\details{ +For more details on the centWave algorithm see +\code{\link{centWave}}. +} +\author{ +Hendrik Treutler, Johannes Rainer +} +\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}} +} + diff --git a/man/do_detectFeatures_massifquant.Rd b/man/do_findChromPeaks_massifquant.Rd similarity index 52% rename from man/do_detectFeatures_massifquant.Rd rename to man/do_findChromPeaks_massifquant.Rd index 49e02da7e..25507c993 100644 --- a/man/do_detectFeatures_massifquant.Rd +++ b/man/do_findChromPeaks_massifquant.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_detectFeatures-functions.R -\name{do_detectFeatures_massifquant} -\alias{do_detectFeatures_massifquant} -\title{Core API function for massifquant feature detection} +% Please edit documentation in R/do_findChromPeaks-functions.R +\name{do_findChromPeaks_massifquant} +\alias{do_findChromPeaks_massifquant} +\title{Core API function for massifquant peak detection} \usage{ -do_detectFeatures_massifquant(mz, int, scantime, valsPerSpect, ppm = 10, +do_findChromPeaks_massifquant(mz, int, scantime, valsPerSpect, ppm = 10, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1, mzdiff = -0.001, fitgauss = FALSE, noise = 0, verboseColumns = FALSE, @@ -24,26 +24,26 @@ spectra/scans of the data representing the retention time of each scan.} \item{valsPerSpect}{Numeric vector with the number of values for each spectrum.} -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} -\item{peakwidth}{numeric(2) with the expected approximate -feature/peak width in chromatographic space. Given as a range (min, max) +\item{peakwidth}{\code{numeric(2)} with the expected approximate +peak width in chromatographic space. Given as a range (min, max) in seconds.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{prefilter}{numeric(2): \code{c(k, I)} specifying the prefilter +\item{prefilter}{\code{numeric(2)}: \code{c(k, I)} specifying the prefilter step for the first analysis step (ROI detection). Mass traces are only retained if they contain at least \code{k} peaks with intensity \code{>= I}.} \item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} \item{integrate}{Integration method. For \code{integrate = 1} peak limits are found through descent on the mexican hat filtered data, for @@ -51,92 +51,94 @@ are found through descent on the mexican hat filtered data, for is more accurate but prone to noise, while the former is more robust, but less exact.} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} -\item{noise}{numeric(1) allowing to set a minimum intensity required +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity \code{< noise} are omitted from ROI detection).} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} -\item{criticalValue}{numeric(1). Suggested values: +\item{criticalValue}{\code{numeric(1)}. Suggested values: (\code{0.1-3.0}). This setting helps determine the the Kalman Filter prediciton margin of error. A real centroid belonging to a bonafide -feature must fall within the KF prediction margin of error. Much like +peak must fall within the KF prediction margin of error. Much like in the construction of a confidence interval, \code{criticalVal} loosely translates to be a multiplier of the standard error of the prediction -reported by the Kalman Filter. If the features in the XC-MS sample have +reported by the Kalman Filter. If the peak in the XC-MS sample have a small mass deviance in ppm error, a smaller critical value might be better and vice versa.} -\item{consecMissedLimit}{Integer: Suggested values: (\code{1,2,3}). While -a feature is in the proces of being detected by a Kalman Filter, the +\item{consecMissedLimit}{\code{integer(1)} Suggested values: (\code{1,2,3}). +While a peak is in the proces of being detected by a Kalman Filter, the Kalman Filter may not find a predicted centroid in every scan. After 1 or more consecutive failed predictions, this setting informs Massifquant -when to stop a Kalman Filter from following a candidate feature.} +when to stop a Kalman Filter from following a candidate peak.} -\item{unions}{Integer: set to \code{1} if apply t-test union on +\item{unions}{\code{integer(1)} set to \code{1} if apply t-test union on segmentation; set to \code{0} if no t-test to be applied on -chromatographically continous features sharing same m/z range. +chromatographically continous peaks sharing same m/z range. Explanation: With very few data points, sometimes a Kalman Filter stops -tracking a feature prematurely. Another Kalman Filter is instantiated +tracking a peak prematurely. Another Kalman Filter is instantiated and begins following the rest of the signal. Because tracking is done -backwards to forwards, this algorithmic defect leaves a real feature +backwards to forwards, this algorithmic defect leaves a real peak divided into two segments or more. With this option turned on, the -program identifies segmented features and combines them (merges them) +program identifies segmented peaks and combines them (merges them) into one with a two sample t-test. The potential danger of this option -is that some truly distinct features may be merged.} +is that some truly distinct peaks may be merged.} -\item{checkBack}{Integer: set to \code{1} if turned on; set to \code{0} -if turned off. The convergence of a Kalman Filter to a feature's precise -m/z mapping is very fast, but sometimes it incorporates erroneous centroids -as part of a feature (especially early on). The \code{scanBack} option is an -attempt to remove the occasional outlier that lies beyond the converged +\item{checkBack}{\code{integer(1)} set to \code{1} if turned on; set to +\code{0} if turned off. The convergence of a Kalman Filter to a peak's +precise m/z mapping is very fast, but sometimes it incorporates erroneous +centroids as part of a peak (especially early on). The \code{scanBack} option +is an attempt to remove the occasional outlier that lies beyond the converged bounds of the Kalman Filter. The option does not directly affect -identification of a feature because it is a postprocessing measure; it +identification of a peak because it is a postprocessing measure; it has not shown to be a extremely useful thus far and the default is set to being turned off.} -\item{withWave}{Logical: if \code{TRUE}, the features identified first +\item{withWave}{\code{logical(1)} if \code{TRUE}, the peaks identified first with Massifquant are subsequently filtered with the second step of the centWave algorithm, which includes wavelet estimation.} } \value{ -A matrix, each row representing an identified feature, with columns: +A matrix, each row representing an identified chromatographic peak, +with columns: \describe{ -\item{mz}{Intensity weighted mean of m/z values of the features across +\item{mz}{Intensity weighted mean of m/z values of the peaks across scans.} -\item{mzmin}{Minumum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} -\item{rtmin}{Minimum retention time of the feature.} -\item{rtmax}{Maximum retention time of the feature.} -\item{rt}{Retention time of the feature's midpoint.} -\item{into}{Integrated (original) intensity of the feature.} -\item{maxo}{Maximum intensity of the feature.} +\item{mzmin}{Minumum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} +\item{rtmin}{Minimum retention time of the peak.} +\item{rtmax}{Maximum retention time of the peak.} +\item{rt}{Retention time of the peak's midpoint.} +\item{into}{Integrated (original) intensity of the peak.} +\item{maxo}{Maximum intensity of the peak.} } If \code{withWave} is set to \code{TRUE}, the result is the same as -returned by the \code{\link{do_detectFeatures_centWave}} method. +returned by the \code{\link{do_findChromPeaks_centWave}} method. } \description{ -Massifquant is a Kalman filter (KF)-based feature -detection for XC-MS data in centroid mode. The identified features +Massifquant is a Kalman filter (KF)-based chromatographic peak +detection for XC-MS data in centroid mode. The identified peaks can be further refined with the \emph{centWave} method (see -\code{\link{do_detectFeatures_centWave}} for details on centWave) +\code{\link{do_findChromPeaks_centWave}} for details on centWave) by specifying \code{withWave = TRUE}. } \details{ This algorithm's performance has been tested rigorously on high resolution LC/{OrbiTrap, TOF}-MS data in centroid mode. -Simultaneous kalman filters identify features and calculate their +Simultaneous kalman filters identify peaks and calculate their area under the curve. The default parameters are set to operate on a complex LC-MS Orbitrap sample. Users will find it useful to do some simple exploratory data analysis to find out where to set a minimum -intensity, and identify how many scans an average feature spans. The +intensity, and identify how many scans an average peak spans. The \code{consecMissedLimit} parameter has yielded good performance on Orbitrap data when set to (\code{2}) and on TOF data it was found best to be at (\code{1}). This may change as the algorithm has yet to be @@ -161,8 +163,8 @@ intVals <- xraw@env$intensity ## Define the values per spectrum: valsPerSpect <- diff(c(xraw@scanindex, length(mzVals))) -## Perform the feature detection using massifquant -res <- do_detectFeatures_massifquant(mz = mzVals, int = intVals, +## Perform the peak detection using massifquant +res <- do_findChromPeaks_massifquant(mz = mzVals, int = intVals, scantime = xraw@scantime, valsPerSpect = valsPerSpect) head(res) } @@ -177,9 +179,9 @@ detection" \emph{Bioinformatics} 2014, 30(18):2636-43. \seealso{ \code{\link{massifquant}} for the standard user interface method. -Other core feature detection functions: \code{\link{do_detectFeatures_MSW}}, - \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}}, - \code{\link{do_detectFeatures_centWave}}, - \code{\link{do_detectFeatures_matchedFilter}} +Other core peak detection functions: \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}}, + \code{\link{do_findChromPeaks_centWave}}, + \code{\link{do_findChromPeaks_matchedFilter}}, + \code{\link{do_findPeaks_MSW}} } diff --git a/man/do_detectFeatures_matchedFilter.Rd b/man/do_findChromPeaks_matchedFilter.Rd similarity index 64% rename from man/do_detectFeatures_matchedFilter.Rd rename to man/do_findChromPeaks_matchedFilter.Rd index a0651d746..fbfdc6d47 100644 --- a/man/do_detectFeatures_matchedFilter.Rd +++ b/man/do_findChromPeaks_matchedFilter.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_detectFeatures-functions.R -\name{do_detectFeatures_matchedFilter} -\alias{do_detectFeatures_matchedFilter} -\title{Core API function for matchedFilter feature detection} +% Please edit documentation in R/do_findChromPeaks-functions.R +\name{do_findChromPeaks_matchedFilter} +\alias{do_findChromPeaks_matchedFilter} +\title{Core API function for matchedFilter peak detection} \usage{ -do_detectFeatures_matchedFilter(mz, int, scantime, valsPerSpect, +do_findChromPeaks_matchedFilter(mz, int, scantime, valsPerSpect, binSize = 0.1, impute = "none", baseValue, distance, fwhm = 30, sigma = fwhm/2.3548, max = 5, snthresh = 10, steps = 2, mzdiff = 0.8 - binSize * steps, index = FALSE) @@ -22,7 +22,7 @@ spectra/scans of the data representing the retention time of each scan.} \item{valsPerSpect}{Numeric vector with the number of values for each spectrum.} -\item{binSize}{numeric(1) specifying the width of the +\item{binSize}{\code{numeric(1)} specifying the width of the bins/slices in m/z dimension.} \item{impute}{Character string specifying the method to be used for missing @@ -39,57 +39,59 @@ is only considered for \code{method = "linbase"} and corresponds to the element of an empty element that should be considered for linear interpolation. See details section for more information.} -\item{fwhm}{numeric(1) specifying the full width at half maximum +\item{fwhm}{\code{numeric(1)} specifying the full width at half maximum of matched filtration gaussian model peak. Only used to calculate the actual sigma, see below.} -\item{sigma}{numeric(1) specifying the standard deviation (width) +\item{sigma}{\code{numeric(1)} specifying the standard deviation (width) of the matched filtration model peak.} -\item{max}{numeric(1) representing the maximum number of peaks +\item{max}{\code{numeric(1)} representing the maximum number of peaks that are expected/will be identified per slice.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{steps}{numeric(1) defining the number of bins to be +\item{steps}{\code{numeric(1)} defining the number of bins to be merged before filtration (i.e. the number of neighboring bins that will be joined to the slice in which filtration and peak detection will be performed).} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{index}{Logical specifying whether indicies should be returned instead +\item{index}{\code{logical(1)} specifying whether indicies should be returned instead of values for m/z and retention times.} } \value{ -A matrix, each row representing an identified feature, with columns: +A matrix, each row representing an identified chromatographic peak, +with columns: \describe{ -\item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} -\item{rt}{Retention time of the feature's midpoint.} -\item{rtmin}{Minimum retention time of the feature.} -\item{rtmax}{Maximum retention time of the feature.} -\item{into}{Integrated (original) intensity of the feature.} +\item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +\item{mzmin}{Minimum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} +\item{rt}{Retention time of the peak's midpoint.} +\item{rtmin}{Minimum retention time of the peak.} +\item{rtmax}{Maximum retention time of the peak.} +\item{into}{Integrated (original) intensity of the peak.} \item{intf}{Integrated intensity of the filtered peak.} -\item{maxo}{Maximum intensity of the feature.} +\item{maxo}{Maximum intensity of the peak.} \item{maxf}{Maximum intensity of the filtered peak.} -\item{i}{Rank of feature in merged EIC (\code{<= max}).} -\item{sn}{Signal to noise ratio of the feature} +\item{i}{Rank of peak in merged EIC (\code{<= max}).} +\item{sn}{Signal to noise ratio of the peak} } } \description{ -This function identifies features in the chromatographic +This function identifies peaks in the chromatographic time domain as described in [Smith 2006]. The intensity values are binned by cutting The LC/MS data into slices (bins) of a mass unit (\code{binSize} m/z) wide. Within each bin the maximal intensity is -selected. The feature detection is then performed in each bin by +selected. The peak detection is then performed in each bin by extending it based on the \code{steps} parameter to generate slices comprising bins \code{current_bin - steps +1} to \code{current_bin + steps - 1}. Each of these slices is then filtered with matched filtration using -a second-derative Gaussian as the model feature/peak shape. After filtration -features are detected using a signal-to-ration cut-off. For more details +a second-derative Gaussian as the model peak shape. After filtration +peaks are detected using a signal-to-ration cut-off. For more details and illustrations see [Smith 2006]. } \details{ @@ -102,7 +104,7 @@ For more details on binning and missing value imputation see \code{\link{binYonX}} and \code{\link{imputeLinInterpol}} methods. } \note{ -This function exposes core feature detection functionality of +This function exposes core peak detection functionality of the \emph{matchedFilter} method. While this function can be called directly, users will generally call the corresponding method for the data object instead (e.g. the \code{link{findPeaks.matchedFilter}} method). @@ -113,13 +115,13 @@ library(faahKO) fs <- system.file('cdf/KO/ko15.CDF', package = "faahKO") xr <- xcmsRaw(fs) -## Extracting the data from the xcmsRaw for do_detectFeatures_centWave +## Extracting the data from the xcmsRaw for do_findChromPeaks_centWave mzVals <- xr@env$mz intVals <- xr@env$intensity ## Define the values per spectrum: valsPerSpect <- diff(c(xr@scanindex, length(mzVals))) -res <- do_detectFeatures_matchedFilter(mz = mzVals, int = intVals, +res <- do_findChromPeaks_matchedFilter(mz = mzVals, int = intVals, scantime = xr@scantime, valsPerSpect = valsPerSpect) head(res) } @@ -137,9 +139,9 @@ Profiling Using Nonlinear Peak Alignment, Matching, and Identification" \code{\link{imputeLinInterpol}} for the interpolation of missing values. \code{\link{matchedFilter}} for the standard user interface method. -Other core feature detection functions: \code{\link{do_detectFeatures_MSW}}, - \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}}, - \code{\link{do_detectFeatures_centWave}}, - \code{\link{do_detectFeatures_massifquant}} +Other core peak detection functions: \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}}, + \code{\link{do_findChromPeaks_centWave}}, + \code{\link{do_findChromPeaks_massifquant}}, + \code{\link{do_findPeaks_MSW}} } diff --git a/man/do_detectFeatures_MSW.Rd b/man/do_findPeaks_MSW.Rd similarity index 53% rename from man/do_detectFeatures_MSW.Rd rename to man/do_findPeaks_MSW.Rd index d7aa32038..0ef56e9d9 100644 --- a/man/do_detectFeatures_MSW.Rd +++ b/man/do_findPeaks_MSW.Rd @@ -1,11 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_detectFeatures-functions.R -\name{do_detectFeatures_MSW} -\alias{do_detectFeatures_MSW} +% Please edit documentation in R/do_findChromPeaks-functions.R +\name{do_findPeaks_MSW} +\alias{do_findPeaks_MSW} \title{Core API function for single-spectrum non-chromatography MS data -feature detection} +peak detection} \usage{ -do_detectFeatures_MSW(mz, int, snthresh = 3, verboseColumns = FALSE, ...) +do_findPeaks_MSW(mz, int, snthresh = 3, verboseColumns = FALSE, ...) } \arguments{ \item{mz}{Numeric vector with the individual m/z values from all scans/ @@ -14,32 +14,32 @@ spectra of one file/sample.} \item{int}{Numeric vector with the individual intensity values from all scans/spectra of one file/sample.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} \item{...}{Additional parameters to be passed to the \code{\link[MassSpecWavelet]{peakDetectionCWT}} function.} } \value{ -A matrix, each row representing an identified feature, with columns: +A matrix, each row representing an identified peak, with columns: \describe{ -\item{mz}{m/z value of the feature at the centroid position.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} +\item{mz}{m/z value of the peak at the centroid position.} +\item{mzmin}{Minimum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} \item{rt}{Always \code{-1}.} \item{rtmin}{Always \code{-1}.} \item{rtmax}{Always \code{-1}.} -\item{into}{Integrated (original) intensity of the feature.} -\item{maxo}{Maximum intensity of the feature.} +\item{into}{Integrated (original) intensity of the peak.} +\item{maxo}{Maximum intensity of the peak.} \item{intf}{Always \code{NA}.} -\item{maxf}{Maximum MSW-filter response of the feature.} +\item{maxf}{Maximum MSW-filter response of the peak.} \item{sn}{Signal to noise ratio.} } } \description{ -This function performs feature detection in mass spectrometry +This function performs peak detection in mass spectrometry direct injection spectrum using a wavelet based algorithm. } \details{ @@ -57,9 +57,9 @@ Joachim Kutzera, Steffen Neumann, Johannes Rainer method. \code{\link[MassSpecWavelet]{peakDetectionCWT}} from the \code{MassSpecWavelet} package. -Other core feature detection functions: \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}}, - \code{\link{do_detectFeatures_centWave}}, - \code{\link{do_detectFeatures_massifquant}}, - \code{\link{do_detectFeatures_matchedFilter}} +Other core peak detection functions: \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}}, + \code{\link{do_findChromPeaks_centWave}}, + \code{\link{do_findChromPeaks_massifquant}}, + \code{\link{do_findChromPeaks_matchedFilter}} } diff --git a/man/do_groupChromPeaks_density.Rd b/man/do_groupChromPeaks_density.Rd new file mode 100644 index 000000000..60504ed87 --- /dev/null +++ b/man/do_groupChromPeaks_density.Rd @@ -0,0 +1,104 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/do_groupChromPeaks-functions.R +\name{do_groupChromPeaks_density} +\alias{do_groupChromPeaks_density} +\title{Core API function for peak density based chromatographic peak +grouping} +\usage{ +do_groupChromPeaks_density(peaks, sampleGroups, bw = 30, minFraction = 0.5, + minSamples = 1, binSize = 0.25, maxFeatures = 50) +} +\arguments{ +\item{peaks}{A \code{matrix} or \code{data.frame} with the mz values and +retention times of the identified chromatographic peaks in all samples of an +experiment. Required columns are \code{"mz"}, \code{"rt"} and +\code{"sample"}. The latter should contain \code{numeric} values representing +the index of the sample in which the peak was found.} + +\item{sampleGroups}{A vector of the same length than samples defining the +sample group assignments (i.e. which samples belong to which sample group).} + +\item{bw}{\code{numeric(1)} defining the bandwidth (standard deviation ot the +smoothing kernel) to be used. This argument is passed to the +\code{\link{density}} method.} + +\item{minFraction}{\code{numeric(1)} defining the minimum fraction of samples +in at least one sample group in which the peaks have to be present to be +considered as a peak group (feature).} + +\item{minSamples}{\code{numeric(1)} with the minimum number of samples in at +least one sample group in which the peaks have to be detected to be +considered a peak group (feature).} + +\item{binSize}{\code{numeric(1)} defining the size of the overlapping slices +in mz dimension.} + +\item{maxFeatures}{\code{numeric(1)} with the maximum number of peak groups +to be identified in a single mz slice.} +} +\value{ +A \code{list} with elements \code{"featureDefinitions"} and +\code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +representing a (mz-rt) feature (i.e. a peak group) with columns: +\describe{ +\item{"mzmed"}{median of the peaks' apex mz values.} +\item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +\item{"mzmax"}{largest mz value of all peaks' apex within the feature.} +\item{"rtmed"}{the median of the peaks' retention times.} +\item{"rtmin"}{the smallest retention time of the peaks in the group.} +\item{"rtmax"}{the largest retention time of the peaks in the group.} +\item{"npeaks"}{the total number of peaks assigned to the feature. +Note that this number can be larger than the total number of samples, since +multiple peaks from the same sample could be assigned to a feature.} +} +\code{"peakIndex"} is a \code{list} with the indices of all peaks in a +feature in the \code{peaks} input matrix. +} +\description{ +The \code{do_groupChromPeaks_density} function performs +chromatographic peak grouping based on the density (distribution) of peaks, +found in different samples, along the retention time axis in slices of +overlapping mz ranges. +} +\details{ +For overlapping slices along the mz dimension, the function +calculates the density distribution of identified peaks along the +retention time axis and groups peaks from the same or different samples +that are close to each other. See [Smith 2006] for more details. +} +\note{ +The default settings might not be appropriate for all LC/GC-MS setups, +especially the \code{bw} and \code{binSize} parameter should be adjusted +accordingly. +} +\examples{ +## Load the test data set +library(faahKO) +data(faahko) + +## Extract the matrix with the identified peaks from the xcmsSet: +fts <- peaks(faahko) + +## Perform the peak grouping with default settings: +res <- do_groupChromPeaks_density(fts, sampleGroups = sampclass(faahko)) + +## The feature definitions: +head(res$featureDefinitions) + +## The assignment of peaks from the input matrix to the features +head(res$peakIndex) +} +\author{ +Colin Smith, Johannes Rainer +} +\references{ +Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and +Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite +Profiling Using Nonlinear Peak Alignment, Matching, and Identification" +\emph{Anal. Chem.} 2006, 78:779-787. +} +\seealso{ +Other core peak grouping algorithms: \code{\link{do_groupChromPeaks_nearest}}, + \code{\link{do_groupPeaks_mzClust}} +} + diff --git a/man/do_groupChromPeaks_nearest.Rd b/man/do_groupChromPeaks_nearest.Rd new file mode 100644 index 000000000..44e2bce4d --- /dev/null +++ b/man/do_groupChromPeaks_nearest.Rd @@ -0,0 +1,63 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/do_groupChromPeaks-functions.R +\name{do_groupChromPeaks_nearest} +\alias{do_groupChromPeaks_nearest} +\title{Core API function for chromatic peak grouping using a nearest +neighbor approach} +\usage{ +do_groupChromPeaks_nearest(peaks, sampleGroups, mzVsRtBalance = 10, + absMz = 0.2, absRt = 15, kNN = 10) +} +\arguments{ +\item{peaks}{A \code{matrix} or \code{data.frame} with the mz values and +retention times of the identified chromatographic peaks in all samples of an +experiment. Required columns are \code{"mz"}, \code{"rt"} and +\code{"sample"}. The latter should contain \code{numeric} values representing +the index of the sample in which the peak was found.} + +\item{sampleGroups}{A vector of the same length than samples defining the +sample group assignments (i.e. which samples belong to which sample group).} + +\item{mzVsRtBalance}{\code{numeric(1)} representing the factor by which mz +values are multiplied before calculating the (euclician) distance between +two peaks.} + +\item{absMz}{\code{numeric(1)} maximum tolerated distance for mz values.} + +\item{absRt}{\code{numeric(1)} maximum tolerated distance for rt values.} + +\item{kNN}{\code{numeric(1)} representing the number of nearest neighbors +to check.} +} +\value{ +A \code{list} with elements \code{"featureDefinitions"} and +\code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +representing an (mz-rt) feature (i.e. peak group) with columns: +\describe{ +\item{"mzmed"}{median of the peaks' apex mz values.} +\item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +\item{"mzmax"}{largest mz value of all peaks' apex within the feature.} +\item{"rtmed"}{the median of the peaks' retention times.} +\item{"rtmin"}{the smallest retention time of the peaks in the feature.} +\item{"rtmax"}{the largest retention time of the peaks in the feature.} +\item{"npeaks"}{the total number of peaks assigned to the feature.} +} +\code{"peakIndex"} is a \code{list} with the indices of all peaks in a +feature in the \code{peaks} input matrix. +} +\description{ +The \code{do_groupChromPeaks_nearest} function groups peaks +across samples by creating a master peak list and assigning corresponding +peaks from all samples to each peak group (i.e. feature). The method is +inspired by the correspondence algorithm of mzMine [Katajamaa 2006]. +} +\references{ +Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for +processing and visualization of mass spectrometry based molecular profile +data. \emph{Bioinformatics} 2006, 22:634-636. +} +\seealso{ +Other core peak grouping algorithms: \code{\link{do_groupChromPeaks_density}}, + \code{\link{do_groupPeaks_mzClust}} +} + diff --git a/man/do_groupFeatures_density.Rd b/man/do_groupFeatures_density.Rd deleted file mode 100644 index c926444b4..000000000 --- a/man/do_groupFeatures_density.Rd +++ /dev/null @@ -1,104 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_groupFeatures-functions.R -\name{do_groupFeatures_density} -\alias{do_groupFeatures_density} -\title{Core API function for feature density based feature alignment} -\usage{ -do_groupFeatures_density(features, sampleGroups, bw = 30, minFraction = 0.5, - minSamples = 1, binSize = 0.25, maxFeatures = 50) -} -\arguments{ -\item{features}{A \code{matrix} or \code{data.frame} with the mz values and -retention times of the identified features in all samples of an experiment. -Required columns are \code{"mz"}, \code{"rt"} and \code{"sample"}. The latter -should contain \code{numeric} values representing the index of the sample in -which the feature was found.} - -\item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} - -\item{bw}{numeric(1) defining the bandwidth (standard deviation ot the -smoothing kernel) to be used. This argument is passed to the -\code{\link{density}} method.} - -\item{minFraction}{numeric(1) defining the minimum fraction of samples in at -least one sample group in which the features have to be present to be -considered as a feature group.} - -\item{minSamples}{numeric(1) with the minimum number of samples in at least -one sample group in which the features have to be detected to be considered -as a feature group.} - -\item{binSize}{numeric(1) defining the size of the overlapping slices in mz -dimension.} - -\item{maxFeatures}{numeric(1) with the maximum number of feature groups to -be identified in a single mz slice.} -} -\value{ -A \code{list} with elements \code{"featureGroups"} and -\code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -representing an aligned feature group and with columns: -\describe{ -\item{"mzmed"}{median of the features' apex mz values.} -\item{"mzmin"}{smallest mz value of all features' apex within the feature -group.} -\item{"mzmax"}{largest mz value of all features' apex within the feature -group.} -\item{"rtmed"}{the median of the features' retention times.} -\item{"rtmin"}{the smallest retention time of the features in the group.} -\item{"rtmax"}{the largest retention time of the features in the group.} -\item{"npeaks"}{the total number of features assigned to the feature group. -Note that this number can be larger than the total number of samples, since -multiple features from the same sample could be assigned to a group.} -} -\code{"featureIndex"} is a \code{list} with the indices of all features in a -feature group in the \code{features} input matrix. -} -\description{ -The \code{do_groupFeatures_density} function performs feature -alignment based on the density (distribution) of features, found in different -samples, along the retention time axis in slices of overlapping mz ranges. -} -\details{ -For overlapping slices along the mz dimension, the function -calculates the density distribution of identified features along the -retention time axis and groups features from the same or different samples -that are close to each other. See [Smith 2006] for more details. -} -\note{ -The default settings might not be appropriate for all LC/GC-MS setups, -especially the \code{bw} and \code{binSize} parameter should be adjusted -accordingly. -} -\examples{ -## Load the test data set -library(faahKO) -data(faahko) - -## Extract the matrix with the identified features from the xcmsSet: -fts <- peaks(faahko) - -## Perform the feature alignment with default settings: -res <- do_groupFeatures_density(fts, sampleGroups = sampclass(faahko)) - -## The feature groups: -head(res$featureGroups) - -## The assignment of features from the input matrix to the feature groups -head(res$featureIndex) -} -\author{ -Colin Smith, Johannes Rainer -} -\references{ -Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and -Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite -Profiling Using Nonlinear Peak Alignment, Matching, and Identification" -\emph{Anal. Chem.} 2006, 78:779-787. -} -\seealso{ -Other core feature alignment algorithms: \code{\link{do_groupFeatures_mzClust}}, - \code{\link{do_groupFeatures_nearest}} -} - diff --git a/man/do_groupFeatures_mzClust.Rd b/man/do_groupFeatures_mzClust.Rd deleted file mode 100644 index 0ddb37848..000000000 --- a/man/do_groupFeatures_mzClust.Rd +++ /dev/null @@ -1,67 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_groupFeatures-functions.R -\name{do_groupFeatures_mzClust} -\alias{do_groupFeatures_mzClust} -\title{Core API function for feature alignment using mzClust} -\usage{ -do_groupFeatures_mzClust(features, sampleGroups, ppm = 20, absMz = 0, - minFraction = 0.5, minSamples = 1) -} -\arguments{ -\item{features}{A \code{matrix} or \code{data.frame} with the mz values and -retention times of the identified features in all samples of an experiment. -Required columns are \code{"mz"}, \code{"rt"} and \code{"sample"}. The latter -should contain \code{numeric} values representing the index of the sample in -which the feature was found.} - -\item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} - -\item{ppm}{numeric(1) representing the relative mz error for the -clustering/grouping (in parts per million).} - -\item{absMz}{numeric(1) representing the absolute mz error for the clustering.} - -\item{minFraction}{numeric(1) defining the minimum fraction of samples in at -least one sample group in which the features have to be present to be -considered as a feature group.} - -\item{minSamples}{numeric(1) with the minimum number of samples in at least -one sample group in which the features have to be detected to be considered -as a feature group.} -} -\value{ -A \code{list} with elements \code{"featureGroups"} and -\code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -representing an aligned feature group and with columns: -\describe{ -\item{"mzmed"}{median of the features' apex mz values.} -\item{"mzmin"}{smallest mz value of all features' apex within the feature -group.} -\item{"mzmax"}{largest mz value of all features' apex within the feature -group.} -\item{"rtmed"}{always \code{-1}.} -\item{"rtmin"}{always \code{-1}.} -\item{"rtmax"}{always \code{-1}.} -\item{"npeaks"}{the total number of features assigned to the feature group. -Note that this number can be larger than the total number of samples, since -multiple features from the same sample could be assigned to a group.} -} -\code{"featureIndex"} is a \code{list} with the indices of all features in a -feature group in the \code{features} input matrix. -} -\description{ -The \code{do_groupFeatures_mzClust} function performs high -resolution alignment on single spectra samples. -} -\references{ -Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill -and David F. Grant\cr \emph{Alignment of high resolution mass spectra: -development of a heuristic approach for metabolomics}.\cr Metabolomics, -Vol. 2, No. 2, 75-83 (2006) -} -\seealso{ -Other core feature alignment algorithms: \code{\link{do_groupFeatures_density}}, - \code{\link{do_groupFeatures_nearest}} -} - diff --git a/man/do_groupFeatures_nearest.Rd b/man/do_groupFeatures_nearest.Rd deleted file mode 100644 index 4c22db7c6..000000000 --- a/man/do_groupFeatures_nearest.Rd +++ /dev/null @@ -1,62 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/do_groupFeatures-functions.R -\name{do_groupFeatures_nearest} -\alias{do_groupFeatures_nearest} -\title{Core API function for feature alignment using a nearest neighbor approach} -\usage{ -do_groupFeatures_nearest(features, sampleGroups, mzVsRtBalance = 10, - absMz = 0.2, absRt = 15, kNN = 10) -} -\arguments{ -\item{features}{A \code{matrix} or \code{data.frame} with the mz values and -retention times of the identified features in all samples of an experiment. -Required columns are \code{"mz"}, \code{"rt"} and \code{"sample"}. The latter -should contain \code{numeric} values representing the index of the sample in -which the feature was found.} - -\item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} - -\item{mzVsRtBalance}{numeric(1) representing the factor by which mz values are -multiplied before calculating the (euclician) distance between two features.} - -\item{absMz}{numeric(1) maximum tolerated distance for mz values.} - -\item{absRt}{numeric(1) maximum tolerated distance for rt values.} - -\item{kNN}{numeric(1) representing the number of nearest neighbors to check.} -} -\value{ -A \code{list} with elements \code{"featureGroups"} and -\code{"featureIndex"}. \code{"featureGroups"} is a \code{matrix}, each row -representing an aligned feature group and with columns: -\describe{ -\item{"mzmed"}{median of the features' apex mz values.} -\item{"mzmin"}{smallest mz value of all features' apex within the feature -group.} -\item{"mzmax"}{largest mz value of all features' apex within the feature -group.} -\item{"rtmed"}{the median of the features' retention times.} -\item{"rtmin"}{the smallest retention time of the features in the group.} -\item{"rtmax"}{the largest retention time of the features in the group.} -\item{"npeaks"}{the total number of features assigned to the feature group.} -} -\code{"featureIndex"} is a \code{list} with the indices of all features in a -feature group in the \code{features} input matrix. -} -\description{ -The \code{do_groupFeatures_nearest} function groups features -across samples by creating a master feature list and assigning corresponding -features from all samples to each feature group. The method is inspired by -the alignment algorithm of mzMine [Katajamaa 2006]. -} -\references{ -Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for -processing and visualization of mass spectrometry based molecular profile -data. \emph{Bioinformatics} 2006, 22:634-636. -} -\seealso{ -Other core feature alignment algorithms: \code{\link{do_groupFeatures_density}}, - \code{\link{do_groupFeatures_mzClust}} -} - diff --git a/man/do_groupPeaks_mzClust.Rd b/man/do_groupPeaks_mzClust.Rd new file mode 100644 index 000000000..864dec860 --- /dev/null +++ b/man/do_groupPeaks_mzClust.Rd @@ -0,0 +1,66 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/do_groupChromPeaks-functions.R +\name{do_groupPeaks_mzClust} +\alias{do_groupPeaks_mzClust} +\title{Core API function for peak grouping using mzClust} +\usage{ +do_groupPeaks_mzClust(peaks, sampleGroups, ppm = 20, absMz = 0, + minFraction = 0.5, minSamples = 1) +} +\arguments{ +\item{peaks}{A \code{matrix} or \code{data.frame} with the mz values and +retention times of the identified chromatographic peaks in all samples of an +experiment. Required columns are \code{"mz"}, \code{"rt"} and +\code{"sample"}. The latter should contain \code{numeric} values representing +the index of the sample in which the peak was found.} + +\item{sampleGroups}{A vector of the same length than samples defining the +sample group assignments (i.e. which samples belong to which sample group).} + +\item{ppm}{\code{numeric(1)} representing the relative mz error for the +clustering/grouping (in parts per million).} + +\item{absMz}{\code{numeric(1)} representing the absolute mz error for the +clustering.} + +\item{minFraction}{\code{numeric(1)} defining the minimum fraction of samples +in at least one sample group in which the peaks have to be present to be +considered as a peak group (feature).} + +\item{minSamples}{\code{numeric(1)} with the minimum number of samples in at +least one sample group in which the peaks have to be detected to be +considered a peak group (feature).} +} +\value{ +A \code{list} with elements \code{"featureDefinitions"} and +\code{"peakIndex"}. \code{"featureDefinitions"} is a \code{matrix}, each row +representing an (mz-rt) feature (i.e. peak group) with columns: +\describe{ +\item{"mzmed"}{median of the peaks' apex mz values.} +\item{"mzmin"}{smallest mz value of all peaks' apex within the feature.} +\item{"mzmax"}{largest mz value of all peaks' apex within the feature.} +\item{"rtmed"}{always \code{-1}.} +\item{"rtmin"}{always \code{-1}.} +\item{"rtmax"}{always \code{-1}.} +\item{"npeaks"}{the total number of peaks assigned to the feature. +Note that this number can be larger than the total number of samples, since +multiple peaks from the same sample could be assigned to a group.} +} +\code{"peakIndex"} is a \code{list} with the indices of all peaks in a +peak group in the \code{peaks} input matrix. +} +\description{ +The \code{do_groupPeaks_mzClust} function performs high +resolution correspondence on single spectra samples. +} +\references{ +Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill +and David F. Grant\cr \emph{Alignment of high resolution mass spectra: +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}} +} + diff --git a/man/featureDetection-centWave.Rd b/man/findChromPeaks-centWave.Rd similarity index 74% rename from man/featureDetection-centWave.Rd rename to man/findChromPeaks-centWave.Rd index 3c1cf44e6..4c7651779 100644 --- a/man/featureDetection-centWave.Rd +++ b/man/findChromPeaks-centWave.Rd @@ -1,13 +1,13 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R \docType{class} -\name{featureDetection-centWave} +\name{findChromPeaks-centWave} \alias{CentWaveParam} \alias{CentWaveParam-class} \alias{centWave} -\alias{detectFeatures,MSnExp,CentWaveParam-method} -\alias{detectFeatures,OnDiskMSnExp,CentWaveParam-method} -\alias{featureDetection-centWave} +\alias{findChromPeaks,MSnExp,CentWaveParam-method} +\alias{findChromPeaks,OnDiskMSnExp,CentWaveParam-method} +\alias{findChromPeaks-centWave} \alias{firstBaselineCheck} \alias{firstBaselineCheck,CentWaveParam-method} \alias{firstBaselineCheck<-} @@ -60,17 +60,17 @@ \alias{verboseColumns,CentWaveParam-method} \alias{verboseColumns<-} \alias{verboseColumns<-,CentWaveParam-method} -\title{Feature detection using the centWave method} +\title{Chromatographic peak detection using the centWave method} \usage{ CentWaveParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, mzdiff = -0.001, fitgauss = FALSE, noise = 0, verboseColumns = FALSE, roiList = list(), firstBaselineCheck = TRUE, roiScales = numeric()) -\S4method{detectFeatures}{OnDiskMSnExp,CentWaveParam}(object, param, +\S4method{findChromPeaks}{OnDiskMSnExp,CentWaveParam}(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") -\S4method{detectFeatures}{MSnExp,CentWaveParam}(object, param, +\S4method{findChromPeaks}{MSnExp,CentWaveParam}(object, param, BPPARAM = bpparam(), return.type = "list") \S4method{show}{CentWaveParam}(object) @@ -128,26 +128,26 @@ CentWaveParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, \S4method{roiScales}{CentWaveParam}(object) <- value } \arguments{ -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} -\item{peakwidth}{numeric(2) with the expected approximate -feature/peak width in chromatographic space. Given as a range (min, max) +\item{peakwidth}{\code{numeric(2)} with the expected approximate +peak width in chromatographic space. Given as a range (min, max) in seconds.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{prefilter}{numeric(2): \code{c(k, I)} specifying the prefilter +\item{prefilter}{\code{numeric(2)}: \code{c(k, I)} specifying the prefilter step for the first analysis step (ROI detection). Mass traces are only retained if they contain at least \code{k} peaks with intensity \code{>= I}.} \item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} \item{integrate}{Integration method. For \code{integrate = 1} peak limits are found through descent on the mexican hat filtered data, for @@ -155,36 +155,37 @@ are found through descent on the mexican hat filtered data, for is more accurate but prone to noise, while the former is more robust, but less exact.} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} -\item{noise}{numeric(1) allowing to set a minimum intensity required +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity \code{< noise} are omitted from ROI detection).} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} \item{roiList}{An optional list of regions-of-interest (ROI) representing detected mass traces. If ROIs are submitted the first analysis step is -omitted and feature detection is performed on the submitted ROIs. Each -ROI is expected to have the following elements specified: +omitted and chromatographic peak detection is performed on the submitted +ROIs. Each ROI is expected to have the following elements specified: \code{scmin} (start scan index), \code{scmax} (end scan index), \code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} (number of scans), \code{intensity} (summed intensity). Each ROI should be represented by a \code{list} of elements or a single row \code{data.frame}.} -\item{firstBaselineCheck}{logical(1). If \code{TRUE} continuous +\item{firstBaselineCheck}{\code{logical(1)}. If \code{TRUE} continuous data within regions of interest is checked to be above the first baseline.} \item{roiScales}{Optional numeric vector with length equal to \code{roiList} defining the scale for each region of interest in \code{roiList} that should be used for the centWave-wavelets.} -\item{object}{For \code{detectFeatures}: Either an +\item{object}{For \code{findChromPeaks}: Either an \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} object containing the MS- and all other experiment-relevant data. @@ -196,11 +197,11 @@ centWave algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. See documentation of the \code{BiocParallel} for more details. If parallel -processing is enables, feature detection is performed in parallel on several +processing is enables, peak detection is performed in parallel on several of the input samples.} \item{return.type}{Character specifying what type of object the method should -return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or \code{"xcmsSet"}.} \item{value}{The value for the slot.} @@ -209,34 +210,34 @@ return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or } \value{ The \code{CentWaveParam} function returns a \code{CentWaveParam} -class instance with all of the settings specified for feature detection by -the centWave method. +class instance with all of the settings specified for chromatographic peak +detection by the centWave method. -For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -\code{\link{XCMSnExp}} object with the results of the feature detection. +For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +\code{\link{XCMSnExp}} object with the results of the peak detection. If \code{return.type = "list"} a list of length equal to the number of -samples with matrices specifying the identified features/peaks. +samples with matrices specifying the identified peaks. If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -with the results of the feature detection. +with the results of the peak detection. } \description{ The centWave algorithm perform peak density and wavelet based -feature detection for high resolution LC/MS data in centroid +chromatographic peak detection for high resolution LC/MS data in centroid mode [Tautenhahn 2008]. -The \code{CentWaveParam} class allows to specify all settings for -a feature detection using the centWave method. Instances should be created -with the \code{CentWaveParam} constructor. +The \code{CentWaveParam} class allows to specify all settings +for a chromatographic peak detection using the centWave method. Instances +should be created with the \code{CentWaveParam} constructor. -The \code{detectFeatures,OnDiskMSnExp,CentWaveParam} method -performs feature detection using the \emph{centWave} algorithm on all -samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +The \code{detectChromPeaks,OnDiskMSnExp,CentWaveParam} method +performs chromatographic peak detection using the \emph{centWave} algorithm +on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. -The \code{detectFeatures,MSnExp,CentWaveParam} method performs -feature detection using the \emph{centWave} algorithm on all samples from +The \code{findChromPeaks,MSnExp,CentWaveParam} method performs +peak detection using the \emph{centWave} algorithm on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and intensity values of all spectra hence no additional data input from the original files is required. @@ -305,7 +306,7 @@ the version from the class. Slots values should exclusively be accessed \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{findPeaks}} methods. It supports feature detection on +\code{\link{findPeaks}} methods. It supports peak detection on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} objects (both defined in the \code{MSnbase} package). All of the settings to the centWave algorithm can be passed with a \code{CentWaveParam} object. @@ -320,7 +321,7 @@ cwp <- CentWaveParam(ppm = 20, noise = 10000) snthresh(cwp) <- 25 cwp -## Perform the feature detection using centWave on some of the files from the +## Perform the peak detection using centWave on some of the files from the ## faahKO package. Files are read using the readMSData2 from the MSnbase ## package library(faahKO) @@ -329,10 +330,9 @@ fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, full.names = TRUE) raw_data <- readMSData2(fls[1:2]) -## Perform the feature detection using the settings defined above. We're -## returning the results as an xcmsSet object. -res <- detectFeatures(raw_data, param = cwp, return.type = "xcmsSet") -head(peaks(res)) +## Perform the peak detection using the settings defined above. +res <- findChromPeaks(raw_data, param = cwp) +head(chromPeaks(res)) } \author{ Ralf Tautenhahn, Johannes Rainer @@ -343,16 +343,16 @@ sensitive feature detection for high resolution LC/MS" \emph{BMC Bioinformatics} 2008, 9:504 } \seealso{ -The \code{\link{do_detectFeatures_centWave}} core API function and +The \code{\link{do_findChromPeaks_centWave}} core API function and \code{\link{findPeaks.centWave}} for the old user interface. \code{\link{XCMSnExp}} for the object containing the results of -the feature detection. +the peak detection. -Other feature detection methods: \code{\link{detectFeatures}}, - \code{\link{featureDetection-MSW}}, - \code{\link{featureDetection-centWaveWithPredIsoROIs}}, - \code{\link{featureDetection-massifquant}}, - \code{\link{featureDetection-matchedFilter}} +Other peak detection methods: \code{\link{chromatographic-peak-detection}}, + \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, + \code{\link{findChromPeaks-massifquant}}, + \code{\link{findChromPeaks-matchedFilter}}, + \code{\link{findPeaks-MSW}} } diff --git a/man/featureDetection-centWaveWithPredIsoROIs.Rd b/man/findChromPeaks-centWaveWithPredIsoROIs.Rd similarity index 60% rename from man/featureDetection-centWaveWithPredIsoROIs.Rd rename to man/findChromPeaks-centWaveWithPredIsoROIs.Rd index 2a4f4e069..6dcfb64b4 100644 --- a/man/featureDetection-centWaveWithPredIsoROIs.Rd +++ b/man/findChromPeaks-centWaveWithPredIsoROIs.Rd @@ -1,13 +1,13 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R \docType{class} -\name{featureDetection-centWaveWithPredIsoROIs} +\name{findChromPeaks-centWaveWithPredIsoROIs} \alias{CentWavePredIsoParam} \alias{CentWavePredIsoParam-class} \alias{centWaveWithPredIsoROIs} -\alias{detectFeatures,MSnExp,CentWavePredIsoParam-method} -\alias{detectFeatures,OnDiskMSnExp,CentWavePredIsoParam-method} -\alias{featureDetection-centWaveWithPredIsoROIs} +\alias{findChromPeaks,MSnExp,CentWavePredIsoParam-method} +\alias{findChromPeaks,OnDiskMSnExp,CentWavePredIsoParam-method} +\alias{findChromPeaks-centWaveWithPredIsoROIs} \alias{maxCharge} \alias{maxCharge,CentWavePredIsoParam-method} \alias{maxCharge<-} @@ -28,7 +28,7 @@ \alias{snthreshIsoROIs,CentWavePredIsoParam-method} \alias{snthreshIsoROIs<-} \alias{snthreshIsoROIs<-,CentWavePredIsoParam-method} -\title{Two-step centWave feature detection considering also feature isotopes} +\title{Two-step centWave peak detection considering also isotopes} \usage{ CentWavePredIsoParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, @@ -37,10 +37,10 @@ CentWavePredIsoParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, snthreshIsoROIs = 6.25, maxCharge = 3, maxIso = 5, mzIntervalExtension = TRUE, polarity = "unknown") -\S4method{detectFeatures}{OnDiskMSnExp,CentWavePredIsoParam}(object, param, +\S4method{findChromPeaks}{OnDiskMSnExp,CentWavePredIsoParam}(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") -\S4method{detectFeatures}{MSnExp,CentWavePredIsoParam}(object, param, +\S4method{findChromPeaks}{MSnExp,CentWavePredIsoParam}(object, param, BPPARAM = bpparam(), return.type = "list") \S4method{show}{CentWavePredIsoParam}(object) @@ -66,26 +66,26 @@ CentWavePredIsoParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, \S4method{polarity}{CentWavePredIsoParam}(object) <- value } \arguments{ -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} -\item{peakwidth}{numeric(2) with the expected approximate -feature/peak width in chromatographic space. Given as a range (min, max) +\item{peakwidth}{\code{numeric(2)} with the expected approximate +peak width in chromatographic space. Given as a range (min, max) in seconds.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{prefilter}{numeric(2): \code{c(k, I)} specifying the prefilter +\item{prefilter}{\code{numeric(2)}: \code{c(k, I)} specifying the prefilter step for the first analysis step (ROI detection). Mass traces are only retained if they contain at least \code{k} peaks with intensity \code{>= I}.} \item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} \item{integrate}{Integration method. For \code{integrate = 1} peak limits are found through descent on the mexican hat filtered data, for @@ -93,53 +93,55 @@ are found through descent on the mexican hat filtered data, for is more accurate but prone to noise, while the former is more robust, but less exact.} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} -\item{noise}{numeric(1) allowing to set a minimum intensity required +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity \code{< noise} are omitted from ROI detection).} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} \item{roiList}{An optional list of regions-of-interest (ROI) representing detected mass traces. If ROIs are submitted the first analysis step is -omitted and feature detection is performed on the submitted ROIs. Each -ROI is expected to have the following elements specified: +omitted and chromatographic peak detection is performed on the submitted +ROIs. Each ROI is expected to have the following elements specified: \code{scmin} (start scan index), \code{scmax} (end scan index), \code{mzmin} (minimum m/z), \code{mzmax} (maximum m/z), \code{length} (number of scans), \code{intensity} (summed intensity). Each ROI should be represented by a \code{list} of elements or a single row \code{data.frame}.} -\item{firstBaselineCheck}{logical(1). If \code{TRUE} continuous +\item{firstBaselineCheck}{\code{logical(1)}. If \code{TRUE} continuous data within regions of interest is checked to be above the first baseline.} \item{roiScales}{Optional numeric vector with length equal to \code{roiList} defining the scale for each region of interest in \code{roiList} that should be used for the centWave-wavelets.} -\item{snthreshIsoROIs}{numeric(1) defining the signal to noise ratio cutoff -to be used in the second centWave run to identify features for predicted +\item{snthreshIsoROIs}{\code{numeric(1)} defining the signal to noise ratio +cutoff to be used in the second centWave run to identify peaks for predicted isotope ROIs.} -\item{maxCharge}{integer(1) defining the maximal isotope charge. Isotopes -will be defined for charges \code{1:maxCharge}.} +\item{maxCharge}{\code{integer(1)} defining the maximal isotope charge. +Isotopes will be defined for charges \code{1:maxCharge}.} -\item{maxIso}{integer(1) defining the number of isotope peaks that should be -predicted for each feature identified in the first centWave run.} +\item{maxIso}{\code{integer(1)} defining the number of isotope peaks that +should be predicted for each peak identified in the first centWave run.} -\item{mzIntervalExtension}{logical(1) whether the mz range for the predicted -isotope ROIs should be extended to increase detection of low intensity peaks.} +\item{mzIntervalExtension}{\code{logical(1)} whether the mz range for the +predicted isotope ROIs should be extended to increase detection of low +intensity peaks.} -\item{polarity}{character(1) specifying the polarity of the data. Currently -not used, but has to be \code{"positive"}, \code{"negative"} or +\item{polarity}{\code{character(1)} specifying the polarity of the data. +Currently not used, but has to be \code{"positive"}, \code{"negative"} or \code{"unknown"} if provided.} -\item{object}{For \code{detectFeatures}: Either an +\item{object}{For \code{findChromPeaks}: Either an \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} object containing the MS- and all other experiment-relevant data. @@ -151,11 +153,11 @@ centWave algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. See documentation of the \code{BiocParallel} for more details. If parallel -processing is enables, feature detection is performed in parallel on several +processing is enables, peak detection is performed in parallel on several of the input samples.} \item{return.type}{Character specifying what type of object the method should -return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or \code{"xcmsSet"}.} \item{value}{The value for the slot.} @@ -163,40 +165,40 @@ return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or \value{ The \code{CentWavePredIsoParam} function returns a \code{CentWavePredIsoParam} class instance with all of the settings -specified for the two-step centWave-based feature detection considering also -feature isotopes. +specified for the two-step centWave-based peak detection considering also +isotopes. -For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -\code{\link{XCMSnExp}} object with the results of the feature detection. +For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +\code{\link{XCMSnExp}} object with the results of the peak detection. If \code{return.type = "list"} a list of length equal to the number of -samples with matrices specifying the identified features/peaks. +samples with matrices specifying the identified peaks. If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -with the results of the feature detection. +with the results of the peak detection. } \description{ -This method performs a two-step centWave-based feature -detection: in a first centWave run features are identified for which then +This method performs a two-step centWave-based chromatographic +peak detection: in a first centWave run peaks are identified for which then the location of their potential isotopes in the mz-retention time is predicted. A second centWave run is then performed on these -\emph{regions of interest} (ROIs). The final list of features comprises all -non-overlapping features from both centWave runs. +\emph{regions of interest} (ROIs). The final list of chromatographic peaks +comprises all non-overlapping peaks from both centWave runs. The \code{CentWavePredIsoParam} class allows to specify all -settings for the two-step centWave-based feature detection considering also -predicted isotopes of features identified in the first centWave run. +settings for the two-step centWave-based peak detection considering also +predicted isotopes of peaks identified in the first centWave run. Instances should be created with the \code{CentWavePredIsoParam} constructor. See also the documentation of the \code{\link{CentWaveParam}} for all methods and arguments this class inherits. -The \code{detectFeatures,OnDiskMSnExp,CentWavePredIsoParam} method -performs a two-step centWave-based feature detection on all samples from an -\code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. +The \code{findChromPeaks,OnDiskMSnExp,CentWavePredIsoParam} method +performs a two-step centWave-based chromatographic peak detection on all +samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +\code{\link[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. -The \code{detectFeatures,MSnExp,CentWavePredIsoParam} method -performs a two-step centWave-based feature detection on all samples from +The \code{findChromPeaks,MSnExp,CentWavePredIsoParam} method +performs a two-step centWave-based peak detection on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and intensity values of all spectra hence no additional data input from the original files is required. @@ -234,10 +236,10 @@ the version from the class. Slots values should exclusively be accessed \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{findPeaks}} methods. It supports feature detection on -\code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +\code{\link{findPeaks}} methods. It supports chromatographic peak detection +on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} objects (both defined in the \code{MSnbase} package). All of the settings -to the centWave algorithm can be passed with a \code{CentWaveParam} object. +to the algorithm can be passed with a \code{CentWavePredIsoParam} object. } \examples{ @@ -252,18 +254,18 @@ p Hendrik Treutler, Johannes Rainer } \seealso{ -The \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}} core +The \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}} core API function and \code{\link{findPeaks.centWave}} for the old user interface. \code{\link{CentWaveParam}} for the class the \code{CentWavePredIsoParam} extends. \code{\link{XCMSnExp}} for the object containing the results of -the feature detection. +the peak detection. -Other feature detection methods: \code{\link{detectFeatures}}, - \code{\link{featureDetection-MSW}}, - \code{\link{featureDetection-centWave}}, - \code{\link{featureDetection-massifquant}}, - \code{\link{featureDetection-matchedFilter}} +Other peak detection methods: \code{\link{chromatographic-peak-detection}}, + \code{\link{findChromPeaks-centWave}}, + \code{\link{findChromPeaks-massifquant}}, + \code{\link{findChromPeaks-matchedFilter}}, + \code{\link{findPeaks-MSW}} } diff --git a/man/featureDetection-massifquant.Rd b/man/findChromPeaks-massifquant.Rd similarity index 66% rename from man/featureDetection-massifquant.Rd rename to man/findChromPeaks-massifquant.Rd index 590b9da1a..2ab109bd5 100644 --- a/man/featureDetection-massifquant.Rd +++ b/man/findChromPeaks-massifquant.Rd @@ -1,7 +1,7 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R \docType{class} -\name{featureDetection-massifquant} +\name{findChromPeaks-massifquant} \alias{MassifquantParam} \alias{MassifquantParam-class} \alias{checkBack} @@ -16,9 +16,9 @@ \alias{criticalValue,MassifquantParam-method} \alias{criticalValue<-} \alias{criticalValue<-,MassifquantParam-method} -\alias{detectFeatures,MSnExp,MassifquantParam-method} -\alias{detectFeatures,OnDiskMSnExp,MassifquantParam-method} -\alias{featureDetection-massifquant} +\alias{findChromPeaks,MSnExp,MassifquantParam-method} +\alias{findChromPeaks,OnDiskMSnExp,MassifquantParam-method} +\alias{findChromPeaks-massifquant} \alias{fitgauss,MassifquantParam-method} \alias{fitgauss<-,MassifquantParam-method} \alias{integrate,MassifquantParam-method} @@ -49,7 +49,7 @@ \alias{withWave,MassifquantParam-method} \alias{withWave<-} \alias{withWave<-,MassifquantParam-method} -\title{Feature detection using the massifquant method} +\title{Chromatographic peak detection using the massifquant method} \usage{ MassifquantParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, prefilter = c(3, 100), mzCenterFun = "wMean", integrate = 1L, @@ -57,10 +57,10 @@ MassifquantParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, criticalValue = 1.125, consecMissedLimit = 2, unions = 1, checkBack = 0, withWave = FALSE) -\S4method{detectFeatures}{OnDiskMSnExp,MassifquantParam}(object, param, +\S4method{findChromPeaks}{OnDiskMSnExp,MassifquantParam}(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") -\S4method{detectFeatures}{MSnExp,MassifquantParam}(object, param, +\S4method{findChromPeaks}{MSnExp,MassifquantParam}(object, param, BPPARAM = bpparam(), return.type = "list") \S4method{show}{MassifquantParam}(object) @@ -126,29 +126,29 @@ MassifquantParam(ppm = 25, peakwidth = c(20, 50), snthresh = 10, \S4method{withWave}{MassifquantParam}(object) <- value } \arguments{ -\item{ppm}{Maximal tolerated m/z deviation in consecutive scans in parts -per million (ppm).} +\item{ppm}{\code{numeric(1)} defining the maximal tolerated m/z deviation in +consecutive scans in parts per million (ppm) for the initial ROI definition.} -\item{peakwidth}{numeric(2). Only the first element is used by -massifquant, which specifices the minimum feature length in time scans. +\item{peakwidth}{\code{numeric(2)}. Only the first element is used by +massifquant, which specifices the minimum peak length in time scans. For \code{withWave = TRUE} the second argument represents the maximum -feature length subject to being greater than the mininum feature length -(see also documentation of \code{\link{do_detectFeatures_centWave}}).} +peak length subject to being greater than the mininum peak length +(see also documentation of \code{\link{do_findChromPeaks_centWave}}).} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{prefilter}{numeric(2). The first argument is only used -if (\code{withWave = TRUE}); see \code{\link{do_detectFeatures_centWave}} +\item{prefilter}{\code{numeric(2)}. The first argument is only used +if (\code{withWave = TRUE}); see \code{\link{findChromPeaks-centWave}} for details. The second argument specifies the minimum threshold for the -maximum intensity of a feature that must be met.} +maximum intensity of a chromatographic peak that must be met.} \item{mzCenterFun}{Name of the function to calculate the m/z center of the -feature. Allowed are: \code{"wMean"}: intensity weighted mean of the feature's -m/z values, \code{"mean"}: mean of the feature's m/z values, \code{"apex"}: -use the m/z value at the peak apex, \code{"wMeanApex3"}: intensity weighted -mean of the m/z value at the peak apex and the m/z values left and right of -it and \code{"meanApex3"}: mean of the m/z value of the peak apex and the -m/z values left and right of it.} +chromatographic peak. Allowed are: \code{"wMean"}: intensity weighted mean of +the peak's m/z values, \code{"mean"}: mean of the peak's m/z values, +\code{"apex"}: use the m/z value at the peak apex, \code{"wMeanApex3"}: +intensity weighted mean of the m/z value at the peak apex and the m/z values +left and right of it and \code{"meanApex3"}: mean of the m/z value of the +peak apex and the m/z values left and right of it.} \item{integrate}{Integration method. For \code{integrate = 1} peak limits are found through descent on the mexican hat filtered data, for @@ -156,62 +156,63 @@ are found through descent on the mexican hat filtered data, for is more accurate but prone to noise, while the former is more robust, but less exact.} -\item{mzdiff}{Numeric representing the minimum difference in m/z dimension -for peaks with overlapping retention times; can be negatove to allow overlap.} +\item{mzdiff}{\code{numeric(1)} representing the minimum difference in m/z +dimension for peaks with overlapping retention times; can be negatove to +allow overlap.} -\item{fitgauss}{Logical whether or not a Gaussian should be fitted to each -peak.} +\item{fitgauss}{\code{logical(1)} whether or not a Gaussian should be fitted +to each peak.} -\item{noise}{numeric(1) allowing to set a minimum intensity required +\item{noise}{\code{numeric(1)} allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity \code{< noise} are omitted from ROI detection).} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} -\item{criticalValue}{numeric(1). Suggested values: +\item{criticalValue}{\code{numeric(1)}. Suggested values: (\code{0.1-3.0}). This setting helps determine the the Kalman Filter prediciton margin of error. A real centroid belonging to a bonafide -feature must fall within the KF prediction margin of error. Much like +peak must fall within the KF prediction margin of error. Much like in the construction of a confidence interval, \code{criticalVal} loosely translates to be a multiplier of the standard error of the prediction -reported by the Kalman Filter. If the features in the XC-MS sample have +reported by the Kalman Filter. If the peak in the XC-MS sample have a small mass deviance in ppm error, a smaller critical value might be better and vice versa.} -\item{consecMissedLimit}{Integer: Suggested values: (\code{1,2,3}). While -a feature is in the proces of being detected by a Kalman Filter, the +\item{consecMissedLimit}{\code{integer(1)} Suggested values: (\code{1,2,3}). +While a peak is in the proces of being detected by a Kalman Filter, the Kalman Filter may not find a predicted centroid in every scan. After 1 or more consecutive failed predictions, this setting informs Massifquant -when to stop a Kalman Filter from following a candidate feature.} +when to stop a Kalman Filter from following a candidate peak.} -\item{unions}{Integer: set to \code{1} if apply t-test union on +\item{unions}{\code{integer(1)} set to \code{1} if apply t-test union on segmentation; set to \code{0} if no t-test to be applied on -chromatographically continous features sharing same m/z range. +chromatographically continous peaks sharing same m/z range. Explanation: With very few data points, sometimes a Kalman Filter stops -tracking a feature prematurely. Another Kalman Filter is instantiated +tracking a peak prematurely. Another Kalman Filter is instantiated and begins following the rest of the signal. Because tracking is done -backwards to forwards, this algorithmic defect leaves a real feature +backwards to forwards, this algorithmic defect leaves a real peak divided into two segments or more. With this option turned on, the -program identifies segmented features and combines them (merges them) +program identifies segmented peaks and combines them (merges them) into one with a two sample t-test. The potential danger of this option -is that some truly distinct features may be merged.} +is that some truly distinct peaks may be merged.} -\item{checkBack}{Integer: set to \code{1} if turned on; set to \code{0} -if turned off. The convergence of a Kalman Filter to a feature's precise -m/z mapping is very fast, but sometimes it incorporates erroneous centroids -as part of a feature (especially early on). The \code{scanBack} option is an -attempt to remove the occasional outlier that lies beyond the converged +\item{checkBack}{\code{integer(1)} set to \code{1} if turned on; set to +\code{0} if turned off. The convergence of a Kalman Filter to a peak's +precise m/z mapping is very fast, but sometimes it incorporates erroneous +centroids as part of a peak (especially early on). The \code{scanBack} option +is an attempt to remove the occasional outlier that lies beyond the converged bounds of the Kalman Filter. The option does not directly affect -identification of a feature because it is a postprocessing measure; it +identification of a peak because it is a postprocessing measure; it has not shown to be a extremely useful thus far and the default is set to being turned off.} -\item{withWave}{Logical: if \code{TRUE}, the features identified first +\item{withWave}{\code{logical(1)} if \code{TRUE}, the peaks identified first with Massifquant are subsequently filtered with the second step of the centWave algorithm, which includes wavelet estimation.} -\item{object}{For \code{detectFeatures}: Either an +\item{object}{For \code{findChromPeaks}: Either an \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} object containing the MS- and all other experiment-relevant data. @@ -223,11 +224,11 @@ the massifquant algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. See documentation of the \code{BiocParallel} for more details. If parallel -processing is enables, feature detection is performed in parallel on several +processing is enables, peak detection is performed in parallel on several of the input samples.} \item{return.type}{Character specifying what type of object the method should -return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or \code{"xcmsSet"}.} \item{value}{The value for the slot.} @@ -236,39 +237,39 @@ return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or } \value{ The \code{MassifquantParam} function returns a \code{MassifquantParam} -class instance with all of the settings specified for feature detection by -the centWave method. +class instance with all of the settings specified for chromatographic peak +detection by the \emph{massifquant} method. -For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -\code{\link{XCMSnExp}} object with the results of the feature detection. +For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +\code{\link{XCMSnExp}} object with the results of the peak detection. If \code{return.type = "list"} a list of length equal to the number of -samples with matrices specifying the identified features/peaks. +samples with matrices specifying the identified peaks. If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -with the results of the feature detection. +with the results of the peak detection. } \description{ -Massifquant is a Kalman filter (KF)-based feature -detection for XC-MS data in centroid mode. The identified features +Massifquant is a Kalman filter (KF)-based chromatographic peak +detection for XC-MS data in centroid mode. The identified peaks can be further refined with the \emph{centWave} method (see -\code{\link{do_detectFeatures_centWave}} for details on centWave) +\code{\link{findChromPeaks-centWave}} for details on centWave) by specifying \code{withWave = TRUE}. The \code{MassifquantParam} class allows to specify all -settings for a feature detection using the massifquant method eventually in -combination with the centWave algorithm. Instances should be created with -the \code{MassifquantParam} constructor. +settings for a chromatographic peak detection using the massifquant method +eventually in combination with the centWave algorithm. Instances should be +created with the \code{MassifquantParam} constructor. -The \code{detectFeatures,OnDiskMSnExp,MassifquantParam} -method performs feature detection using the \emph{massifquant} algorithm -on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. +The \code{findChromPeaks,OnDiskMSnExp,MassifquantParam} +method performs chromatographic peak detection using the \emph{massifquant} +algorithm on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. -The \code{detectFeatures,MSnExp,MassifquantParam} method -performs feature detection using the \emph{massifquant} method on all -samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain -mz and intensity values of all spectra hence no additional +The \code{findChromPeaks,MSnExp,MassifquantParam} method +performs chromatographic peak detection using the \emph{massifquant} method +on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects +contain mz and intensity values of all spectra hence no additional data input from the original files is required. \code{ppm},\code{ppm<-}: getter and setter for the \code{ppm} @@ -319,11 +320,11 @@ setter for the \code{withWave} slot of the object. \details{ This algorithm's performance has been tested rigorously on high resolution LC/{OrbiTrap, TOF}-MS data in centroid mode. -Simultaneous kalman filters identify features and calculate their -area under the curve. The default parameters are set to operate on +Simultaneous kalman filters identify chromatographic peaks and calculate +their area under the curve. The default parameters are set to operate on a complex LC-MS Orbitrap sample. Users will find it useful to do some simple exploratory data analysis to find out where to set a minimum -intensity, and identify how many scans an average feature spans. The +intensity, and identify how many scans an average peak spans. The \code{consecMissedLimit} parameter has yielded good performance on Orbitrap data when set to (\code{2}) and on TOF data it was found best to be at (\code{1}). This may change as the algorithm has yet to be @@ -349,8 +350,8 @@ the version from the class. Slots values should exclusively be accessed \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{findPeaks}} methods. It supports feature detection on -\code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +\code{\link{findPeaks}} methods. It supports chromatographic peak detection +on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} objects (both defined in the \code{MSnbase} package). All of the settings to the massifquant and centWave algorithm can be passed with a \code{MassifquantParam} object. @@ -363,7 +364,7 @@ mqp <- MassifquantParam() snthresh(mqp) <- 30 mqp -## Perform the feature detection using massifquant on the files from the +## Perform the peak detection using massifquant on the files from the ## faahKO package. Files are read using the readMSData2 from the MSnbase ## package library(faahKO) @@ -371,10 +372,9 @@ library(MSnbase) fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, full.names = TRUE) raw_data <- readMSData2(fls[1:2]) -## Perform the feature detection using the settings defined above. We're -## returning the results as an xcmsSet object. -res <- detectFeatures(raw_data, param = mqp, return.type = "xcmsSet") -head(peaks(res)) +## Perform the peak detection using the settings defined above. +res <- findChromPeaks(raw_data, param = mqp) +head(chromPeaks(res)) } \author{ Christopher Conley, Johannes Rainer @@ -385,16 +385,16 @@ Conley CJ, Smith R, Torgrip RJ, Taylor RM, Tautenhahn R and Prince JT detection" \emph{Bioinformatics} 2014, 30(18):2636-43. } \seealso{ -The \code{\link{do_detectFeatures_massifquant}} core API function +The \code{\link{do_findChromPeaks_massifquant}} core API function and \code{\link{findPeaks.massifquant}} for the old user interface. \code{\link{XCMSnExp}} for the object containing the results of -the feature detection. +the peak detection. -Other feature detection methods: \code{\link{detectFeatures}}, - \code{\link{featureDetection-MSW}}, - \code{\link{featureDetection-centWaveWithPredIsoROIs}}, - \code{\link{featureDetection-centWave}}, - \code{\link{featureDetection-matchedFilter}} +Other peak detection methods: \code{\link{chromatographic-peak-detection}}, + \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, + \code{\link{findChromPeaks-centWave}}, + \code{\link{findChromPeaks-matchedFilter}}, + \code{\link{findPeaks-MSW}} } diff --git a/man/featureDetection-matchedFilter.Rd b/man/findChromPeaks-matchedFilter.Rd similarity index 75% rename from man/featureDetection-matchedFilter.Rd rename to man/findChromPeaks-matchedFilter.Rd index dcdf15f48..1e2c1d925 100644 --- a/man/featureDetection-matchedFilter.Rd +++ b/man/findChromPeaks-matchedFilter.Rd @@ -1,7 +1,7 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R \docType{class} -\name{featureDetection-matchedFilter} +\name{findChromPeaks-matchedFilter} \alias{MatchedFilterParam} \alias{MatchedFilterParam-class} \alias{baseValue} @@ -12,13 +12,13 @@ \alias{binSize,MatchedFilterParam-method} \alias{binSize<-} \alias{binSize<-,MatchedFilterParam-method} -\alias{detectFeatures,MSnExp,MatchedFilterParam-method} -\alias{detectFeatures,OnDiskMSnExp,MatchedFilterParam-method} \alias{distance} \alias{distance,MatchedFilterParam-method} \alias{distance<-} \alias{distance<-,MatchedFilterParam-method} -\alias{featureDetection-matchedFilter} +\alias{findChromPeaks,MSnExp,MatchedFilterParam-method} +\alias{findChromPeaks,OnDiskMSnExp,MatchedFilterParam-method} +\alias{findChromPeaks-matchedFilter} \alias{fwhm} \alias{fwhm,MatchedFilterParam-method} \alias{fwhm<-} @@ -54,10 +54,10 @@ MatchedFilterParam(binSize = 0.1, impute = "none", baseValue = numeric(), snthresh = 10, steps = 2, mzdiff = 0.8 - binSize * steps, index = FALSE) -\S4method{detectFeatures}{OnDiskMSnExp,MatchedFilterParam}(object, param, +\S4method{findChromPeaks}{OnDiskMSnExp,MatchedFilterParam}(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") -\S4method{detectFeatures}{MSnExp,MatchedFilterParam}(object, param, +\S4method{findChromPeaks}{MSnExp,MatchedFilterParam}(object, param, BPPARAM = bpparam(), return.type = "list") \S4method{show}{MatchedFilterParam}(object) @@ -107,7 +107,7 @@ MatchedFilterParam(binSize = 0.1, impute = "none", baseValue = numeric(), \S4method{index}{MatchedFilterParam}(object) <- value } \arguments{ -\item{binSize}{numeric(1) specifying the width of the +\item{binSize}{\code{numeric(1)} specifying the width of the bins/slices in m/z dimension.} \item{impute}{Character string specifying the method to be used for missing @@ -124,31 +124,31 @@ is only considered for \code{method = "linbase"} and corresponds to the element of an empty element that should be considered for linear interpolation. See details section for more information.} -\item{fwhm}{numeric(1) specifying the full width at half maximum +\item{fwhm}{\code{numeric(1)} specifying the full width at half maximum of matched filtration gaussian model peak. Only used to calculate the actual sigma, see below.} -\item{sigma}{numeric(1) specifying the standard deviation (width) +\item{sigma}{\code{numeric(1)} specifying the standard deviation (width) of the matched filtration model peak.} -\item{max}{numeric(1) representing the maximum number of peaks +\item{max}{\code{numeric(1)} representing the maximum number of peaks that are expected/will be identified per slice.} -\item{snthresh}{numeric(1) defining the signal to noise cutoff -to be used in the feature detection step.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise cutoff +to be used in the chromatographic peak detection step.} -\item{steps}{numeric(1) defining the number of bins to be +\item{steps}{\code{numeric(1)} defining the number of bins to be merged before filtration (i.e. the number of neighboring bins that will be joined to the slice in which filtration and peak detection will be performed).} -\item{mzdiff}{numeric(1) defining the minimum difference +\item{mzdiff}{\code{numeric(1)} defining the minimum difference in m/z for peaks with overlapping retention times} -\item{index}{Logical specifying whether indicies should be returned instead +\item{index}{\code{logical(1)} specifying whether indicies should be returned instead of values for m/z and retention times.} -\item{object}{For \code{detectFeatures}: Either an +\item{object}{For \code{findChromPeaks}: Either an \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} object containing the MS- and all other experiment-relevant data. @@ -160,11 +160,11 @@ the matchedFilter algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. See documentation of the \code{BiocParallel} for more details. If parallel -processing is enables, feature detection is performed in parallel on several +processing is enables, peak detection is performed in parallel on several of the input samples.} \item{return.type}{Character specifying what type of object the method should -return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or \code{"xcmsSet"}.} \item{value}{The value for the slot.} @@ -174,41 +174,41 @@ return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or \value{ The \code{MatchedFilterParam} function returns a \code{MatchedFilterParam} class instance with all of the settings specified -for feature detection by the centWave method. +for chromatographic detection by the \emph{matchedFilter} method. -For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -\code{\link{XCMSnExp}} object with the results of the feature detection. +For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +\code{\link{XCMSnExp}} object with the results of the peak detection. If \code{return.type = "list"} a list of length equal to the number of -samples with matrices specifying the identified features/peaks. +samples with matrices specifying the identified peaks. If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -with the results of the feature detection. +with the results of the peak detection. } \description{ -The \emph{matchedFilter} algorithm identifies features in the +The \emph{matchedFilter} algorithm identifies peaks in the chromatographic time domain as described in [Smith 2006]. The intensity values are binned by cutting The LC/MS data into slices (bins) of a mass unit (\code{binSize} m/z) wide. Within each bin the maximal intensity is selected. -The feature detection is then performed in each bin by extending it based on -the \code{steps} parameter to generate slices comprising bins +The chromatographic peak detection is then performed in each bin by extending +it based on the \code{steps} parameter to generate slices comprising bins \code{current_bin - steps +1} to \code{current_bin + steps - 1}. Each of these slices is then filtered with matched filtration using a second-derative -Gaussian as the model feature/peak shape. After filtration features are -detected using a signal-to-ration cut-off. For more details and -illustrations see [Smith 2006]. +Gaussian as the model peak shape. After filtration peaks are detected using +a signal-to-ration cut-off. For more details and illustrations see +[Smith 2006]. The \code{MatchedFilterParam} class allows to specify all -settings for a feature detection using the matchedFilter method. Instances -should be created with the \code{MatchedFilterParam} constructor. +settings for a chromatographic peak detection using the matchedFilter method. +Instances should be created with the \code{MatchedFilterParam} constructor. -The \code{detectFeatures,OnDiskMSnExp,MatchedFilterParam} -method performs feature detection using the \emph{matchedFilter} algorithm +The \code{findChromPeaks,OnDiskMSnExp,MatchedFilterParam} +method performs peak detection using the \emph{matchedFilter} algorithm on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. -The \code{detectFeatures,MSnExp,MatchedFilterParam} method -performs feature detection using the \emph{matchedFilter} method on all +The \code{findChromPeaks,MSnExp,MatchedFilterParam} method +performs peak detection using the \emph{matchedFilter} method on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and intensity values of all spectra hence no additional data input from the original files is required. @@ -270,8 +270,8 @@ the version from the class. Slots values should exclusively be accessed \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{findPeaks}} methods. It supports feature detection on -\code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} +\code{\link{findPeaks}} methods. It supports chromatographic peak detection +on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} objects (both defined in the \code{MSnbase} package). All of the settings to the matchedFilter algorithm can be passed with a \code{MatchedFilterParam} object. @@ -284,7 +284,7 @@ mfp <- MatchedFilterParam(binSize = 0.5) snthresh(mfp) <- 15 mfp -## Perform the feature detection using matchecFilter on the files from the +## Perform the peak detection using matchecFilter on the files from the ## faahKO package. Files are read using the readMSData2 from the MSnbase ## package library(faahKO) @@ -292,12 +292,12 @@ library(MSnbase) fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, full.names = TRUE) raw_data <- readMSData2(fls) -## Perform the feature detection using the settings defined above. We're -## returning the results as an xcmsSet object. Note that we are also -## disabling parallel processing in this example by registering a "SerialParam" +## Perform the chromatographic peak detection using the settings defined +## above. Note that we are also disabling parallel processing in this +## example by registering a "SerialParam" register(SerialParam()) -res <- detectFeatures(raw_data, param = mfp, return.type = "xcmsSet") -head(peaks(res)) +res <- findChromPeaks(raw_data, param = mfp) +head(chromPeaks(res)) } \author{ Colin A Smith, Johannes Rainer @@ -309,16 +309,16 @@ Profiling Using Nonlinear Peak Alignment, Matching, and Identification" \emph{Anal. Chem.} 2006, 78:779-787. } \seealso{ -The \code{\link{do_detectFeatures_matchedFilter}} core API function +The \code{\link{do_findChromPeaks_matchedFilter}} core API function and \code{\link{findPeaks.matchedFilter}} for the old user interface. \code{\link{XCMSnExp}} for the object containing the results of -the feature detection. +the chromatographic peak detection. -Other feature detection methods: \code{\link{detectFeatures}}, - \code{\link{featureDetection-MSW}}, - \code{\link{featureDetection-centWaveWithPredIsoROIs}}, - \code{\link{featureDetection-centWave}}, - \code{\link{featureDetection-massifquant}} +Other peak detection methods: \code{\link{chromatographic-peak-detection}}, + \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, + \code{\link{findChromPeaks-centWave}}, + \code{\link{findChromPeaks-massifquant}}, + \code{\link{findPeaks-MSW}} } diff --git a/man/featureDetection-MSW.Rd b/man/findPeaks-MSW.Rd similarity index 81% rename from man/featureDetection-MSW.Rd rename to man/findPeaks-MSW.Rd index 0ac9afd13..d70e520fa 100644 --- a/man/featureDetection-MSW.Rd +++ b/man/findPeaks-MSW.Rd @@ -1,7 +1,7 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-OnDiskMSnExp.R, R/methods-Params.R \docType{class} -\name{featureDetection-MSW} +\name{findPeaks-MSW} \alias{MSW} \alias{MSWParam} \alias{MSWParam-class} @@ -13,9 +13,9 @@ \alias{ampTh,MSWParam-method} \alias{ampTh<-} \alias{ampTh<-,MSWParam-method} -\alias{detectFeatures,MSnExp,MSWParam-method} -\alias{detectFeatures,OnDiskMSnExp,MSWParam-method} -\alias{featureDetection-MSW} +\alias{findChromPeaks,MSnExp,MSWParam-method} +\alias{findChromPeaks,OnDiskMSnExp,MSWParam-method} +\alias{findPeaks-MSW} \alias{minNoiseLevel} \alias{minNoiseLevel,MSWParam-method} \alias{minNoiseLevel<-} @@ -49,17 +49,17 @@ \alias{tuneIn<-,MSWParam-method} \alias{verboseColumns,MSWParam-method} \alias{verboseColumns<-,MSWParam-method} -\title{Single-spectrum non-chromatography MS data feature detection} +\title{Single-spectrum non-chromatography MS data peak detection} \usage{ MSWParam(snthresh = 3, verboseColumns = FALSE, scales = c(1, seq(2, 30, 2), seq(32, 64, 4)), nearbyPeak = TRUE, peakScaleRange = 5, ampTh = 0.01, minNoiseLevel = ampTh/snthresh, ridgeLength = 24, peakThr = NULL, tuneIn = FALSE, ...) -\S4method{detectFeatures}{OnDiskMSnExp,MSWParam}(object, param, +\S4method{findChromPeaks}{OnDiskMSnExp,MSWParam}(object, param, BPPARAM = bpparam(), return.type = "XCMSnExp") -\S4method{detectFeatures}{MSnExp,MSWParam}(object, param, BPPARAM = bpparam(), +\S4method{findChromPeaks}{MSnExp,MSWParam}(object, param, BPPARAM = bpparam(), return.type = "list") \S4method{show}{MSWParam}(object) @@ -109,10 +109,10 @@ MSWParam(snthresh = 3, verboseColumns = FALSE, scales = c(1, seq(2, 30, \S4method{addParams}{MSWParam}(object) <- value } \arguments{ -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{verboseColumns}{Logical whether additional feature meta data columns -should be returned.} +\item{verboseColumns}{\code{logical(1)} whether additional peak meta data +columns should be returned.} \item{scales}{Numeric defining the scales of the continuous wavelet transform (CWT).} @@ -145,7 +145,7 @@ estimation of the detected peaks.} \code{\link[MassSpecWavelet]{sav.gol}} functions from the \code{MassSpecWavelet} package.} -\item{object}{For \code{detectFeatures}: Either an +\item{object}{For \code{findChromPeaks}: Either an \code{\link[MSnbase]{OnDiskMSnExp}} or a \code{\link[MSnbase]{MSnExp}} object containing the MS- and all other experiment-relevant data. @@ -157,45 +157,45 @@ the algorithm.} \item{BPPARAM}{A parameter class specifying if and how parallel processing should be performed. It defaults to \code{\link[BiocParallel]{bpparam}}. See documentation of the \code{BiocParallel} for more details. If parallel -processing is enables, feature detection is performed in parallel on several +processing is enables, peak detection is performed in parallel on several of the input samples.} \item{return.type}{Character specifying what type of object the method should -return. Can be either \code{"XCMSnExp"} (code), \code{"list"} or +return. Can be either \code{"XCMSnExp"} (default), \code{"list"} or \code{"xcmsSet"}.} \item{value}{The value for the slot.} } \value{ The \code{MSWParam} function returns a \code{MSWParam} -class instance with all of the settings specified for feature detection by -the centWave method. +class instance with all of the settings specified for peak detection by +the \emph{MSW} method. -For \code{detectFeatures}: if \code{return.type = "XCMSnExp"} an -\code{\link{XCMSnExp}} object with the results of the feature detection. +For \code{findChromPeaks}: if \code{return.type = "XCMSnExp"} an +\code{\link{XCMSnExp}} object with the results of the peak detection. If \code{return.type = "list"} a list of length equal to the number of -samples with matrices specifying the identified features/peaks. +samples with matrices specifying the identified peaks. If \code{return.type = "xcmsSet"} an \code{\linkS4class{xcmsSet}} object -with the results of the feature detection. +with the results of the detection. } \description{ -Perform feature detection in mass spectrometry +Perform peak detection in mass spectrometry direct injection spectrum using a wavelet based algorithm. The \code{MSWParam} class allows to specify all -settings for a feature detection using the MSW method. Instances should be +settings for a peak detection using the MSW method. Instances should be created with the \code{MSWParam} constructor. -The \code{detectFeatures,OnDiskMSnExp,MSWParam} -method performs feature detection in single-spectrum non-chromatography MS +The \code{findChromPeaks,OnDiskMSnExp,MSWParam} +method performs peak detection in single-spectrum non-chromatography MS data using functionality from the \code{MassSpecWavelet} package on all samples from an \code{\link[MSnbase]{OnDiskMSnExp}} object. \code{\link[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. -The \code{detectFeatures,MSnExp,MSWParam} method -performs feature detection in single-spectrum non-chromatography MS +The \code{findChromPeaks,MSnExp,MSWParam} method +performs peak detection in single-spectrum non-chromatography MS data using functionality from the \code{MassSpecWavelet} package on all samples from an \code{\link[MSnbase]{MSnExp}} object. These objects contain mz and intensity values of all spectra hence no additional @@ -260,11 +260,10 @@ setter methods listed above.} \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{findPeaks}} methods. It supports feature detection on +\code{\link{findPeaks}} methods. It supports peak detection on \code{\link[MSnbase]{MSnExp}} and \code{\link[MSnbase]{OnDiskMSnExp}} objects (both defined in the \code{MSnbase} package). All of the settings -to the massifquant and centWave algorithm can be passed with a -\code{MassifquantParam} object. +to the algorithm can be passed with a \code{MSWParam} object. } \examples{ @@ -280,27 +279,27 @@ fticrf <- list.files(system.file("fticr", package = "msdata"), recursive = TRUE, full.names = TRUE) fticr <- readMSData2(fticrf[1:2], msLevel. = 1) -## Perform the MSW feature detection on these: +## Perform the MSW peak detection on these: p <- MSWParam(scales = c(1, 7), peakThr = 80000, ampTh = 0.005, SNR.method = "data.mean", winSize.noise = 500) -fticr <- detectFeatures(fticr, param = p) +fticr <- findChromPeaks(fticr, param = p) -head(features(fticr)) +head(chromPeaks(fticr)) } \author{ Joachim Kutzera, Steffen Neumann, Johannes Rainer } \seealso{ -The \code{\link{do_detectFeatures_MSW}} core API function +The \code{\link{do_findPeaks_MSW}} core API function and \code{\link{findPeaks.MSW}} for the old user interface. \code{\link{XCMSnExp}} for the object containing the results of -the feature detection. +the peak detection. -Other feature detection methods: \code{\link{detectFeatures}}, - \code{\link{featureDetection-centWaveWithPredIsoROIs}}, - \code{\link{featureDetection-centWave}}, - \code{\link{featureDetection-massifquant}}, - \code{\link{featureDetection-matchedFilter}} +Other peak detection methods: \code{\link{chromatographic-peak-detection}}, + \code{\link{findChromPeaks-centWaveWithPredIsoROIs}}, + \code{\link{findChromPeaks-centWave}}, + \code{\link{findChromPeaks-massifquant}}, + \code{\link{findChromPeaks-matchedFilter}} } diff --git a/man/findPeaks.MSW-xcmsRaw-method.Rd b/man/findPeaks.MSW-xcmsRaw-method.Rd index 4cd9d39af..d6917e1c9 100644 --- a/man/findPeaks.MSW-xcmsRaw-method.Rd +++ b/man/findPeaks.MSW-xcmsRaw-method.Rd @@ -4,18 +4,18 @@ \name{findPeaks.MSW,xcmsRaw-method} \alias{findPeaks.MSW} \alias{findPeaks.MSW,xcmsRaw-method} -\title{Feature detection for single-spectrum non-chromatography MS data} +\title{Peak detection for single-spectrum non-chromatography MS data} \usage{ \S4method{findPeaks.MSW}{xcmsRaw}(object, snthresh = 3, verbose.columns = FALSE, ...) } \arguments{ -\item{object}{The \code{\linkS4class{xcmsRaw}} object on which feature +\item{object}{The \code{\linkS4class{xcmsRaw}} object on which peak detection should be performed.} -\item{snthresh}{numeric(1) defining the signal to noise ratio cutoff.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise ratio cutoff.} -\item{verbose.columns}{Logical whether additional feature meta data columns +\item{verbose.columns}{Logical whether additional peak meta data columns should be returned.} \item{...}{Additional parameters to be passed to the @@ -24,23 +24,23 @@ should be returned.} \code{MassSpecWavelet} package.} } \value{ -A matrix, each row representing an intentified feature, with columns: +A matrix, each row representing an intentified peak, with columns: \describe{ -\item{mz}{m/z value of the feature at the centroid position.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} +\item{mz}{m/z value of the peak at the centroid position.} +\item{mzmin}{Minimum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} \item{rt}{Always \code{-1}.} \item{rtmin}{Always \code{-1}.} \item{rtmax}{Always \code{-1}.} -\item{into}{Integrated (original) intensity of the feature.} -\item{maxo}{Maximum intensity of the feature.} +\item{into}{Integrated (original) intensity of the peak.} +\item{maxo}{Maximum intensity of the peak.} \item{intf}{Always \code{NA}.} -\item{maxf}{Maximum MSW-filter response of the feature.} +\item{maxf}{Maximum MSW-filter response of the peak.} \item{sn}{Signal to noise ratio.} } } \description{ -This method performs feature detection in mass spectrometry +This method performs peak detection in mass spectrometry direct injection spectrum using a wavelet based algorithm. } \details{ @@ -54,7 +54,7 @@ Joachim Kutzera, Steffen Neumann, Johannes Rainer } \seealso{ \code{\link{MSW}} for the new user interface, -\code{\link{do_detectFeatures_MSW}} for the downstream analysis +\code{\link{do_findPeaks_MSW}} for the downstream analysis function or \code{\link[MassSpecWavelet]{peakDetectionCWT}} from the \code{MassSpecWavelet} for details on the algorithm and additionally supported parameters. diff --git a/man/findPeaks.centWaveWithPredictedIsotopeROIs-methods.Rd b/man/findPeaks.centWaveWithPredictedIsotopeROIs-methods.Rd index 7347c0fb0..9c921205d 100644 --- a/man/findPeaks.centWaveWithPredictedIsotopeROIs-methods.Rd +++ b/man/findPeaks.centWaveWithPredictedIsotopeROIs-methods.Rd @@ -133,7 +133,7 @@ Submitted to Metabolites 2016, Special Issue "Bioinformatics and Data Analysis" } \seealso{ - \code{\link{do_detectFeatures_centWaveWithPredIsoROIs}} for the + \code{\link{do_findChromPeaks_centWaveWithPredIsoROIs}} for the corresponding core API function. \code{\link{findPeaks.addPredictedIsotopeFeatures}} \code{\link{findPeaks.centWave}} diff --git a/man/findPeaks.matchedFilter-xcmsRaw-method.Rd b/man/findPeaks.matchedFilter-xcmsRaw-method.Rd index 109024290..8191faabc 100644 --- a/man/findPeaks.matchedFilter-xcmsRaw-method.Rd +++ b/man/findPeaks.matchedFilter-xcmsRaw-method.Rd @@ -4,7 +4,7 @@ \name{findPeaks.matchedFilter,xcmsRaw-method} \alias{findPeaks.matchedFilter} \alias{findPeaks.matchedFilter,xcmsRaw-method} -\title{Feature detection in the chromatographic time domain} +\title{Peak detection in the chromatographic time domain} \usage{ \S4method{findPeaks.matchedFilter}{xcmsRaw}(object, fwhm = 30, sigma = fwhm/2.3548, max = 5, snthresh = 10, step = 0.1, steps = 2, @@ -12,62 +12,64 @@ scanrange = numeric()) } \arguments{ -\item{object}{The \code{\linkS4class{xcmsRaw}} object on which feature detection +\item{object}{The \code{\linkS4class{xcmsRaw}} object on which peak detection should be performed.} -\item{fwhm}{numeric(1) specifying the full width at half maximum +\item{fwhm}{\code{numeric(1)} specifying the full width at half maximum of matched filtration gaussian model peak. Only used to calculate the actual sigma, see below.} -\item{sigma}{numeric(1) specifying the standard deviation (width) +\item{sigma}{\code{numeric(1)} specifying the standard deviation (width) of the matched filtration model peak.} -\item{max}{numeric(1) representing the maximum number of peaks +\item{max}{\code{numeric(1)} representing the maximum number of peaks that are expected/will be identified per slice.} -\item{snthresh}{numeric(1) defining the signal to noise cutoff -to be used in the feature detection step.} +\item{snthresh}{\code{numeric(1)} defining the signal to noise cutoff +to be used in the chromatographic peak detection step.} \item{step}{numeric(1) specifying the width of the bins/slices in m/z dimension.} -\item{steps}{numeric(1) defining the number of bins to be +\item{steps}{\code{numeric(1)} defining the number of bins to be merged before filtration (i.e. the number of neighboring bins that will be joined to the slice in which filtration and peak detection will be performed).} -\item{mzdiff}{numeric(1) defining the minimum difference +\item{mzdiff}{\code{numeric(1)} defining the minimum difference in m/z for peaks with overlapping retention times} -\item{index}{Logical specifying whether indicies should be returned instead +\item{index}{\code{logical(1)} specifying whether indicies should be returned instead of values for m/z and retention times.} \item{sleep}{(DEFUNCT). This parameter is no longer functional, as it would cause problems in parallel processing mode.} \item{scanrange}{Numeric vector defining the range of scans to which the original -\code{object} should be sub-setted before feature detection.} +\code{object} should be sub-setted before peak detection.} } \value{ -A matrix, each row representing an intentified feature, with columns: +A matrix, each row representing an intentified chromatographic peak, +with columns: \describe{ -\item{mz}{Intensity weighted mean of m/z values of the feature across scans.} -\item{mzmin}{Minimum m/z of the feature.} -\item{mzmax}{Maximum m/z of the feature.} -\item{rt}{Retention time of the feature's midpoint.} -\item{rtmin}{Minimum retention time of the feature.} -\item{rtmax}{Maximum retention time of the feature.} -\item{into}{Integrated (original) intensity of the feature.} +\item{mz}{Intensity weighted mean of m/z values of the peak across scans.} +\item{mzmin}{Minimum m/z of the peak.} +\item{mzmax}{Maximum m/z of the peak.} +\item{rt}{Retention time of the peak's midpoint.} +\item{rtmin}{Minimum retention time of the peak.} +\item{rtmax}{Maximum retention time of the peak.} +\item{into}{Integrated (original) intensity of the peak.} \item{intf}{Integrated intensity of the filtered peak.} -\item{maxo}{Maximum intensity of the feature.} +\item{maxo}{Maximum intensity of the peak.} \item{maxf}{Maximum intensity of the filtered peak.} -\item{i}{Rank of feature in merged EIC (\code{<= max}).} -\item{sn}{Signal to noise ratio of the feature} +\item{i}{Rank of peak in merged EIC (\code{<= max}).} +\item{sn}{Signal to noise ratio of the peak.} } } \description{ -Find features (peaks) in the chromatographic time domain of the -profile matrix. For more details see \code{\link{do_detectFeatures_matchedFilter}}. +Find peaks in the chromatographic time domain of the +profile matrix. For more details see +\code{\link{do_findChromPeaks_matchedFilter}}. } \author{ Colin A. Smith @@ -81,7 +83,7 @@ Profiling Using Nonlinear Peak Alignment, Matching, and Identification" \seealso{ \code{\link{matchedFilter}} for the new user interface. \code{\linkS4class{xcmsRaw}}, -\code{\link{do_detectFeatures_matchedFilter}} for the core function -performing the feature detection. +\code{\link{do_findChromPeaks_matchedFilter}} for the core function +performing the peak detection. } diff --git a/man/group.density.Rd b/man/group.density.Rd index 3e6dd4509..66969afc9 100644 --- a/man/group.density.Rd +++ b/man/group.density.Rd @@ -49,7 +49,7 @@ An \code{xcmsSet} object with peak group assignments and statistics. } \seealso{ - \code{\link{do_groupFeatures_density}} for the core API function + \code{\link{do_groupChromPeaks_density}} for the core API function performing the analysis. \code{\link{xcmsSet-class}}, \code{\link{density}} diff --git a/man/groupChromPeaks-density.Rd b/man/groupChromPeaks-density.Rd new file mode 100644 index 000000000..152d4b66d --- /dev/null +++ b/man/groupChromPeaks-density.Rd @@ -0,0 +1,226 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R +\docType{class} +\name{groupChromPeaks-density} +\alias{PeakDensityParam} +\alias{PeakDensityParam-class} +\alias{binSize,PeakDensityParam-method} +\alias{binSize<-,PeakDensityParam-method} +\alias{bw} +\alias{bw,PeakDensityParam-method} +\alias{bw<-} +\alias{bw<-,PeakDensityParam-method} +\alias{groupChromPeaks,XCMSnExp,PeakDensityParam-method} +\alias{groupChromPeaks-density} +\alias{maxFeatures} +\alias{maxFeatures,PeakDensityParam-method} +\alias{maxFeatures<-} +\alias{maxFeatures<-,PeakDensityParam-method} +\alias{minFraction} +\alias{minFraction,PeakDensityParam-method} +\alias{minFraction<-} +\alias{minFraction<-,PeakDensityParam-method} +\alias{minSamples} +\alias{minSamples,PeakDensityParam-method} +\alias{minSamples<-} +\alias{minSamples<-,PeakDensityParam-method} +\alias{sampleGroups} +\alias{sampleGroups,PeakDensityParam-method} +\alias{sampleGroups<-} +\alias{sampleGroups<-,PeakDensityParam-method} +\alias{show,PeakDensityParam-method} +\title{Peak grouping based on time dimension peak densities} +\usage{ +PeakDensityParam(sampleGroups = numeric(), bw = 30, minFraction = 0.5, + minSamples = 1, binSize = 0.25, maxFeatures = 50) + +\S4method{show}{PeakDensityParam}(object) + +\S4method{sampleGroups}{PeakDensityParam}(object) + +\S4method{sampleGroups}{PeakDensityParam}(object) <- value + +\S4method{bw}{PeakDensityParam}(object) + +\S4method{bw}{PeakDensityParam}(object) <- value + +\S4method{minFraction}{PeakDensityParam}(object) + +\S4method{minFraction}{PeakDensityParam}(object) <- value + +\S4method{minSamples}{PeakDensityParam}(object) + +\S4method{minSamples}{PeakDensityParam}(object) <- value + +\S4method{binSize}{PeakDensityParam}(object) + +\S4method{binSize}{PeakDensityParam}(object) <- value + +\S4method{maxFeatures}{PeakDensityParam}(object) + +\S4method{maxFeatures}{PeakDensityParam}(object) <- value + +\S4method{groupChromPeaks}{XCMSnExp,PeakDensityParam}(object, param) +} +\arguments{ +\item{sampleGroups}{A vector of the same length than samples defining the +sample group assignments (i.e. which samples belong to which sample group).} + +\item{bw}{\code{numeric(1)} defining the bandwidth (standard deviation ot the +smoothing kernel) to be used. This argument is passed to the +\code{\link{density}} method.} + +\item{minFraction}{\code{numeric(1)} defining the minimum fraction of samples +in at least one sample group in which the peaks have to be present to be +considered as a peak group (feature).} + +\item{minSamples}{\code{numeric(1)} with the minimum number of samples in at +least one sample group in which the peaks have to be detected to be +considered a peak group (feature).} + +\item{binSize}{\code{numeric(1)} defining the size of the overlapping slices +in mz dimension.} + +\item{maxFeatures}{\code{numeric(1)} with the maximum number of peak groups +to be identified in a single mz slice.} + +\item{object}{For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +containing the results from a previous peak detection analysis (see +\code{\link{findChromPeaks}}). + +For all other methods: a \code{PeakDensityParam} object.} + +\item{value}{The value for the slot.} + +\item{param}{A \code{PeakDensityParam} object containing all settings for +the peak grouping algorithm.} +} +\value{ +The \code{PeakDensityParam} function returns a +\code{PeakDensityParam} class instance with all of the settings +specified for chromatographic peak alignment based on peak densities. + +For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +results of the correspondence analysis. The definition of the resulting mz-rt +features can be accessed with the \code{\link{featureDefinitions}} method. +} +\description{ +This method performs performs correspondence (chromatographic +peak grouping) based on the density (distribution) of identified peaks +along the retention time axis within slices of overlapping mz ranges. +All peaks (from the same or from different samples) being close on the +retention time axis are grouped into a feature (\emph{peak group}). + +The \code{PeakDensityParam} class allows to specify all +settings for the peak grouping based on peak densities along the time +dimension. Instances should be created with the \code{PeakDensityParam} +constructor. + +\code{sampleGroups},\code{sampleGroups<-}: getter and setter +for the \code{sampleGroups} slot of the object. + +\code{bw},\code{bw<-}: getter and setter for the \code{bw} slot +of the object. + +\code{minFraction},\code{minFraction<-}: getter and setter for +the \code{minFraction} slot of the object. + +\code{minSamples},\code{minSamples<-}: getter and setter for the +\code{minSamples} slot of the object. + +\code{binSize},\code{binSize<-}: getter and setter for the +\code{binSize} slot of the object. + +\code{maxFeatures},\code{maxFeatures<-}: getter and setter for +the \code{maxFeatures} slot of the object. + +\code{groupChromPeaks,XCMSnExp,PeakDensityParam}: +performs correspondence (peak grouping within and across samples) within in +mz dimension overlapping slices of MS data based on the density distribution +of the identified chromatographic peaks in the slice along the time axis. +} +\section{Slots}{ + +\describe{ +\item{\code{.__classVersion__,sampleGroups,bw,minFraction,minSamples,binSize,maxFeatures}}{See corresponding parameter above. \code{.__classVersion__} stores +the version from the class. Slots values should exclusively be accessed +\emph{via} the corresponding getter and setter methods listed above.} +}} +\note{ +These methods and classes are part of the updated and modernized +\code{xcms} user interface which will eventually replace the +\code{\link{group}} methods. All of the settings to the algorithm +can be passed with a \code{PeakDensityParam} object. + +Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause +all eventually present previous correspondence results to be dropped. +} +\examples{ + +## Create a PeakDensityParam object +p <- PeakDensityParam(binSize = 0.05) +## Change hte minSamples slot +minSamples(p) <- 3 +p + +############################## +## Chromatographic peak detection and grouping. +## +## Below we perform first a peak detection (using the matchedFilter +## method) on some of the test files from the faahKO package followed by +## a peak grouping using the density method. +library(faahKO) +library(MSnbase) +fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, + full.names = TRUE) + +## Reading 2 of the KO samples +raw_data <- readMSData2(fls[1:2]) + +## Perform the chromatographic peak detection using the matchedFilter method. +mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) +res <- findChromPeaks(raw_data, param = mfp) + +head(chromPeaks(res)) +## The number of peaks identified per sample: +table(chromPeaks(res)[, "sample"]) + +## Performing the chromatographic peak grouping +fdp <- PeakDensityParam() +res <- groupChromPeaks(res, fdp) + +## The definition of the features (peak groups): +featureDefinitions(res) + +## Using the groupval method to extract a matrix with the intensities of +## the features per sample. +head(groupval(res, value = "into")) + +## The process history: +processHistory(res) +} +\author{ +Colin Smith, Johannes Rainer +} +\references{ +Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and +Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite +Profiling Using Nonlinear Peak Alignment, Matching, and Identification" +\emph{Anal. Chem.} 2006, 78:779-787. +} +\seealso{ +The \code{\link{do_groupChromPeaks_density}} core +API function and \code{\link{group.density}} for the old user interface. + +\code{\link{featureDefinitions}} and +\code{\link{groupval,XCMSnExp-method}} for methods to access the features +(i.e. the peak grouping results). + +\code{\link{XCMSnExp}} for the object containing the results of +the correspondence. + +Other peak grouping methods: \code{\link{groupChromPeaks-mzClust}}, + \code{\link{groupChromPeaks-nearest}}, + \code{\link{groupChromPeaks}} +} + diff --git a/man/groupFeatures-mzClust.Rd b/man/groupChromPeaks-mzClust.Rd similarity index 62% rename from man/groupFeatures-mzClust.Rd rename to man/groupChromPeaks-mzClust.Rd index 069e23ca0..19b837cdd 100644 --- a/man/groupFeatures-mzClust.Rd +++ b/man/groupChromPeaks-mzClust.Rd @@ -1,15 +1,15 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R \docType{class} -\name{groupFeatures-mzClust} +\name{groupChromPeaks-mzClust} \alias{MzClustParam} \alias{MzClustParam-class} \alias{absMz} \alias{absMz,MzClustParam-method} \alias{absMz<-} \alias{absMz<-,MzClustParam-method} -\alias{groupFeatures,XCMSnExp,MzClustParam-method} -\alias{groupFeatures-mzClust} +\alias{groupChromPeaks,XCMSnExp,MzClustParam-method} +\alias{groupChromPeaks-mzClust} \alias{minFraction,MzClustParam-method} \alias{minFraction<-,MzClustParam-method} \alias{minSamples,MzClustParam-method} @@ -19,7 +19,7 @@ \alias{sampleGroups,MzClustParam-method} \alias{sampleGroups<-,MzClustParam-method} \alias{show,MzClustParam-method} -\title{High resolution feature alignment for single spectra samples} +\title{High resolution peak grouping for single spectra samples} \usage{ MzClustParam(sampleGroups = numeric(), ppm = 20, absMz = 0, minFraction = 0.5, minSamples = 1) @@ -46,51 +46,52 @@ MzClustParam(sampleGroups = numeric(), ppm = 20, absMz = 0, \S4method{minSamples}{MzClustParam}(object) <- value -\S4method{groupFeatures}{XCMSnExp,MzClustParam}(object, param) +\S4method{groupChromPeaks}{XCMSnExp,MzClustParam}(object, param) } \arguments{ \item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} +sample group assignments (i.e. which samples belong to which sample group).} -\item{ppm}{numeric(1) representing the relative mz error for the +\item{ppm}{\code{numeric(1)} representing the relative mz error for the clustering/grouping (in parts per million).} -\item{absMz}{numeric(1) representing the absolute mz error for the clustering.} +\item{absMz}{\code{numeric(1)} representing the absolute mz error for the +clustering.} -\item{minFraction}{numeric(1) defining the minimum fraction of samples in at -least one sample group in which the features have to be present to be -considered as a feature group.} +\item{minFraction}{\code{numeric(1)} defining the minimum fraction of samples +in at least one sample group in which the peaks have to be present to be +considered as a peak group (feature).} -\item{minSamples}{numeric(1) with the minimum number of samples in at least -one sample group in which the features have to be detected to be considered -as a feature group.} +\item{minSamples}{\code{numeric(1)} with the minimum number of samples in at +least one sample group in which the peaks have to be detected to be +considered a peak group (feature).} -\item{object}{For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -containing the results from a previous feature detection analysis (see -\code{\link{detectFeatures}}). +\item{object}{For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +containing the results from a previous chromatographic peak detection +analysis (see \code{\link{findChromPeaks}}). For all other methods: a \code{MzClustParam} object.} \item{value}{The value for the slot.} \item{param}{A \code{MzClustParam} object containing all settings for -the feature alignment algorithm.} +the peak grouping algorithm.} } \value{ The \code{MzClustParam} function returns a \code{MzClustParam} class instance with all of the settings -specified for high resolution single spectra feature alignment. +specified for high resolution single spectra peak alignment. -For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -results of the feature alignment step. These can be accessed with the -\code{\link{featureGroups}} method. +For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +results of the peak grouping step (i.e. the features). These can be accessed +with the \code{\link{featureDefinitions}} method. } \description{ -This method performs high resolution alignment for single +This method performs high resolution correspondence for single spectra samples. The \code{MzClustParam} class allows to specify all -settings for the feature alignment based on the \emph{mzClust} algorithm. +settings for the peak grouping based on the \emph{mzClust} algorithm. Instances should be created with the \code{MzClustParam} constructor. \code{sampleGroups},\code{sampleGroups<-}: getter and setter @@ -108,9 +109,9 @@ the \code{minFraction} slot of the object. \code{minSamples},\code{minSamples<-}: getter and setter for the \code{minSamples} slot of the object. -\code{groupFeatures,XCMSnExp,MzClustParam}: -performs high resolution feature alignment for single spectrum metabolomics -data. +\code{groupChromPeaks,XCMSnExp,MzClustParam}: +performs high resolution peak grouping for single spectrum +metabolomics data. } \section{Slots}{ @@ -122,11 +123,11 @@ the version from the class. Slots values should exclusively be accessed \note{ These methods and classes are part of the updated and modernized \code{xcms} user interface which will eventually replace the -\code{\link{group}} methods. All of the settings to the alignment algorithm +\code{\link{group}} methods. All of the settings to the algorithm can be passed with a \code{MzClustParam} object. -Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause -all eventually present previous alignment results to be dropped. +Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause +all eventually present previous correspondence results to be dropped. } \examples{ @@ -136,20 +137,21 @@ fticrf <- list.files(system.file("fticr", package = "msdata"), recursive = TRUE, full.names = TRUE) fticr <- readMSData2(fticrf[1:2], msLevel. = 1) -## Perform the MSW feature detection on these: +## Perform the MSW peak detection on these: p <- MSWParam(scales = c(1, 7), peakThr = 80000, ampTh = 0.005, SNR.method = "data.mean", winSize.noise = 500) -fticr <- detectFeatures(fticr, param = p) +fticr <- findChromPeaks(fticr, param = p) -head(features(fticr)) +head(chromPeaks(fticr)) ## Now create the MzClustParam parameter object: we're assuming here that ## both samples are from the same sample group. p <- MzClustParam(sampleGroups = c(1, 1)) -fticr <- groupFeatures(fticr, param = p) +fticr <- groupChromPeaks(fticr, param = p) -featureGroups(fticr) +## Get the definition of the features. +featureDefinitions(fticr) } \references{ Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill @@ -158,17 +160,18 @@ development of a heuristic approach for metabolomics}.\cr Metabolomics, Vol. 2, No. 2, 75-83 (2006) } \seealso{ -The \code{\link{do_groupFeatures_mzClust}} core +The \code{\link{do_groupPeaks_mzClust}} core API function and \code{\link{group.mzClust}} for the old user interface. -\code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -for methods to access feature grouping results. +\code{\link{featureDefinitions}} and +\code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +results (i.e. the features). \code{\link{XCMSnExp}} for the object containing the results of -the feature alignment. +the peak grouping. -Other feature alignment methods: \code{\link{groupFeatures-density}}, - \code{\link{groupFeatures-nearest}}, - \code{\link{groupFeatures}} +Other peak grouping methods: \code{\link{groupChromPeaks-density}}, + \code{\link{groupChromPeaks-nearest}}, + \code{\link{groupChromPeaks}} } diff --git a/man/groupChromPeaks-nearest.Rd b/man/groupChromPeaks-nearest.Rd new file mode 100644 index 000000000..54b1c3933 --- /dev/null +++ b/man/groupChromPeaks-nearest.Rd @@ -0,0 +1,201 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R +\docType{class} +\name{groupChromPeaks-nearest} +\alias{NearestPeaksParam} +\alias{NearestPeaksParam-class} +\alias{absMz,NearestPeaksParam-method} +\alias{absMz<-,NearestPeaksParam-method} +\alias{absRt} +\alias{absRt,NearestPeaksParam-method} +\alias{absRt<-} +\alias{absRt<-,NearestPeaksParam-method} +\alias{groupChromPeaks,XCMSnExp,NearestPeaksParam-method} +\alias{groupChromPeaks-nearest} +\alias{kNN} +\alias{kNN,NearestPeaksParam-method} +\alias{kNN<-} +\alias{kNN<-,NearestPeaksParam-method} +\alias{mzVsRtBalance} +\alias{mzVsRtBalance,NearestPeaksParam-method} +\alias{mzVsRtBalance<-} +\alias{mzVsRtBalance<-,NearestPeaksParam-method} +\alias{sampleGroups,NearestPeaksParam-method} +\alias{sampleGroups<-,NearestPeaksParam-method} +\alias{show,NearestPeaksParam-method} +\title{Peak grouping based on proximity in the mz-rt space} +\usage{ +NearestPeaksParam(sampleGroups = numeric(), mzVsRtBalance = 10, + absMz = 0.2, absRt = 15, kNN = 10) + +\S4method{show}{NearestPeaksParam}(object) + +\S4method{sampleGroups}{NearestPeaksParam}(object) + +\S4method{sampleGroups}{NearestPeaksParam}(object) <- value + +\S4method{mzVsRtBalance}{NearestPeaksParam}(object) + +\S4method{mzVsRtBalance}{NearestPeaksParam}(object) <- value + +\S4method{absMz}{NearestPeaksParam}(object) + +\S4method{absMz}{NearestPeaksParam}(object) <- value + +\S4method{absRt}{NearestPeaksParam}(object) + +\S4method{absRt}{NearestPeaksParam}(object) <- value + +\S4method{kNN}{NearestPeaksParam}(object) + +\S4method{kNN}{NearestPeaksParam}(object) <- value + +\S4method{groupChromPeaks}{XCMSnExp,NearestPeaksParam}(object, param) +} +\arguments{ +\item{sampleGroups}{A vector of the same length than samples defining the +sample group assignments (i.e. which samples belong to which sample group).} + +\item{mzVsRtBalance}{\code{numeric(1)} representing the factor by which mz +values are multiplied before calculating the (euclician) distance between +two peaks.} + +\item{absMz}{\code{numeric(1)} maximum tolerated distance for mz values.} + +\item{absRt}{\code{numeric(1)} maximum tolerated distance for rt values.} + +\item{kNN}{\code{numeric(1)} representing the number of nearest neighbors +to check.} + +\item{object}{For \code{groupChromPeaks}: an \code{\link{XCMSnExp}} object +containing the results from a previous chromatographic peak detection +analysis (see \code{\link{findChromPeaks}}). + +For all other methods: a \code{NearestPeaksParam} object.} + +\item{value}{The value for the slot.} + +\item{param}{A \code{NearestPeaksParam} object containing all settings for +the peak grouping algorithm.} +} +\value{ +The \code{NearestPeaksParam} function returns a +\code{NearestPeaksParam} class instance with all of the settings +specified for peak alignment based on peak proximity. + +For \code{groupChromPeaks}: a \code{\link{XCMSnExp}} object with the +results of the peak grouping/correspondence step (i.e. the mz-rt features). +These can be accessed with the \code{\link{featureDefinitions}} method. +} +\description{ +This method is inspired by the grouping algorithm of mzMine +[Katajamaa 2006] and performs correspondence based on proximity of peaks in +the space spanned by retention time and mz values. +The method creates first a \emph{master peak list} consisting of all +chromatographic peaks from the sample in which most peaks were identified, +and starting from that, calculates distances to peaks from the sample with +the next most number of peaks. If peaks are closer than the defined +threshold they are grouped together. + +The \code{NearestPeaksParam} class allows to specify all +settings for the peak grouping based on the \emph{nearest} algorithm. +Instances should be created with the \code{NearestPeaksParam} constructor. + +\code{sampleGroups},\code{sampleGroups<-}: getter and setter +for the \code{sampleGroups} slot of the object. + +\code{mzVsRtBalance},\code{mzVsRtBalance<-}: getter and setter +for the \code{mzVsRtBalance} slot of the object. + +\code{absMz},\code{absMz<-}: getter and setter for the +\code{absMz} slot of the object. + +\code{absRt},\code{absRt<-}: getter and setter for the +\code{absRt} slot of the object. + +\code{kNN},\code{kNN<-}: getter and setter for the +\code{kNN} slot of the object. + +\code{groupChromPeaks,XCMSnExp,NearestPeaksParam}: +performs peak grouping based on the proximity between chromatographic +peaks from different samples in the mz-rt range. +} +\section{Slots}{ + +\describe{ +\item{\code{.__classVersion__,sampleGroups,mzVsRtBalance,absMz,absRt,kNN}}{See corresponding parameter above. \code{.__classVersion__} stores +the version from the class. Slots values should exclusively be accessed +\emph{via} the corresponding getter and setter methods listed above.} +}} +\note{ +These methods and classes are part of the updated and modernized +\code{xcms} user interface which will eventually replace the +\code{\link{group}} methods. All of the settings to the algorithm +can be passed with a \code{NearestPeaksParam} object. + +Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause +all eventually present previous alignment results to be dropped. +} +\examples{ + +## Create a NearestPeaksParam object +p <- NearestPeaksParam(kNN = 3) +p + +############################## +## Chromatographi peak detection and grouping. +## +## Below we perform first a chromatographic peak detection (using the +## matchedFilter method) on some of the test files from the faahKO package +## followed by a peaks grouping using the "nearest" method. +library(faahKO) +library(MSnbase) +fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, + full.names = TRUE) + +## Reading 2 of the KO samples +raw_data <- readMSData2(fls[1:2]) + +## Perform the peak detection using the matchedFilter method. +mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) +res <- findChromPeaks(raw_data, param = mfp) + +head(chromPeaks(res)) +## The number of peaks identified per sample: +table(chromPeaks(res)[, "sample"]) + +## Performing the peak grouping +p <- NearestPeaksParam() +res <- groupChromPeaks(res, param = p) + +## The results from the peak grouping: +featureDefinitions(res) + +## Using the groupval method to extract a matrix with the intensities of +## the features per sample. +head(groupval(res, value = "into")) + +## The process history: +processHistory(res) +} +\references{ +Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for +processing and visualization of mass spectrometry based molecular profile +data. \emph{Bioinformatics} 2006, 22:634-636. +} +\seealso{ +The \code{\link{do_groupChromPeaks_nearest}} core +API function and \code{\link{group.nearest}} for the old user interface. + +\code{\link{featureDefinitions}} and +\code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +results (i.e. the features). + +\code{\link{XCMSnExp}} for the object containing the results of +the peak grouping. + +Other peak grouping methods: \code{\link{groupChromPeaks-density}}, + \code{\link{groupChromPeaks-mzClust}}, + \code{\link{groupChromPeaks}} +} + diff --git a/man/groupChromPeaks.Rd b/man/groupChromPeaks.Rd new file mode 100644 index 000000000..dc907d0e5 --- /dev/null +++ b/man/groupChromPeaks.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DataClasses.R +\name{groupChromPeaks} +\alias{groupChromPeaks} +\title{Correspondence: Chromatographic peak grouping methods.} +\description{ +The \code{groupChromPeaks} method(s) perform the correspondence, +i.e. the grouping of chromatographic peaks within and between samples. +These methods are part of the modernized \code{xcms} user interface. +The resulting peak groups are referred to as (mz-rt) features and can be +accessed \emph{via} the \code{\link{featureDefinitions}} method on the result +object. + +The implemented peak grouping methods are: +\describe{ +\item{density}{peak grouping based on time dimension peak densities. +See \code{\link{groupChromPeaks-density}} for more details.} + +\item{mzClust}{high resolution peak grouping for single spectra (direct +infusion) MS data. See \code{\link{groupChromPeaks-mzClust}} for more +details.} + +\item{nearest}{chromatographic peak grouping based on their proximity in +the mz-rt space. See \code{\link{groupChromPeaks-nearest}} for more details.} + +} +} +\author{ +Johannes Rainer +} +\seealso{ +\code{\link{group}} for the \emph{old} peak grouping methods. + +\code{\link{featureDefinitions}} and +\code{\link{groupval,XCMSnExp-method}} for methods to access peak grouping +results. + +Other peak grouping methods: \code{\link{groupChromPeaks-density}}, + \code{\link{groupChromPeaks-mzClust}}, + \code{\link{groupChromPeaks-nearest}} +} + diff --git a/man/groupFeatures-density.Rd b/man/groupFeatures-density.Rd deleted file mode 100644 index b6e892595..000000000 --- a/man/groupFeatures-density.Rd +++ /dev/null @@ -1,225 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R -\docType{class} -\name{groupFeatures-density} -\alias{FeatureDensityParam} -\alias{FeatureDensityParam-class} -\alias{binSize,FeatureDensityParam-method} -\alias{binSize<-,FeatureDensityParam-method} -\alias{bw} -\alias{bw,FeatureDensityParam-method} -\alias{bw<-} -\alias{bw<-,FeatureDensityParam-method} -\alias{groupFeatures,XCMSnExp,FeatureDensityParam-method} -\alias{groupFeatures-density} -\alias{maxFeatures} -\alias{maxFeatures,FeatureDensityParam-method} -\alias{maxFeatures<-} -\alias{maxFeatures<-,FeatureDensityParam-method} -\alias{minFraction} -\alias{minFraction,FeatureDensityParam-method} -\alias{minFraction<-} -\alias{minFraction<-,FeatureDensityParam-method} -\alias{minSamples} -\alias{minSamples,FeatureDensityParam-method} -\alias{minSamples<-} -\alias{minSamples<-,FeatureDensityParam-method} -\alias{sampleGroups} -\alias{sampleGroups,FeatureDensityParam-method} -\alias{sampleGroups<-} -\alias{sampleGroups<-,FeatureDensityParam-method} -\alias{show,FeatureDensityParam-method} -\title{Feature alignment based on time dimension feature densities} -\usage{ -FeatureDensityParam(sampleGroups = numeric(), bw = 30, minFraction = 0.5, - minSamples = 1, binSize = 0.25, maxFeatures = 50) - -\S4method{show}{FeatureDensityParam}(object) - -\S4method{sampleGroups}{FeatureDensityParam}(object) - -\S4method{sampleGroups}{FeatureDensityParam}(object) <- value - -\S4method{bw}{FeatureDensityParam}(object) - -\S4method{bw}{FeatureDensityParam}(object) <- value - -\S4method{minFraction}{FeatureDensityParam}(object) - -\S4method{minFraction}{FeatureDensityParam}(object) <- value - -\S4method{minSamples}{FeatureDensityParam}(object) - -\S4method{minSamples}{FeatureDensityParam}(object) <- value - -\S4method{binSize}{FeatureDensityParam}(object) - -\S4method{binSize}{FeatureDensityParam}(object) <- value - -\S4method{maxFeatures}{FeatureDensityParam}(object) - -\S4method{maxFeatures}{FeatureDensityParam}(object) <- value - -\S4method{groupFeatures}{XCMSnExp,FeatureDensityParam}(object, param) -} -\arguments{ -\item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} - -\item{bw}{numeric(1) defining the bandwidth (standard deviation ot the -smoothing kernel) to be used. This argument is passed to the -\code{\link{density}} method.} - -\item{minFraction}{numeric(1) defining the minimum fraction of samples in at -least one sample group in which the features have to be present to be -considered as a feature group.} - -\item{minSamples}{numeric(1) with the minimum number of samples in at least -one sample group in which the features have to be detected to be considered -as a feature group.} - -\item{binSize}{numeric(1) defining the size of the overlapping slices in mz -dimension.} - -\item{maxFeatures}{numeric(1) with the maximum number of feature groups to -be identified in a single mz slice.} - -\item{object}{For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -containing the results from a previous feature detection analysis (see -\code{\link{detectFeatures}}). - -For all other methods: a \code{FeatureDensityParam} object.} - -\item{value}{The value for the slot.} - -\item{param}{A \code{FeatureDensityParam} object containing all settings for -the feature alignment algorithm.} -} -\value{ -The \code{FeatureDensityParam} function returns a -\code{FeatureDensityParam} class instance with all of the settings -specified for feature alignment based on feature densities. - -For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -results of the feature alignment step. These can be accessed with the -\code{\link{featureGroups}} method. -} -\description{ -This method performs performs feature alignment based on the -density (distribution) of identified features along the retention time axis -within slices of overlapping mz ranges. All features (from the same or from -different samples) being close on the retention time axis are grouped into -a \emph{feature group}. - -The \code{FeatureDensityParam} class allows to specify all -settings for the feature alignment based on feature densities along the time -dimension. Instances should be created with the \code{FeatureDensityParam} -constructor. - -\code{sampleGroups},\code{sampleGroups<-}: getter and setter -for the \code{sampleGroups} slot of the object. - -\code{bw},\code{bw<-}: getter and setter for the \code{bw} slot -of the object. - -\code{minFraction},\code{minFraction<-}: getter and setter for -the \code{minFraction} slot of the object. - -\code{minSamples},\code{minSamples<-}: getter and setter for the -\code{minSamples} slot of the object. - -\code{binSize},\code{binSize<-}: getter and setter for the -\code{binSize} slot of the object. - -\code{maxFeatures},\code{maxFeatures<-}: getter and setter for -the \code{maxFeatures} slot of the object. - -\code{groupFeatures,XCMSnExp,FeatureDensityParam}: -performs feature alignment (within and across samples) within in mz dimension -overlapping slices of MS data based on the density distribution of the -identified features in the slice along the time axis. -} -\section{Slots}{ - -\describe{ -\item{\code{.__classVersion__,sampleGroups,bw,minFraction,minSamples,binSize,maxFeatures}}{See corresponding parameter above. \code{.__classVersion__} stores -the version from the class. Slots values should exclusively be accessed -\emph{via} the corresponding getter and setter methods listed above.} -}} -\note{ -These methods and classes are part of the updated and modernized -\code{xcms} user interface which will eventually replace the -\code{\link{group}} methods. All of the settings to the alignment algorithm -can be passed with a \code{FeatureDensityParam} object. - -Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause -all eventually present previous alignment results to be dropped. -} -\examples{ - -## Create a FeatureDensityParam object -p <- FeatureDensityParam(binSize = 0.05) -## Change hte minSamples slot -minSamples(p) <- 3 -p - -############################## -## feature detection and alignment. -## -## Below we perform first a feature detection (using the matchedFilter -## method) on some of the test files from the faahKO package followed by -## a feature alignment using the density method. -library(faahKO) -library(MSnbase) -fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, - full.names = TRUE) - -## Reading 2 of the KO samples -raw_data <- readMSData2(fls[1:2]) - -## Perform the feature detection using the matchedFilter method. -mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -res <- detectFeatures(raw_data, param = mfp) - -head(features(res)) -## The number of features identified per sample: -table(features(res)[, "sample"]) - -## Performing the feature alignment -fdp <- FeatureDensityParam() -res <- groupFeatures(res, fdp) - -## The results from the feature alignment: -featureGroups(res) - -## Using the groupval method to extract a matrix with the intensities of -## the feature groups per sample. -head(groupval(res, value = "into")) - -## The process history: -processHistory(res) -} -\author{ -Colin Smith, Johannes Rainer -} -\references{ -Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and -Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite -Profiling Using Nonlinear Peak Alignment, Matching, and Identification" -\emph{Anal. Chem.} 2006, 78:779-787. -} -\seealso{ -The \code{\link{do_groupFeatures_density}} core -API function and \code{\link{group.density}} for the old user interface. - -\code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -for methods to access feature grouping results. - -\code{\link{XCMSnExp}} for the object containing the results of -the feature alignment. - -Other feature alignment methods: \code{\link{groupFeatures-mzClust}}, - \code{\link{groupFeatures-nearest}}, - \code{\link{groupFeatures}} -} - diff --git a/man/groupFeatures-nearest.Rd b/man/groupFeatures-nearest.Rd deleted file mode 100644 index ff768e774..000000000 --- a/man/groupFeatures-nearest.Rd +++ /dev/null @@ -1,198 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DataClasses.R, R/functions-Params.R, R/methods-Params.R, R/methods-XCMSnExp.R -\docType{class} -\name{groupFeatures-nearest} -\alias{NearestFeaturesParam} -\alias{NearestFeaturesParam-class} -\alias{absMz,NearestFeaturesParam-method} -\alias{absMz<-,NearestFeaturesParam-method} -\alias{absRt} -\alias{absRt,NearestFeaturesParam-method} -\alias{absRt<-} -\alias{absRt<-,NearestFeaturesParam-method} -\alias{groupFeatures,XCMSnExp,NearestFeaturesParam-method} -\alias{groupFeatures-nearest} -\alias{kNN} -\alias{kNN,NearestFeaturesParam-method} -\alias{kNN<-} -\alias{kNN<-,NearestFeaturesParam-method} -\alias{mzVsRtBalance} -\alias{mzVsRtBalance,NearestFeaturesParam-method} -\alias{mzVsRtBalance<-} -\alias{mzVsRtBalance<-,NearestFeaturesParam-method} -\alias{sampleGroups,NearestFeaturesParam-method} -\alias{sampleGroups<-,NearestFeaturesParam-method} -\alias{show,NearestFeaturesParam-method} -\title{Feature alignment based on proximity in the mz-rt space} -\usage{ -NearestFeaturesParam(sampleGroups = numeric(), mzVsRtBalance = 10, - absMz = 0.2, absRt = 15, kNN = 10) - -\S4method{show}{NearestFeaturesParam}(object) - -\S4method{sampleGroups}{NearestFeaturesParam}(object) - -\S4method{sampleGroups}{NearestFeaturesParam}(object) <- value - -\S4method{mzVsRtBalance}{NearestFeaturesParam}(object) - -\S4method{mzVsRtBalance}{NearestFeaturesParam}(object) <- value - -\S4method{absMz}{NearestFeaturesParam}(object) - -\S4method{absMz}{NearestFeaturesParam}(object) <- value - -\S4method{absRt}{NearestFeaturesParam}(object) - -\S4method{absRt}{NearestFeaturesParam}(object) <- value - -\S4method{kNN}{NearestFeaturesParam}(object) - -\S4method{kNN}{NearestFeaturesParam}(object) <- value - -\S4method{groupFeatures}{XCMSnExp,NearestFeaturesParam}(object, param) -} -\arguments{ -\item{sampleGroups}{A vector of the same length than samples defining the -sample group assignments.} - -\item{mzVsRtBalance}{numeric(1) representing the factor by which mz values are -multiplied before calculating the (euclician) distance between two features.} - -\item{absMz}{numeric(1) maximum tolerated distance for mz values.} - -\item{absRt}{numeric(1) maximum tolerated distance for rt values.} - -\item{kNN}{numeric(1) representing the number of nearest neighbors to check.} - -\item{object}{For \code{groupFeatures}: an \code{\link{XCMSnExp}} object -containing the results from a previous feature detection analysis (see -\code{\link{detectFeatures}}). - -For all other methods: a \code{NearestFeaturesParam} object.} - -\item{value}{The value for the slot.} - -\item{param}{A \code{NearestFeaturesParam} object containing all settings for -the feature alignment algorithm.} -} -\value{ -The \code{NearestFeaturesParam} function returns a -\code{NearestFeaturesParam} class instance with all of the settings -specified for high resolution single spectra feature alignment. - -For \code{groupFeatures}: a \code{\link{XCMSnExp}} object with the -results of the feature alignment step. These can be accessed with the -\code{\link{featureGroups}} method. -} -\description{ -This method is inspired by the alignment algorithm of mzMine -[Katajamaa 2006] and performs alignment based on proximity of features in the -space spanned by retention time and mz values. -The method creates first a \emph{master feature list} consisting of all -features from the sample in which most features were identified, and -starting from that, calculates distances to features from the sample with the -next most features. If features are closer than the defined threshold they -are grouped together. - -The \code{NearestFeaturesParam} class allows to specify all -settings for the feature alignment based on the \emph{nearest} algorithm. -Instances should be created with the \code{NearestFeaturesParam} constructor. - -\code{sampleGroups},\code{sampleGroups<-}: getter and setter -for the \code{sampleGroups} slot of the object. - -\code{mzVsRtBalance},\code{mzVsRtBalance<-}: getter and setter -for the \code{mzVsRtBalance} slot of the object. - -\code{absMz},\code{absMz<-}: getter and setter for the -\code{absMz} slot of the object. - -\code{absRt},\code{absRt<-}: getter and setter for the -\code{absRt} slot of the object. - -\code{kNN},\code{kNN<-}: getter and setter for the -\code{kNN} slot of the object. - -\code{groupFeatures,XCMSnExp,NearestFeaturesParam}: -performs feature alignment based on the proximity between features from -different samples in the mz-rt range. -} -\section{Slots}{ - -\describe{ -\item{\code{.__classVersion__,sampleGroups,mzVsRtBalance,absMz,absRt,kNN}}{See corresponding parameter above. \code{.__classVersion__} stores -the version from the class. Slots values should exclusively be accessed -\emph{via} the corresponding getter and setter methods listed above.} -}} -\note{ -These methods and classes are part of the updated and modernized -\code{xcms} user interface which will eventually replace the -\code{\link{group}} methods. All of the settings to the alignment algorithm -can be passed with a \code{NearestFeaturesParam} object. - -Calling \code{groupFeatures} on an \code{XCMSnExp} object will cause -all eventually present previous alignment results to be dropped. -} -\examples{ - -## Create a NearestFeaturesParam object -p <- NearestFeaturesParam(kNN = 3) -p - -############################## -## feature detection and alignment. -## -## Below we perform first a feature detection (using the matchedFilter -## method) on some of the test files from the faahKO package followed by -## a feature alignment using the "nearest" method. -library(faahKO) -library(MSnbase) -fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE, - full.names = TRUE) - -## Reading 2 of the KO samples -raw_data <- readMSData2(fls[1:2]) - -## Perform the feature detection using the matchedFilter method. -mfp <- MatchedFilterParam(snthresh = 20, binSize = 1) -res <- detectFeatures(raw_data, param = mfp) - -head(features(res)) -## The number of features identified per sample: -table(features(res)[, "sample"]) - -## Performing the feature alignment -p <- NearestFeaturesParam() -res <- groupFeatures(res, param = p) - -## The results from the feature alignment: -featureGroups(res) - -## Using the groupval method to extract a matrix with the intensities of -## the feature groups per sample. -head(groupval(res, value = "into")) - -## The process history: -processHistory(res) -} -\references{ -Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for -processing and visualization of mass spectrometry based molecular profile -data. \emph{Bioinformatics} 2006, 22:634-636. -} -\seealso{ -The \code{\link{do_groupFeatures_nearest}} core -API function and \code{\link{group.nearest}} for the old user interface. - -\code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -for methods to access feature grouping results. - -\code{\link{XCMSnExp}} for the object containing the results of -the feature alignment. - -Other feature alignment methods: \code{\link{groupFeatures-density}}, - \code{\link{groupFeatures-mzClust}}, - \code{\link{groupFeatures}} -} - diff --git a/man/groupFeatures.Rd b/man/groupFeatures.Rd deleted file mode 100644 index f72c13df5..000000000 --- a/man/groupFeatures.Rd +++ /dev/null @@ -1,38 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DataClasses.R -\name{groupFeatures} -\alias{groupFeatures} -\title{Feature alignment methods.} -\description{ -The \code{groupFeatures} method(s) perform alignment of features -within and between samples. These methods are part of the modernized -\code{xcms} user interface. - -The implemented feature alignment methods are: -\describe{ -\item{density}{feature alignment based on time dimension feature densities. -See \code{\link{groupFeatures-density}} for more details.} - -\item{mzClust}{high resolution feature alignment for single spectra (direct -infusion) MS data. See \code{\link{groupFeatures-mzClust}} for more details.} - -\item{nearest}{feature alignment based on their proximity in the mz-rt space. -See \code{\link{groupFeatures-nearest}} for more details.} - -} -} -\author{ -Johannes Rainer -} -\seealso{ -\code{\link{group}} for the \emph{old} feature alignment -methods. - -\code{\link{featureGroups}} and \code{\link{groupval,XCMSnExp-method}} -for methods to access feature grouping results. - -Other feature alignment methods: \code{\link{groupFeatures-density}}, - \code{\link{groupFeatures-mzClust}}, - \code{\link{groupFeatures-nearest}} -} - diff --git a/man/showError-xcmsSet-method.Rd b/man/showError-xcmsSet-method.Rd index 939f4002f..1de61c40d 100644 --- a/man/showError-xcmsSet-method.Rd +++ b/man/showError-xcmsSet-method.Rd @@ -21,7 +21,7 @@ A list of error messages (if \code{message. = TRUE}) or errors or an empty list if no errors are present. } \description{ -If feature detection is performed with \code{\link{findPeaks}} +If peak detection is performed with \code{\link{findPeaks}} setting argument \code{stopOnError = FALSE} eventual errors during the process do not cause to stop the processing but are recorded inside of the resulting \code{\linkS4class{xcmsSet}} object. These errors can be accessed diff --git a/man/useOriginalCode.Rd b/man/useOriginalCode.Rd index 9e94f5f57..d031bb970 100644 --- a/man/useOriginalCode.Rd +++ b/man/useOriginalCode.Rd @@ -23,7 +23,7 @@ details for functions affected. \details{ The functions/methods that will be affected by this are: \itemize{ -\item \code{\link{do_detectFeatures_matchedFilter}} +\item \code{\link{do_findChromPeaks_matchedFilter}} } } \note{ diff --git a/tests/doRUnit.R b/tests/doRUnit.R index 74a3d4212..334dedf45 100644 --- a/tests/doRUnit.R +++ b/tests/doRUnit.R @@ -42,7 +42,7 @@ if(require("RUnit", quietly=TRUE)) { faahko_od <- readMSData2(faahko_3_files) ## Feature alignment on those: - faahko_xod <- detectFeatures(faahko_od, param = CentWaveParam(noise = 10000, + faahko_xod <- findChromPeaks(faahko_od, param = CentWaveParam(noise = 10000, snthresh = 40)) faahko_xs <- xcmsSet(faahko_3_files, profparam = list(step = 0), method = "centWave", noise = 10000, snthresh = 40) diff --git a/vignettes/new_functionality.Rmd b/vignettes/new_functionality.Rmd index 5494c3806..2e3d715fd 100644 --- a/vignettes/new_functionality.Rmd +++ b/vignettes/new_functionality.Rmd @@ -40,61 +40,61 @@ library(RColorBrewer) The modernization of the user interface comprises new classes for data representation and new data analysis methods. In addition, the core logic for the data processing has been extracted from the old methods and put into a set -of R functions, the so called core API functions (or `do_` functions), that take -standard R data structures as input and can hence also easily be included in -other R packages. The new user interface aims at simplifying and streamlining -the `xcms` workflow while guaranteeing data integrity and performance also for -large scale metabolomics experiments. All objects in the new user interface -ensuring data integrity *via* validation methods and class versioning, all methods -are tested internally in extensive unit tests to guarantee proper functionality. - -In the new user interface, objects from the `MSnbase` Bioconductor package are -used, namely the `OnDiskMSnExp` object. This object is specifically designed for -large scale experiments by just loading basic information from the raw files and -reading the actual spectra data (mz and intensity values) on demand from the -files. In contrast to the old `xcmsRaw` objects this object contains information -from all files of an experiment. In addition, by using this object from the -`MSnbase` package as container for the raw data, data normalization and adjustment -methods defined for this class can be applied directly without having them to be -re-implemented in the `xcms` package. In the new user interface the results from -the pre-processing steps are stored in a new results object, the `XCMSnExp` -object. This is similar to the old `xcmsSet` object, but by extending the -`OnDiskMSnExp` object it inherits all of its methods and hence provides a simple -and streamlined access to the (raw) data on which the processing was performed. - -For feature detection (peak calling), and thus replacing the `findPeaks.*` -methods, the `detectFeatures` method has been implemented. The reason for -changing the name from `findPeaks` to `detectFeatures` was to discriminate *peak* -(i.e. mass peak mostly used in proteomics), from *feature* (which describes a peak -in chromatographic space). The `detectFeatures` method performs dispatching to -the various algorithms (e.g. *centWave*, *matchedFilter*) based on a parameter class -submitted *via* the `param` argument. This encapsulation of the parameters to a +of R functions, the so called core API functions (or `do_` functions). These +functions take standard R data structures as input and return standard R data +types as result and can hence be easily included in other R packages. + +Over and above, the new user interface aims at simplifying and streamlining the +`xcms` workflow while guaranteeing data integrity and performance also for large +scale metabolomics experiments. An important aspect was also to enable an easy +access to the raw data files. + +The new interface re-uses objects from the `MSnbase` Bioconductor package, such as +the `OnDiskMSnExp` object. This object is specifically designed for large scale MS +experiments as it initially reads just the scan header information from the mzML +while the mz-intensity value pairs from all or from selected spectra of a file +or are read on demand hence minimizing the memory footprint. Also in contrast to +the old `xcmsRaw` object the `OnDiskMSnExp` contains information from all files of +an experiment. In addition, all data normalization and adjustment methods +implemented in the `MSnbase` package can be directly applied to the MS data +without the need to re-implement such methods in `xcms`. Results from `xcms` +preprocessings, such as chromatographic peak detection or correspondence are +stored into the new `XCMSnExp` object. This object extends the `OnDiskMSnExp` object +and enables thus an easy access of the raw data on which the preprocessing was +performed. + +Class and method/function names follow also a new naming convention and avoid +the partially confusing nomenclature of the original `xcms` methods. To +distinguish them from mass peaks, the peaks identified by the peak detection in +an LS/GC-MS experiment are referred to as *chromatographic peaks*. The respective +method to identify such peaks is hence called `findChromPeaks` and the identified +peaks can be accessed using the `XCMSnExp` `chromPeaks` method. The results from an +correspondence analysis which aims to match and group chromatographic peaks +within and between samples are called *features*. The definition of such mz-rt +features (i.e. the result from the `groupChromPeaks` method) can be accessed *via* +the `featureDefinitions` method of the `XCMSnExp` class. Finally, alignment +(retention time correction) can be performed using the `adjustRtime` method. + +The settings for any of the new analysis methods are bundled in *parameter* +classes, one class for each method. This encapsulation of the parameters to a function into a parameter class (such as `CentWaveParam`) avoids busy function -calls (with many single parameters to specify) and enables saving, reloading and -reusing settings as well as, by adding them to the result objects, enabling the -documentation of the data processing history. In addition, parameter validation -can be performed within the parameter object and hence is no longer required in -the analysis function. - -The implementation of the `detectFeatures` method for `OnDiskMSnExp` and `MSnExp` -objects (from the `MSnbase` package) enable feature detection on these types of -objects that represent the full MS data of an experiment along with all -experiment relevant metadata. Loading the files first into an `MSnExp` or -`OnDiskMSnExp` (the latter being specifically designed for large scale -experiments) enables a first data inspection and quality assessment, followed by -eventual subsetting and filtering (e.g. on retention time) before performing the -feature detection on the thus processed data. - -Below we load the raw data files from the `faahKO` package as an `OnDiskMSnExp` -object using the `readMSData2` function from the `MSnbase` package. +calls (with many single parameters) and enables saving, reloading and reusing +the settings. In addition, the parameter classes are added, along with other +information to the process history of an `XCMSnExp` object thus providing a +detailed documentation of each processing step of an analysis. In addition, +validation of the parameters can be performed within the parameter object and +hence is no longer required in the analysis function. + +The example below illustrates the new user interface. First we load the raw data +files from the `faahKO` package using the `readMSData2` from the `MSnbase` package. ```{r message = FALSE, warning = FALSE} ## Reading the raw data using the MSnbase package library(MSnbase) library(xcms) -## Load the CDF files from the faahKO +## Load 6 of the CDF files from the faahKO cdf_files <- dir(system.file("cdf", package = "faahKO"), recursive = TRUE, - full.names = TRUE) + full.names = TRUE)[c(1:3, 7:9)] ## Define the sample grouping. s_groups <- rep("KO", length(cdf_files)) @@ -109,9 +109,10 @@ raw_data <- readMSData2(cdf_files, pdata = new("NAnnotatedDataFrame", pheno)) ``` We next plot the total ion chromatogram (TIC) for all files within the -experiment. Note that we are iteratively sub-setting the full data per file, -which for `OnDiskMSnExp` is an efficient way to subset the data while ensuring -that all data, including metadata, stays consistent. +experiment. Note that we are iteratively sub-setting the full data per file +using the `filterFile` method, which, for `OnDiskMSnExp` objects, is an efficient +way to subset the data while ensuring that all data, including metadata, stays +consistent. ```{r faahKO-tic, message = FALSE, fig.align = 'center', fig.width = 8, fig.height = 4} library(RColorBrewer) @@ -120,17 +121,26 @@ names(sample_colors) <- c("KO", "WT") ## Subset the full raw data by file and plot the data. tmp <- filterFile(raw_data, file = 1) plot(x = rtime(tmp), y = tic(tmp), xlab = "retention time", ylab = "TIC", - col = sample_colors[pData(tmp)$sample_group], type = "l") + col = paste0(sample_colors[pData(tmp)$sample_group], 80), type = "l") for (i in 2:length(fileNames(raw_data))) { tmp <- filterFile(raw_data, file = i) points(rtime(tmp), tic(tmp), type = "l", - col = sample_colors[pData(tmp)$sample_group]) + col = paste0(sample_colors[pData(tmp)$sample_group], 80)) } legend("topleft", col = sample_colors, legend = names(sample_colors), lty = 1) ``` -- Do the feature detection. -- Describe the feature detection methods. +In addition we can plot the distribution of the total ion counts per file. + +The `tic` (and for mzML files) the `bpi` methods are very fast, even for large data +sets, as these information are stored in the header of the raw files avoiding +the need to read the raw data from each file. + +- Do the chromatographic peak detection. + +- Describe the peak detection methods. + +- Describe subsetting methods filter etc. ## New naming convention @@ -138,17 +148,19 @@ legend("topleft", col = sample_colors, legend = names(sample_colors), lty = 1) Methods for data analysis from the original `xcms` code have been renamed to avoid potential confusions: -- `detectFeatures` instead of `findPeaks`: for new functions and methods the term - *peak* is avoided as much as possible, as it is usually used to describe a mass - peak in mz dimension. To clearly distinguish between these peaks and peaks in - retention time space, the latter are referred to as *features*. +- **Chromatographic peak detection**: `findChromPeaks` instead of `findPeaks`: for new + functions and methods the term *peak* is avoided as much as possible, as it is + usually used to describe a mass peak in mz dimension. To clearly distinguish + between these peaks and peaks in retention time space, the latter are referred + to as *chromatographic peak*, or `chromPeak`. -- `groupFeatures` instead of `group` to clearly indicate what is being - grouped. Group might be a sample group or a feature group, hence groups of - features are always referred to as *feature groups*. +- **Correspondence**: `groupChromPeaks` instead of `group` to clearly indicate what is + being grouped. Group might be a sample group or a peak group, the latter being + referred to also by (mz-rt) *feature*. -- `adjustRtime` instead of `retcor` for retention time correction. The word *cor* in - *retcor* might be easily misinterpreted as *correlation* instead of correction. +- **Alignment**: `adjustRtime` instead of `retcor` for retention time correction. The + word *cor* in *retcor* might be easily misinterpreted as *correlation* instead of + correction. ## New data classes @@ -169,11 +181,12 @@ represents a container for the xcms-based preprocessing results while (since it inherits all functionality from its parent class) keeping a direct relation to the (raw) data on which the processing was performed. An additional slot `.processHistory` in the object allows to keep track of all performed processing -steps. Each analysis method, such as `detectFeatures` adds an `XProcessHistory` +steps. Each analysis method, such as `findChromPeaks` adds an `XProcessHistory` object which includes also the parameter class passed to the analysis method. Hence not only the time and type of the analysis, but its exact settings are reported within the `XCMSnExp` object. The `XCMSnExp` is thus equivalent to the -`xcmsSet` from the original `xcms` implementation. +`xcmsSet` from the original `xcms` implementation, but keeps in addition a link to +the raw data on which the preprocessing was performed. ## Binning and missing value imputation functions @@ -259,24 +272,24 @@ set to a base value corresponding to half of the smallest bin value. Both methods thus yield same results, except for bins 15-17 (see Figure above). -## Core feature detection functions +## Core chromatographic peak detection functions -The core logic from the feature detection methods `findPeaks.centWave`, +The core logic from the chromatographic peak detection methods `findPeaks.centWave`, `findPeaks.massifquant`, `findPeaks.matchedFilter` has been extracted and put into -functions with the common prefix `do_detectFeatures` with the aim, as detailed in +functions with the common prefix `do_findChromPeaks` with the aim, as detailed in issue [#30](https://github.com/sneumann/xcms/issues/30), to separate the core logic from the analysis methods invoked by the -users to enable also the use of the feature detection functions using base R +users to enable also the use of the peak detection functions using base R parameters (i.e. without specific classes containing the data such as the `xcmsRaw` class). This simplifies also the re-use of these functions in other -packages and simplifies the future implementation of the feature detection +packages and simplifies the future implementation of the peak detection algorithms for e.g. the `MSnExp` or `OnDiskMSnExp` objects from the `MSnbase` Bioconductor package. The implemented functions are: -- `do_detectFeatures_centWave`: peak density and wavelet based feature detection +- `do_findChromPeaks_centWave`: peak density and wavelet based peak detection for high resolution LC/MS data in centroid mode [@Tautenhahn:2008fx]. -- `do_detectFeatures_matchedFilter`: identification of features in the +- `do_findChromPeaks_matchedFilter`: identification of peak in the chromatographic domain based on matched filtration [@Smith:2006ic]. -- `do_detectFeatures_massifquant`: identification of features using Kalman +- `do_findChromPeaks_massifquant`: identification of peaks using Kalman filters. One possible drawback from the introduction of this new layer is, that more @@ -357,11 +370,11 @@ the beginning and the end of the provided numeric vector. This can be disabled `TRUE` (like in the example above). -## Differences due to updates in `do_detectFeatures_matchedFilter`, respectively `findPeaks.matchedFilter`. +## Differences due to updates in `do_findChromPeaks_matchedFilter`, respectively `findPeaks.matchedFilter`. The original `findPeaks.matchedFilter` (up to version 1.49.7) had several shortcomings and bugs that have been fixed in the new -`do_detectFeatures_matchedFilter` method: +`do_findChromPeaks_matchedFilter` method: - The internal iterative processing of smaller chunks of the full data (also referred to as *iterative buffering*) could result, for some bin (step) sizes to @@ -378,7 +391,7 @@ shortcomings and bugs that have been fixed in the new - The `profBinLin` implementation contains two bugs, one that can result in failing to identify the maximal value in the first and last bin (see issue [#46](https://github.com/sneumann/xcms/issues/46)) and one that fails to assign a value to a bin (issue [#49](https://github.com/sneumann/xcms/issues/49)). Both are fixed - in the `do_detectFeatures_matchedFilter` implementation. + in the `do_findChromPeaks_matchedFilter` implementation. A detailed description of tests comparing all implementations is available in issue [#52](https://github.com/sneumann/xcms/issues/52) on github. Note also that in course of these changes also the `getEIC` @@ -405,23 +418,23 @@ binning and linear interpolation methods. Thus results might be slightly different. -## `retcor.peaksgroups`: change in the way how *well behaved* feature groups are ordered +## `retcor.peaksgroups`: change in the way how *well behaved* peak groups are ordered -The `retcor.peakgroups` defines first the feature groups (peaks groups) that are +The `retcor.peakgroups` defines first the chromatographic peak groups that are used for the alignment of all spectra. Once these are identified, the retention -time of the feature with the highest intensity in a sample for a given feature -group is returned and the feature groups are ordered increasingly by retention -time (which is required for the later fitting of either a polynomial or a linear -model to the data). The selection of the retention time of the feature with the -highest intensity within a feature group and samples, denoted as *representative* -feature for a given feature group in a sample, ensures that only the retention -time of a single feature per sample and feature group is selected (multiple -features within the same sample can be assigned to a feature group). In the -original code the ordering of the feature groups was however performed using the -median retention time of the complete feature group (which includes also -potential additional features per sample). This has been changed and the feature -groups are ordered now by the median retention time across samples of the -representative features. +time of the peak with the highest intensity in a sample for a given peak group +is returned and the peak groups are ordered increasingly by retention time +(which is required for the later fitting of either a polynomial or a linear +model to the data). The selection of the retention time of the peak with the +highest intensity within a feature (peak group) and samples, denoted as +*representative* peak for a given feature in a sample, ensures that only the +retention time of a single peak per sample and feature is selected (note that +multiple chromatographic peaks within the same sample can be assigned to a +feature). In the original code the ordering of the peak groups was however +performed using the median retention time of the complete peak group (which +includes also potential additional peaks per sample). This has been changed and +the features are ordered now by the median retention time across samples of the +representative chromatographic peaks. ## `scanrange` parameter in all `findPeaks` methods diff --git a/vignettes/new_functionality.org b/vignettes/new_functionality.org index 6a6ac2ba5..4f24a2d22 100644 --- a/vignettes/new_functionality.org +++ b/vignettes/new_functionality.org @@ -49,61 +49,65 @@ in the =xcms= package introduced during the update to version /3/. The modernization of the user interface comprises new classes for data representation and new data analysis methods. In addition, the core logic for the data processing has been extracted from the old methods and put into a set -of R functions, the so called core API functions (or =do_= functions), that take -standard R data structures as input and can hence also easily be included in -other R packages. The new user interface aims at simplifying and streamlining -the =xcms= workflow while guaranteeing data integrity and performance also for -large scale metabolomics experiments. All objects in the new user interface -ensuring data integrity /via/ validation methods and class versioning, all methods -are tested internally in extensive unit tests to guarantee proper functionality. - -In the new user interface, objects from the =MSnbase= Bioconductor package are -used, namely the =OnDiskMSnExp= object. This object is specifically designed for -large scale experiments by just loading basic information from the raw files and -reading the actual spectra data (mz and intensity values) on demand from the -files. In contrast to the old =xcmsRaw= objects this object contains information -from all files of an experiment. In addition, by using this object from the -=MSnbase= package as container for the raw data, data normalization and adjustment -methods defined for this class can be applied directly without having them to be -re-implemented in the =xcms= package. In the new user interface the results from -the pre-processing steps are stored in a new results object, the =XCMSnExp= -object. This is similar to the old =xcmsSet= object, but by extending the -=OnDiskMSnExp= object it inherits all of its methods and hence provides a simple -and streamlined access to the (raw) data on which the processing was performed. - -For feature detection (peak calling), and thus replacing the =findPeaks.*= -methods, the =detectFeatures= method has been implemented. The reason for -changing the name from =findPeaks= to =detectFeatures= was to discriminate /peak/ -(i.e. mass peak mostly used in proteomics), from /feature/ (which describes a peak -in chromatographic space). The =detectFeatures= method performs dispatching to -the various algorithms (e.g. /centWave/, /matchedFilter/) based on a parameter class -submitted /via/ the =param= argument. This encapsulation of the parameters to a +of R functions, the so called core API functions (or =do_= functions). These +functions take standard R data structures as input and return standard R data +types as result and can hence be easily included in other R packages. + +Over and above, the new user interface aims at simplifying and streamlining the +=xcms= workflow while guaranteeing data integrity and performance also for large +scale metabolomics experiments. An important aspect was also to enable an easy +access to the raw data files. + +# All objects in the new user interface ensuring +# data integrity /via/ validation methods and class versioning, all methods are +# tested internally in extensive unit tests to guarantee proper functionality. + +The new interface re-uses objects from the =MSnbase= Bioconductor package, such as +the =OnDiskMSnExp= object. This object is specifically designed for large scale MS +experiments as it initially reads just the scan header information from the mzML +while the mz-intensity value pairs from all or from selected spectra of a file +or are read on demand hence minimizing the memory footprint. Also in contrast to +the old =xcmsRaw= object the =OnDiskMSnExp= contains information from all files of +an experiment. In addition, all data normalization and adjustment methods +implemented in the =MSnbase= package can be directly applied to the MS data +without the need to re-implement such methods in =xcms=. Results from =xcms= +preprocessings, such as chromatographic peak detection or correspondence are +stored into the new =XCMSnExp= object. This object extends the =OnDiskMSnExp= object +and enables thus an easy access of the raw data on which the preprocessing was +performed. + +Class and method/function names follow also a new naming convention and avoid +the partially confusing nomenclature of the original =xcms= methods. To +distinguish them from mass peaks, the peaks identified by the peak detection in +an LS/GC-MS experiment are referred to as /chromatographic peaks/. The respective +method to identify such peaks is hence called =findChromPeaks= and the identified +peaks can be accessed using the =XCMSnExp= =chromPeaks= method. The results from an +correspondence analysis which aims to match and group chromatographic peaks +within and between samples are called /features/. The definition of such mz-rt +features (i.e. the result from the =groupChromPeaks= method) can be accessed /via/ +the =featureDefinitions= method of the =XCMSnExp= class. Finally, alignment +(retention time correction) can be performed using the =adjustRtime= method. + +The settings for any of the new analysis methods are bundled in /parameter/ +classes, one class for each method. This encapsulation of the parameters to a function into a parameter class (such as =CentWaveParam=) avoids busy function -calls (with many single parameters to specify) and enables saving, reloading and -reusing settings as well as, by adding them to the result objects, enabling the -documentation of the data processing history. In addition, parameter validation -can be performed within the parameter object and hence is no longer required in -the analysis function. - -The implementation of the =detectFeatures= method for =OnDiskMSnExp= and =MSnExp= -objects (from the =MSnbase= package) enable feature detection on these types of -objects that represent the full MS data of an experiment along with all -experiment relevant metadata. Loading the files first into an =MSnExp= or -=OnDiskMSnExp= (the latter being specifically designed for large scale -experiments) enables a first data inspection and quality assessment, followed by -eventual subsetting and filtering (e.g. on retention time) before performing the -feature detection on the thus processed data. - -Below we load the raw data files from the =faahKO= package as an =OnDiskMSnExp= -object using the =readMSData2= function from the =MSnbase= package. +calls (with many single parameters) and enables saving, reloading and reusing +the settings. In addition, the parameter classes are added, along with other +information to the process history of an =XCMSnExp= object thus providing a +detailed documentation of each processing step of an analysis. In addition, +validation of the parameters can be performed within the parameter object and +hence is no longer required in the analysis function. + +The example below illustrates the new user interface. First we load the raw data +files from the =faahKO= package using the =readMSData2= from the =MSnbase= package. #+BEGIN_SRC R :ravel message = FALSE, warning = FALSE ## Reading the raw data using the MSnbase package library(MSnbase) library(xcms) - ## Load the CDF files from the faahKO + ## Load 6 of the CDF files from the faahKO cdf_files <- dir(system.file("cdf", package = "faahKO"), recursive = TRUE, - full.names = TRUE) + full.names = TRUE)[c(1:3, 7:9)] ## Define the sample grouping. s_groups <- rep("KO", length(cdf_files)) @@ -118,9 +122,10 @@ object using the =readMSData2= function from the =MSnbase= package. #+END_SRC We next plot the total ion chromatogram (TIC) for all files within the -experiment. Note that we are iteratively sub-setting the full data per file, -which for =OnDiskMSnExp= is an efficient way to subset the data while ensuring -that all data, including metadata, stays consistent. +experiment. Note that we are iteratively sub-setting the full data per file +using the =filterFile= method, which, for =OnDiskMSnExp= objects, is an efficient +way to subset the data while ensuring that all data, including metadata, stays +consistent. #+NAME: faahKO-tic #+BEGIN_SRC R :ravel message = FALSE, fig.align = 'center', fig.width = 8, fig.height = 4 @@ -130,34 +135,46 @@ that all data, including metadata, stays consistent. ## Subset the full raw data by file and plot the data. tmp <- filterFile(raw_data, file = 1) plot(x = rtime(tmp), y = tic(tmp), xlab = "retention time", ylab = "TIC", - col = sample_colors[pData(tmp)$sample_group], type = "l") + col = paste0(sample_colors[pData(tmp)$sample_group], 80), type = "l") for (i in 2:length(fileNames(raw_data))) { tmp <- filterFile(raw_data, file = i) points(rtime(tmp), tic(tmp), type = "l", - col = sample_colors[pData(tmp)$sample_group]) + col = paste0(sample_colors[pData(tmp)$sample_group], 80)) } legend("topleft", col = sample_colors, legend = names(sample_colors), lty = 1) #+END_SRC -+ Do the feature detection. -+ Describe the feature detection methods. +In addition we can plot the distribution of the total ion counts per file. + + +The =tic= (and for mzML files) the =bpi= methods are very fast, even for large data +sets, as these information are stored in the header of the raw files avoiding +the need to read the raw data from each file. + ++ Do the chromatographic peak detection. + ++ Describe the peak detection methods. + ++ Describe subsetting methods filter etc. ** New naming convention Methods for data analysis from the original =xcms= code have been renamed to avoid potential confusions: -+ =detectFeatures= instead of =findPeaks=: for new functions and methods the term - /peak/ is avoided as much as possible, as it is usually used to describe a mass - peak in mz dimension. To clearly distinguish between these peaks and peaks in - retention time space, the latter are referred to as /features/. ++ *Chromatographic peak detection*: =findChromPeaks= instead of =findPeaks=: for new + functions and methods the term /peak/ is avoided as much as possible, as it is + usually used to describe a mass peak in mz dimension. To clearly distinguish + between these peaks and peaks in retention time space, the latter are referred + to as /chromatographic peak/, or =chromPeak=. -+ =groupFeatures= instead of =group= to clearly indicate what is being - grouped. Group might be a sample group or a feature group, hence groups of - features are always referred to as /feature groups/. ++ *Correspondence*: =groupChromPeaks= instead of =group= to clearly indicate what is + being grouped. Group might be a sample group or a peak group, the latter being + referred to also by (mz-rt) /feature/. -+ =adjustRtime= instead of =retcor= for retention time correction. The word /cor/ in - /retcor/ might be easily misinterpreted as /correlation/ instead of correction. ++ *Alignment*: =adjustRtime= instead of =retcor= for retention time correction. The + word /cor/ in /retcor/ might be easily misinterpreted as /correlation/ instead of + correction. ** New data classes @@ -175,11 +192,12 @@ represents a container for the xcms-based preprocessing results while (since it inherits all functionality from its parent class) keeping a direct relation to the (raw) data on which the processing was performed. An additional slot =.processHistory= in the object allows to keep track of all performed processing -steps. Each analysis method, such as =detectFeatures= adds an =XProcessHistory= +steps. Each analysis method, such as =findChromPeaks= adds an =XProcessHistory= object which includes also the parameter class passed to the analysis method. Hence not only the time and type of the analysis, but its exact settings are reported within the =XCMSnExp= object. The =XCMSnExp= is thus equivalent to the -=xcmsSet= from the original =xcms= implementation. +=xcmsSet= from the original =xcms= implementation, but keeps in addition a link to +the raw data on which the preprocessing was performed. ** Binning and missing value imputation functions @@ -263,24 +281,24 @@ of the bin with the missing value (=1= by default). The other missing values are set to a base value corresponding to half of the smallest bin value. Both methods thus yield same results, except for bins 15-17 (see Figure above). -** Core feature detection functions +** Core chromatographic peak detection functions -The core logic from the feature detection methods =findPeaks.centWave=, +The core logic from the chromatographic peak detection methods =findPeaks.centWave=, =findPeaks.massifquant=, =findPeaks.matchedFilter= has been extracted and put into -functions with the common prefix =do_detectFeatures= with the aim, as detailed in +functions with the common prefix =do_findChromPeaks= with the aim, as detailed in issue [[https://github.com/sneumann/xcms/issues/30][#30]], to separate the core logic from the analysis methods invoked by the -users to enable also the use of the feature detection functions using base R +users to enable also the use of the peak detection functions using base R parameters (i.e. without specific classes containing the data such as the =xcmsRaw= class). This simplifies also the re-use of these functions in other -packages and simplifies the future implementation of the feature detection +packages and simplifies the future implementation of the peak detection algorithms for e.g. the =MSnExp= or =OnDiskMSnExp= objects from the =MSnbase= Bioconductor package. The implemented functions are: -+ =do_detectFeatures_centWave=: peak density and wavelet based feature detection ++ =do_findChromPeaks_centWave=: peak density and wavelet based peak detection for high resolution LC/MS data in centroid mode \cite{Tautenhahn:2008fx}. -+ =do_detectFeatures_matchedFilter=: identification of features in the ++ =do_findChromPeaks_matchedFilter=: identification of peak in the chromatographic domain based on matched filtration \cite{Smith:2006ic}. -+ =do_detectFeatures_massifquant=: identification of features using Kalman ++ =do_findChromPeaks_massifquant=: identification of peaks using Kalman filters. One possible drawback from the introduction of this new layer is, that more @@ -358,11 +376,11 @@ the beginning and the end of the provided numeric vector. This can be disabled (to be compliant with =profBinLin=) by setting parameter =noInterpolAtEnds= to =TRUE= (like in the example above). -** Differences due to updates in =do_detectFeatures_matchedFilter=, respectively =findPeaks.matchedFilter=. +** Differences due to updates in =do_findChromPeaks_matchedFilter=, respectively =findPeaks.matchedFilter=. The original =findPeaks.matchedFilter= (up to version 1.49.7) had several shortcomings and bugs that have been fixed in the new -=do_detectFeatures_matchedFilter= method: +=do_findChromPeaks_matchedFilter= method: + The internal iterative processing of smaller chunks of the full data (also referred to as /iterative buffering/) could result, for some bin (step) sizes to @@ -379,7 +397,7 @@ shortcomings and bugs that have been fixed in the new + The =profBinLin= implementation contains two bugs, one that can result in failing to identify the maximal value in the first and last bin (see issue [[https://github.com/sneumann/xcms/issues/46][#46]]) and one that fails to assign a value to a bin (issue [[https://github.com/sneumann/xcms/issues/49][#49]]). Both are fixed - in the =do_detectFeatures_matchedFilter= implementation. + in the =do_findChromPeaks_matchedFilter= implementation. A detailed description of tests comparing all implementations is available in issue [[https://github.com/sneumann/xcms/issues/52][#52]] on github. Note also that in course of these changes also the =getEIC= @@ -404,23 +422,23 @@ binning and linear interpolation methods. Thus results might be slightly different. -** =retcor.peaksgroups=: change in the way how /well behaved/ feature groups are ordered +** =retcor.peaksgroups=: change in the way how /well behaved/ peak groups are ordered -The =retcor.peakgroups= defines first the feature groups (peaks groups) that are +The =retcor.peakgroups= defines first the chromatographic peak groups that are used for the alignment of all spectra. Once these are identified, the retention -time of the feature with the highest intensity in a sample for a given feature -group is returned and the feature groups are ordered increasingly by retention -time (which is required for the later fitting of either a polynomial or a linear -model to the data). The selection of the retention time of the feature with the -highest intensity within a feature group and samples, denoted as /representative/ -feature for a given feature group in a sample, ensures that only the retention -time of a single feature per sample and feature group is selected (multiple -features within the same sample can be assigned to a feature group). In the -original code the ordering of the feature groups was however performed using the -median retention time of the complete feature group (which includes also -potential additional features per sample). This has been changed and the feature -groups are ordered now by the median retention time across samples of the -representative features. +time of the peak with the highest intensity in a sample for a given peak group +is returned and the peak groups are ordered increasingly by retention time +(which is required for the later fitting of either a polynomial or a linear +model to the data). The selection of the retention time of the peak with the +highest intensity within a feature (peak group) and samples, denoted as +/representative/ peak for a given feature in a sample, ensures that only the +retention time of a single peak per sample and feature is selected (note that +multiple chromatographic peaks within the same sample can be assigned to a +feature). In the original code the ordering of the peak groups was however +performed using the median retention time of the complete peak group (which +includes also potential additional peaks per sample). This has been changed and +the features are ordered now by the median retention time across samples of the +representative chromatographic peaks. ** =scanrange= parameter in all =findPeaks= methods @@ -493,8 +511,8 @@ using the =seq= function, but they are not identical. ** Implementation and comparison for =matchedFilter= :noexport: -These results base on the test =dontrun_test_do_detectFeatures_matchedFilter_impl= -defined in /test_do_detectFeatures_matchedFilter.R/ +These results base on the test =dontrun_test_do_findChromPeaks_matchedFilter_impl= +defined in /test_do_findChromPeaks_matchedFilter.R/ We have 4 different functions to test and compare to the original one: + *A*: =.matchedFilter_orig=: it's the original code. @@ -800,5 +818,49 @@ to avoid copying etc of the data. Check also =assayDataElement()= in =MSnbase=. + Alignment information could be implemented as =DataFrame= with the indices added to a column =idx=. +** TODO Rename objects, functions and methods + ++ [X] =features=: =chromPeaks=. ++ [X] =hasDetectedFeatures=: =hasChromPeaks=. ++ [ ] feature: chromatographic peak. ++ [X] =detectFeatures=: =findChromPeaks=. ++ [X] =dropFeatures=: =dropChromPeaks=. ++ [X] featureDetection-centWave: findChromPeaks-centWave ++ [X] =validFeatureMatrix=: =validChromPeaksMatrix=. + +Correspondence. ++ [ ] feature groups: features (aligned and grouped chromatographic peaks). ++ [X] =groupFeatures=: =groupChromPeaks=. ++ [X] =hasAlignedFeatures=: =hasFeatures=. ++ [X] =featureGroups=: =featureDefinitions=, =featureValue= (=groupval=). ++ [X] =FeatureDensityParam=: =PeakDensityParam=. ++ [X] =NearestFeaturesParam=: =NearestPeaksParam= ++ [ ] feature alignment methods: peak alignment methods ++ [X] =$features=: =$chromPeaks=. ++ [X] =featureidx=: =peakidx=. ++ [X] =featureIndex=: =peakIndex=. ++ [X] =dropFeatureGroups=: =dropFeatureDefinitions=. ++ [ ] Peak alignment: Peak grouping ++ [X] =.PROCSTEP.PEAK.ALIGNMENT=: =.PROCSTEP.PEAK.GROUPING=. + +Param classes: ++ [X] =extraFeatures=: =extraPeaks=. + +RT correction. ++ [X] =featureGroups= retention time correction: =peakGroups=. ++ [X] =FeatureGroupsParam=: =PeakGroupsParam=. ++ [X] =features=: =peaks= ++ [X] =featureIndex=: =peakIndex= ++ [X] =getFeatureGroupsRtMatrix=: =getPeakGroupsRtMatrix= ++ [X] =applyRtAdjToFeatures=: =applyRtAdjToPeaks=. ++ [X] =do_groupFeatures_mzClust=: =do_groupPeaks_mzClust=. + ++ [X] Check =maxFeatures= parameter for =do_groupChromPeaks_density=. Is it really + the maximum number of features, or of peaks? + ++ [X] Alignment: retention time correction between samples + \cite{Sugimoto:2012jt}. ++ [X] Correspondence: (grouping) registration of recurring signals from the same + analyte over replicate samples \cite{Smith:2014di}. * References