Package 'xcms'

Description

The methods listed on this page allow to filter and subset XCMSnExp objects. Most of them are inherited from the OnDiskMSnExp object defined in the MSnbase package and have been adapted for XCMSnExp to enable correct subsetting of preprocessing results.

• [: subset a XCMSnExp object by spectra. Be aware that this removes all preprocessing results, except adjusted retention times if keepAdjustedRtime = TRUE is passed to the method.

• [[: extracts a single Spectrum object (defined in MSnbase). The reported retention time is the adjusted retention time if alignment has been performed.

• filterChromPeaks: subset the chromPeaks matrix in object. Parameter method allows to specify how the chromatographic peaks should be filtered. Currently, only method = "keep" is supported which allows to specify chromatographic peaks to keep with parameter keep (i.e. provide a logical, integer or character defining which chromatographic peaks to keep). Feature definitions (if present) are updated correspondingly.

• filterFeatureDefinitions: allows to subset the feature definitions of an XCMSnExp object. Parameter features allow to define which features to keep. It can be a logical, integer (index of features to keep) or character (feature IDs) vector.

• filterFile: allows to reduce the XCMSnExp to data from only selected files. Identified chromatographic peaks for these files are retained while correspondence results (feature definitions) are removed by default. To force keeping feature definitions use keepFeatures = TRUE. Adjusted retention times (if present) are retained by default if present. Use keepAdjustedRtime = FALSE to drop them.

• filterMsLevel: reduces the XCMSnExp object to spectra of the specified MS level(s). Chromatographic peaks and identified features are also subsetted to the respective MS level. See also the filterMsLevel documentation in MSnbase for details and examples.

• filterMz: filters the data set based on the provided m/z value range. All chromatographic peaks and features (grouped peaks) with their apex falling within the provided mz value range are retained (i.e. if chromPeaks(object)[, "mz"] is ⁠>= mz[1]⁠ and ⁠<= mz[2]⁠). Adjusted retention times, if present, are kept.

• filterRt: filters the data set based on the provided retention time range. All chromatographic peaks and features (grouped peaks) within 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 adjusted allows to specify manually whether filtering should be performed on raw or adjusted retention times. Filtering by retention time does not drop any preprocessing results nor does it remove or change alignment results (i.e. adjusted retention times). The method returns an empty object if no spectrum or feature is within the specified retention time range.

• split: splits an XCMSnExp object into a list of XCMSnExp objects based on the provided parameter f. Note that by default all pre-processing results are removed by the splitting, except adjusted retention times, if the optional argument keepAdjustedRtime = TRUE is provided.

Usage

## S4 method for signature 'XCMSnExp,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'XCMSnExp,ANY,ANY'
x[[i, j, drop = FALSE]]

## S4 method for signature 'XCMSnExp'
filterMsLevel(object, msLevel., keepAdjustedRtime = hasAdjustedRtime(object))

## S4 method for signature 'XCMSnExp'
filterFile(
  object,
  file,
  keepAdjustedRtime = hasAdjustedRtime(object),
  keepFeatures = FALSE
)

## S4 method for signature 'XCMSnExp'
filterMz(object, mz, msLevel., ...)

## S4 method for signature 'XCMSnExp'
filterRt(object, rt, msLevel., adjusted = hasAdjustedRtime(object))

## S4 method for signature 'XCMSnExp,ANY'
split(x, f, drop = FALSE, ...)

## S4 method for signature 'XCMSnExp'
filterChromPeaks(
  object,
  keep = rep(TRUE, nrow(chromPeaks(object))),
  method = "keep",
  ...
)

## S4 method for signature 'XCMSnExp'
filterFeatureDefinitions(object, features = integer())

Arguments

Details

All subsetting methods try to ensure that the returned data is consistent. Correspondence results for example are removed by default if the data set is sub-setted by file, since the correspondence results are dependent on the files on which correspondence was performed. This can be changed by setting keepFeatures = TRUE. For adjusted retention times, most subsetting methods support the argument keepAdjustedRtime (even the [ method) that forces the adjusted retention times to be retained even if the default would be to drop them.

Value

All methods return an XCMSnExp object.

Note

The filterFile method removes also process history steps not related to the files to which the object should be sub-setted and updates the fileIndex attribute accordingly. Also, the method does not allow arbitrary ordering of the files or re-ordering of the files within the object.

Note also that most of the filtering methods, and also the subsetting operations [ drop all or selected preprocessing results. To consolidate the alignment results, i.e. ensure that adjusted retention times are always preserved, use the applyAdjustedRtime() function on the object that contains the alignment results. This replaces the raw retention times with the adjusted ones.

Author(s)

Johannes Rainer

See Also

XCMSnExp for base class documentation.

XChromatograms() for similar filter functions on XChromatograms objects.

Examples

## Loading a test data set with identified chromatographic peaks
library(MSnbase)
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")

## Disable parallel processing for this example
register(SerialParam())

## Subset the dataset to the first and third file.
xod_sub <- filterFile(faahko_sub, file = c(1, 3))

## The number of chromatographic peaks per file for the full object
table(chromPeaks(faahko_sub)[, "sample"])

## The number of chromatographic peaks per file for the subset
table(chromPeaks(xod_sub)[, "sample"])

basename(fileNames(faahko_sub))
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(faahko_sub, mz = c(300, 400))
head(chromPeaks(xod_sub))
nrow(chromPeaks(xod_sub))
nrow(chromPeaks(faahko_sub))

## 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(faahko_sub, rt = c(2700, 2900))

range(rtime(xod_sub))
head(chromPeaks(xod_sub))
range(chromPeaks(xod_sub)[, "rt"])

nrow(chromPeaks(faahko_sub))
nrow(chromPeaks(xod_sub))

## Extract a single Spectrum
faahko_sub[[4]]

## Subsetting using [ removes all preprocessing results - using
## keepAdjustedRtime = TRUE would keep adjusted retention times, if present.
xod_sub <- faahko_sub[fromFile(faahko_sub) == 1]
xod_sub

## Using split does also remove preprocessing results, but it supports the
## optional parameter keepAdjustedRtime.
## Split the object into a list of XCMSnExp objects, one per file
xod_list <- split(faahko_sub, f = fromFile(faahko_sub))
xod_list

Description

Subset an xcmsRaw object by scans. The returned xcmsRaw object contains values for all scans specified with argument i. Note that the scanrange slot of the returned xcmsRaw will be c(1, length(object@scantime)) and hence not range(i).

Usage

## S4 method for signature 'xcmsRaw,logicalOrNumeric,missing,missing'
x[i, j, drop]

Arguments

Details

Only subsetting by scan index in increasing order or by a logical vector are supported. If not ordered, argument i is sorted automatically. Indices which are larger than the total number of scans are discarded.

Value

The sub-setted xcmsRaw object.

Author(s)

Johannes Rainer

See Also

split.xcmsRaw

Examples

## Load a test file
file <- system.file('cdf/KO/ko15.CDF', package = "faahKO")
xraw <- xcmsRaw(file, profstep = 0)
## The number of scans/spectra:
length(xraw@scantime)

## Subset the object to scans with a scan time from 3500 to 4000.
xsub <- xraw[xraw@scantime >= 3500 & xraw@scantime <= 4000]
range(xsub@scantime)
## The number of scans:
length(xsub@scantime)
## The number of values of the subset:
length(xsub@env$mz)

Description

Determine which peaks are absent / present in a sample class

Arguments

Details

Determine which peaks are absent / present in a sample class The functions treat peaks that are only present because of fillPeaks correctly, i.e. does not count them as present.

Value

An logical vector with the same length as nrow(groups(object)).

Methods

object = "xcmsSet"

absent(object, ...) present(object, ...)

See Also

group diffreport

Description

The adjustRtime method(s) perform retention time correction (alignment) between chromatograms of different samples/dataset. Alignment is performed by default on MS level 1 data. Retention times of spectra from other MS levels, if present, are subsequently adjusted based on the adjusted retention times of the MS1 spectra. Note that calling adjustRtime on a xcms result object will remove any eventually present previous alignment results as well as any correspondence analysis results. To run a second round of alignment, raw retention times need to be replaced with adjusted ones using the applyAdjustedRtime() function.

The alignment method can be specified (and configured) using a dedicated param argument.

Supported param objects are:

• ObiwarpParam: performs retention time adjustment based on the full m/z - rt data using the obiwarp method (Prince (2006)). It is based on the original code but supports in addition alignment of multiple samples by aligning each against a center sample. The alignment is performed directly on the profile-matrix and can hence be performed independently of the peak detection or peak grouping.

• PeakGroupsParam: performs retention time correction based on the alignment of features defined in all/most samples (corresponding to house keeping compounds or marker compounds) (Smith 2006). First the retention time deviation of these features is described by fitting either a polynomial (smooth = "loess") or a linear (smooth = "linear") function to the data points. These are then subsequently used to adjust the retention time of each spectrum in each sample (even from spectra of MS levels different than MS 1). Since the function is based on features (i.e. chromatographic peaks grouped across samples) a initial correspondence analysis has to be performed before using the groupChromPeaks() function. Alternatively, it is also possible to manually define a numeric matrix with retention times of markers in each samples that should be used for alignment. Such a matrix can be passed to the alignment function using the peakGroupsMatrix parameter of the PeakGroupsParam parameter object. By default the adjustRtimePeakGroups function is used to define this matrix. This function identifies peak groups (features) for alignment in object based on the parameters defined in param. See also do_adjustRtime_peakGroups() for the core API function.

• LamaParama: This function performs retention time correction by aligning chromatographic data to an external reference dataset (concept and initial implementation by Carl Brunius). The process involves identifying and aligning peaks within the experimental chromatographic data, represented as an XcmsExperiment object, to a predefined set of landmark features called "lamas". These landmark features are characterized by their mass-to-charge ratio (m/z) and retention time. see LamaParama() for more information on the method.

Usage

adjustRtime(object, param, ...)

## S4 method for signature 'MsExperiment,ObiwarpParam'
adjustRtime(object, param, chunkSize = 2L, BPPARAM = bpparam())

## S4 method for signature 'MsExperiment,PeakGroupsParam'
adjustRtime(object, param, msLevel = 1L, ...)

PeakGroupsParam(
  minFraction = 0.9,
  extraPeaks = 1,
  smooth = "loess",
  span = 0.2,
  family = "gaussian",
  peakGroupsMatrix = matrix(nrow = 0, ncol = 0),
  subset = integer(),
  subsetAdjust = c("average", "previous")
)

ObiwarpParam(
  binSize = 1,
  centerSample = integer(),
  response = 1L,
  distFun = "cor_opt",
  gapInit = numeric(),
  gapExtend = numeric(),
  factorDiag = 2,
  factorGap = 1,
  localAlignment = FALSE,
  initPenalty = 0,
  subset = integer(),
  subsetAdjust = c("average", "previous"),
  rtimeDifferenceThreshold = 5
)

adjustRtimePeakGroups(object, param = PeakGroupsParam(), msLevel = 1L)

## S4 method for signature 'OnDiskMSnExp,ObiwarpParam'
adjustRtime(object, param, msLevel = 1L)

## S4 method for signature 'PeakGroupsParam'
minFraction(object)

## S4 replacement method for signature 'PeakGroupsParam'
minFraction(object) <- value

## S4 method for signature 'PeakGroupsParam'
extraPeaks(object)

## S4 replacement method for signature 'PeakGroupsParam'
extraPeaks(object) <- value

## S4 method for signature 'PeakGroupsParam'
smooth(x)

## S4 replacement method for signature 'PeakGroupsParam'
smooth(object) <- value

## S4 method for signature 'PeakGroupsParam'
span(object)

## S4 replacement method for signature 'PeakGroupsParam'
span(object) <- value

## S4 method for signature 'PeakGroupsParam'
family(object)

## S4 replacement method for signature 'PeakGroupsParam'
family(object) <- value

## S4 method for signature 'PeakGroupsParam'
peakGroupsMatrix(object)

## S4 replacement method for signature 'PeakGroupsParam'
peakGroupsMatrix(object) <- value

## S4 method for signature 'PeakGroupsParam'
subset(x)

## S4 replacement method for signature 'PeakGroupsParam'
subset(object) <- value

## S4 method for signature 'PeakGroupsParam'
subsetAdjust(object)

## S4 replacement method for signature 'PeakGroupsParam'
subsetAdjust(object) <- value

## S4 method for signature 'ObiwarpParam'
binSize(object)

## S4 replacement method for signature 'ObiwarpParam'
binSize(object) <- value

## S4 method for signature 'ObiwarpParam'
centerSample(object)

## S4 replacement method for signature 'ObiwarpParam'
centerSample(object) <- value

## S4 method for signature 'ObiwarpParam'
response(object)

## S4 replacement method for signature 'ObiwarpParam'
response(object) <- value

## S4 method for signature 'ObiwarpParam'
distFun(object)

## S4 replacement method for signature 'ObiwarpParam'
distFun(object) <- value

## S4 method for signature 'ObiwarpParam'
gapInit(object)

## S4 replacement method for signature 'ObiwarpParam'
gapInit(object) <- value

## S4 method for signature 'ObiwarpParam'
gapExtend(object)

## S4 replacement method for signature 'ObiwarpParam'
gapExtend(object) <- value

## S4 method for signature 'ObiwarpParam'
factorDiag(object)

## S4 replacement method for signature 'ObiwarpParam'
factorDiag(object) <- value

## S4 method for signature 'ObiwarpParam'
factorGap(object)

## S4 replacement method for signature 'ObiwarpParam'
factorGap(object) <- value

## S4 method for signature 'ObiwarpParam'
localAlignment(object)

## S4 replacement method for signature 'ObiwarpParam'
localAlignment(object) <- value

## S4 method for signature 'ObiwarpParam'
initPenalty(object)

## S4 replacement method for signature 'ObiwarpParam'
initPenalty(object) <- value

## S4 method for signature 'ObiwarpParam'
subset(x)

## S4 replacement method for signature 'ObiwarpParam'
subset(object) <- value

## S4 method for signature 'ObiwarpParam'
subsetAdjust(object)

## S4 replacement method for signature 'ObiwarpParam'
subsetAdjust(object) <- value

## S4 method for signature 'XCMSnExp,PeakGroupsParam'
adjustRtime(object, param, msLevel = 1L)

## S4 method for signature 'XCMSnExp,ObiwarpParam'
adjustRtime(object, param, msLevel = 1L)

Arguments

Value

adjustRtime on an OnDiskMSnExp or XCMSnExp object will return an XCMSnExp object with the alignment results.

adjustRtime on an MsExperiment or XcmsExperiment will return an XcmsExperiment with the adjusted retention times stored in an new spectra variable rtime_adjusted in the object's spectra.

ObiwarpParam, PeakGroupsParam and LamaParama return the respective parameter object.

adjustRtimeGroups returns a matrix with the retention times of marker features in each sample (each row one feature, each row one sample).

Subset-based alignment

All alignment methods allow to perform the retention time correction on a user-selected subset of samples (e.g. QC samples) after which all samples not part of that subset will be adjusted based on the adjusted retention times of the closest subset sample (close in terms of index within object and hence possibly injection index). It is thus suggested to load MS data files in the order in which their samples were injected in the measurement run(s).

How the non-subset samples are adjusted depends also on the parameter subsetAdjust: with subsetAdjust = "previous", each non-subset sample is adjusted based on the closest previous subset sample which results in most cases with adjusted retention times of the non-subset sample being identical to the subset sample on which the adjustment bases. The second, default, option is subsetAdjust = "average" in which case each non subset sample is adjusted based on the average retention time adjustment from the previous and following subset sample. For the average, a weighted mean is used with weights being the inverse of the distance of the non-subset sample to the subset samples used for alignment.

See also section Alignment of experiments including blanks in the xcms vignette for more details.

Author(s)

Colin Smith, Johannes Rainer, Philippine Louail, Carl Brunius

References

Prince, J. T., and Marcotte, E. M. (2006) "Chromatographic Alignment of ESI-LC-MS Proteomic Data Sets by Ordered Bijective Interpolated Warping" Anal. Chem., 78 (17), 6140-6152.

Smith, C.A., Want, E.J., O'Maille, G., Abagyan, R. and Siuzdak, G. (2006). "XCMS: Processing Mass Spectrometry Data for Metabolite Profiling Using Nonlinear Peak Alignment, Matching, and Identification" Anal. Chem. 78:779-787.

See Also

plotAdjustedRtime() for visualization of alignment results.

Description

Alignment is achieved using the ['adjustRtime()'] method with a 'param' of class 'LamaParama'. This method corrects retention time by aligning chromatographic data with an external reference dataset.

Chromatographic peaks in the experimental data are first matched to predefined (external) landmark features based on their mass-to-charge ratio and retention time and subsequently the data is aligned by minimizing the differences in retention times between the matched chromatographic peaks and lamas. This adjustment is performed file by file.

Adjustable parameters such as 'ppm', 'tolerance', and 'toleranceRt' define acceptable deviations during the matching process. It's crucial to note that only lamas and chromatographic peaks exhibiting a one-to-one mapping are considered when estimating retention time shifts. If a file has no peaks matching with lamas, no adjustment will be performed, and the the retention times will be returned as-is. Users can evaluate this matching, for example, by checking the number of matches and ranges of the matching peaks, by first running '[matchLamasChromPeaks()]'.

Different warping methods are available; users can choose to fit a *loess* ('method = "loess"', the default) or a *gam* ('method = "gam"') between the reference data points and observed matching ChromPeaks. Additional parameters such as 'span', 'weight', 'outlierTolerance', 'zeroWeight', and 'bs' are specific to these models. These parameters offer flexibility in fine-tuning how the matching chromatographic peaks are fitted to the lamas, thereby generating a model to align the overall retention time for a single file.

Other functions related to this method:

- 'LamaParama()': return the respective parameter object for alignment using 'adjustRtime()' function. It is also the input for the functions listed below.

- ‘matchLamasChromPeaks()': quickly matches each file’s ChromPeaks to Lamas, allowing the user to evaluate the matches for each file.

- 'summarizeLamaMatch()': generates a summary of the 'LamaParama' method. See below for the details of the return object.

- 'matchedRtimes()': Access the list of 'data.frame' saved in the 'LamaParama' object, generated by the 'matchLamasChromPeaks()' function.

- 'plot()':plot the chromatographic peaks versus the reference lamas as well as the fitting line for the chosen model type. The user can decide what file to inspect by specifying the assay number with the parameter 'assay'

Usage

## S4 method for signature 'XcmsExperiment,LamaParama'
adjustRtime(object, param, BPPARAM = bpparam(), ...)

matchLamasChromPeaks(object, param, BPPARAM = bpparam())

summarizeLamaMatch(param)

matchedRtimes(param)

LamaParama(
  lamas = matrix(ncol = 2, nrow = 0, dimnames = list(NULL, c("mz", "rt"))),
  method = c("loess", "gam"),
  span = 0.5,
  outlierTolerance = 3,
  zeroWeight = 10,
  ppm = 20,
  tolerance = 0,
  toleranceRt = 5,
  bs = "tp"
)

## S4 method for signature 'LamaParama,ANY'
plot(
  x,
  index = 1L,
  colPoints = "#00000060",
  colFit = "#00000080",
  xlab = "Matched Chromatographic peaks",
  ylab = "Lamas",
  ...
)

Arguments

Value

For 'matchLamasChromPeaks()': A 'LamaParama' object with new slot 'rtMap' composed of a list of matrices representing the 1:1 matches between Lamas (ref) and ChromPeaks (obs). To access this, 'matchedRtimes()' can be used.

For 'matchedRtimes()': A list of 'data.frame' representing matches between chromPeaks and 'lamas' for each files.

For 'summarizeLamaMatch()':A 'data.frame' with:

- "Total_peaks": total number of chromatographic peaks in the file.

- "Matched_peak": The number of matched peaks to Lamas.

- "Total_Lamas": Total number of Lamas.

- "Model_summary": 'summary.loess' or 'summary.gam' object for each file.

Note

If there are no matches when using 'matchLamasChromPeaks()', the file retention will not be adjusted when calling [adjustRtime()] with the same 'LamaParama' and 'XcmsExperiment' object.

To see examples on how to utilize this methods and its functionality, see the vignette.

Author(s)

Carl Brunius, Philippine Louail

Examples

## load test and reference datasets
ref <- loadXcmsData("xmse")
tst <- loadXcmsData("faahko_sub2")

## create lamas input from the reference dataset
library(MsExperiment)
f <- sampleData(ref)$sample_type
f[f == "QC"] <- NA
ref <- filterFeatures(ref, PercentMissingFilter(threshold = 0, f = f))
ref_mz_rt <- featureDefinitions(ref)[, c("mzmed","rtmed")]

## Set up the LamaParama object
param <- LamaParama(lamas = ref_mz_rt, method = "loess", span = 0.5,
                     outlierTolerance = 3, zeroWeight = 10, ppm = 20,
                     tolerance = 0, toleranceRt = 20, bs = "tp")

## input into `adjustRtime()`
tst_adjusted <- adjustRtime(tst, param = param)

## run diagnostic functions to pre-evaluate alignment
param <- matchLamasChromPeaks(tst, param = param)
mtch <- matchedRtimes(param)

## Access summary of matches and model information
summary <- summarizeLamaMatch(param)

##coverage for each file
summary$Matched_peaks / summary$Total_peaks * 100

## Access the information on the model of for the first file
summary$model_summary[[1]]

Description

Replaces the raw retention times with the adjusted retention time or returns the object unchanged if none are present.

Usage

applyAdjustedRtime(object)

Arguments

Details

Adjusted retention times are stored in parallel to the adjusted retention times in XCMSnExp or XcmsExperiment objects. The applyAdjustedRtime replaces the raw (original) retention times with the adjusted retention times.

Value

An XCMSnExp or XcmsExperiment object with the raw (original) retention times being replaced with the adjusted retention time.

Note

Replacing the raw retention times with adjusted retention times disables the possibility to restore raw retention times using the dropAdjustedRtime() method. This function does not remove the retention time processing step with the settings of the alignment from the processHistory() of the object to ensure that the processing history is preserved.

Author(s)

Johannes Rainer

See Also

adjustRtime() for the function to perform the alignment (retention time correction).

[adjustedRtime()] for the method to extract adjusted retention times from
an [XCMSnExp] object.

[dropAdjustedRtime] for the method to delete alignment results and to
restore the raw retention times.

Examples

## Load a test data set with detected peaks
library(MSnbase)
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")

## Disable parallel processing for this example
register(SerialParam())

xod <- adjustRtime(faahko_sub, param = ObiwarpParam())

hasAdjustedRtime(xod)

## Replace raw retention times with adjusted retention times.
xod <- applyAdjustedRtime(xod)

## No adjusted retention times present
hasAdjustedRtime(xod)

## Raw retention times have been replaced with adjusted retention times
plot(split(rtime(faahko_sub), fromFile(faahko_sub))[[1]] -
    split(rtime(xod), fromFile(xod))[[1]], type = "l")

## And the process history still contains the settings for the alignment
processHistory(xod)

Description

AutoLockMass - This function decides where the lock mass scans are in the xcmsRaw object. This is done by using the scan time differences.

Arguments

Value

AutoLockMass A numeric vector of scan locations corresponding to lock Mass scans

Methods

object = "xcmsRaw"

signature(object = "xcmsRaw")

Author(s)

Paul Benton, [email protected]

Examples

## Not run: library(xcms)
    library(faahKO)
    ## These files do not have this problem
    ## to correct for but just for an example
    cdfpath <- system.file("cdf", package = "faahKO")
    cdffiles <- list.files(cdfpath, recursive = TRUE, full.names = TRUE)
    xr<-xcmsRaw(cdffiles[1])
    xr
    ##Lets assume that the lockmass starts at 1 and is every 100 scans
    lockMass<-xcms:::makeacqNum(xr, freq=100, start=1)
    ## these are equalvent
    lockmass2<-AutoLockMass(xr)
    all((lockmass == lockmass2) == TRUE)

    ob<-stitch(xr, lockMass)

## End(Not run)

Description

The methods listed on this page are XCMSnExp methods inherited from its parent, the OnDiskMSnExp class from the MSnbase package, that alter the raw data or are related to data subsetting. Thus calling any of these methods causes all xcms pre-processing results to be removed from the XCMSnExp object to ensure its data integrity.

bin: allows to bin spectra. See bin documentation in the MSnbase package for more details and examples.

clean: removes unused 0 intensity data points. See clean documentation in the MSnbase package for details and examples.

filterAcquisitionNum: filters the XCMSnExp object keeping only spectra with the provided acquisition numbers. See filterAcquisitionNum for details and examples.

The normalize method performs basic normalization of spectra intensities. See normalize documentation in the MSnbase package for details and examples.

The pickPeaks method performs peak picking. See pickPeaks documentation for details and examples.

The removePeaks method removes mass peaks (intensities) lower than a threshold. Note that these peaks refer to mass peaks, which are different to the chromatographic peaks detected and analyzed in a metabolomics experiment! See removePeaks documentation for details and examples.

The smooth method smooths spectra. See smooth documentation in MSnbase for details and examples.

Usage

## S4 method for signature 'XCMSnExp'
bin(x, binSize = 1L, msLevel.)

## S4 method for signature 'XCMSnExp'
clean(object, all = FALSE, verbose = FALSE, msLevel.)

## S4 method for signature 'XCMSnExp'
filterAcquisitionNum(object, n, file)

## S4 method for signature 'XCMSnExp'
normalize(object, method = c("max", "sum"), ...)

## S4 method for signature 'XCMSnExp'
pickPeaks(
  object,
  halfWindowSize = 3L,
  method = c("MAD", "SuperSmoother"),
  SNR = 0L,
  ...
)

## S4 method for signature 'XCMSnExp'
removePeaks(object, t = "min", verbose = FALSE, msLevel.)

## S4 method for signature 'XCMSnExp'
smooth(
  x,
  method = c("SavitzkyGolay", "MovingAverage"),
  halfWindowSize = 2L,
  verbose = FALSE,
  ...
)

Arguments

Value

For all methods: a XCMSnExp object.

Author(s)

Johannes Rainer

See Also

XCMSnExp-filter for methods to filter and subset XCMSnExp objects. XCMSnExp for base class documentation. OnDiskMSnExp for the documentation of the parent class.

Description

This functions takes two same-sized numeric vectors x and y, bins/cuts x into bins (either a pre-defined number of equal-sized bins or bins of a pre-defined size) and aggregates values in y corresponding to x values falling within each bin. By default (i.e. method = "max") the maximal y value for the corresponding x values is identified. x is expected to be incrementally sorted and, if not, it will be internally sorted (in which case also y will be ordered according to the order of x).

Usage

binYonX(
  x,
  y,
  breaks,
  nBins,
  binSize,
  binFromX,
  binToX,
  fromIdx = 1L,
  toIdx = length(x),
  method = "max",
  baseValue,
  sortedX = !is.unsorted(x),
  shiftByHalfBinSize = FALSE,
  returnIndex = FALSE,
  returnX = TRUE
)

Arguments

Details

The breaks defining the boundary of each bin can be either passed directly to the function with the argument breaks, or are calculated on the data based on arguments nBins or binSize along with fromIdx, toIdx and optionally binFromX and binToX. Arguments fromIdx and toIdx allow to specify subset(s) of the input vector x on which bins should be calculated. The default the full x vector is considered. Also, if not specified otherwise with arguments binFromX and binToX , the range of the bins within each of the sub-sets will be from x[fromIdx] to x[toIdx]. Arguments binFromX and binToX allow to overwrite this by manually defining the a range on which the breaks should be calculated. See examples below for more details.

Calculation of breaks: for nBins the breaks correspond to seq(min(x[fromIdx])), max(x[fromIdx], length.out = (nBins + 1)). For binSize the breaks correspond to seq(min(x[fromIdx]), max(x[toIdx]), by = binSize) with the exception that the last break value is forced to be equal to max(x[toIdx]). This ensures that all values from the specified range are covered by the breaks defining the bins. The last bin could however in some instances be slightly larger than binSize. See breaks_on_binSize and breaks_on_nBins for more details.

Value

Returns a list of length 2, the first element (named "x") contains the bin mid-points, the second element (named "y") the aggregated values from input vector y within each bin. For returnIndex = TRUE the list contains an additional element "index" with the index of the max or min (depending on whether method = "max" or method = "min") value within each bin in input vector x.

Note

The function ensures that all values within the range used to define the breaks are considered in the binning (and assigned to a bin). This means that for all bins except the last one values in x have to be >= xlower and < xupper (with xlower and xupper being the lower and upper boundary, respectively). For the last bin the condition is x >= xlower & x <= xupper. Note also that if shiftByHalfBinSize is TRUE the range of values that is used for binning is expanded by binSize (i.e. the lower boundary will be fromX - binSize/2, the upper toX + binSize/2). Setting this argument to TRUE resembles the binning that is/was used in profBin function from xcms < 1.51.

NA handling: by default the function ignores NA values in y (thus inherently assumes na.rm = TRUE). No NA values are allowed in x.

Author(s)

Johannes Rainer

See Also

imputeLinInterpol

Examples

########
## Simple example illustrating the breaks and the binning.
##
## Define breaks for 5 bins:
brks <- seq(2, 12, length.out = 6)
## The first bin is then [2,4), the second [4,6) and so on.
brks
## Get the max value falling within each bin.
binYonX(x = 1:16, y = 1:16, breaks = brks)
## Thus, the largest value in x = 1:16 falling into the bin [2,4) (i.e. being
## >= 2 and < 4) is 3, the largest one falling into [4,6) is 5 and so on.
## Note however the function ensures that the minimal and maximal x-value
## (in this example 1 and 12) fall within a bin, i.e. 12 is considered for
## the last bin.

#######
## Performing the binning ons sub-set of x
##
X <- 1:16
## Bin X from element 4 to 10 into 5 bins.
X[4:10]
binYonX(X, X, nBins = 5L, fromIdx = 4, toIdx = 10)
## This defines breaks for 5 bins on the values from 4 to 10 and bins
## the values into these 5 bins. Alternatively, we could manually specify
## the range for the binning, i.e. the minimal and maximal value for the
## breaks:
binYonX(X, X, nBins = 5L, fromIdx = 4, toIdx = 10, binFromX = 1, binToX = 16)
## In this case the breaks for 5 bins were defined from a value 1 to 16 and
## the values 4 to 10 were binned based on these breaks.

#######
## Bin values within a sub-set of x, second example
##
## This example illustrates how the fromIdx and toIdx parameters can be used.
## x defines 3 times the sequence form 1 to 10, while y is the sequence from
## 1 to 30. In this very simple example x is supposed to represent M/Z values
## from 3 consecutive scans and y the intensities measured for each M/Z in
## each scan. We want to get the maximum intensities for M/Z value bins only
## for the second scan, and thus we use fromIdx = 11 and toIdx = 20. The breaks
## for the bins are defined with the nBins, binFromX and binToX.
X <- rep(1:10, 3)
Y <- 1:30
## Bin the M/Z values in the second scan into 5 bins and get the maximum
## intensity for each bin. Note that we have to specify sortedX = TRUE as
## the x and y vectors would be sorted otherwise.
binYonX(X, Y, nBins = 5L, sortedX = TRUE, fromIdx = 11, toIdx = 20)

#######
## Bin in overlapping sub-sets of X
##
## In this example we define overlapping sub-sets of X and perform the binning
## within these.
X <- 1:30
## Define the start and end indices of the sub-sets.
fIdx <- c(2, 8, 21)
tIdx <- c(10, 25, 30)
binYonX(X, nBins = 5L, fromIdx = fIdx, toIdx = tIdx)
## The same, but pre-defining also the desired range of the bins.
binYonX(X, nBins = 5L, fromIdx = fIdx, toIdx = tIdx, binFromX = 4, binToX = 28)
## The same bins are thus used for each sub-set.

Description

The 'BlankFlag' class and method enable users to flag features of an 'XcmsExperiment' or 'SummarizedExperiment' object based on the relationship between the intensity of a feature in blanks compared to the intensity in the samples.

This class and method are part of the possible dispatch of the generic function 'filterFeatures'. Features *below* ('<') the user-input threshold will be flagged by calling the 'filterFeatures' function. This means that an extra column will be created in 'featureDefinitions' or 'rowData' called 'possible_contaminants' with a logical value for each feature.

Usage

BlankFlag(
  threshold = 2,
  blankIndex = integer(),
  qcIndex = integer(),
  na.rm = TRUE
)

## S4 method for signature 'XcmsResult,BlankFlag'
filterFeatures(object, filter, ...)

## S4 method for signature 'SummarizedExperiment,BlankFlag'
filterFeatures(object, filter, assay = 1)

Arguments

Value

For 'BlankFlag': a 'BlankFlag' class. 'filterFeatures' returns the input object with an added column in the features metadata called 'possible_contaminants' with a logical value for each feature. This is added to 'featureDefinitions' for 'XcmsExperiment' objects and 'rowData' for 'SummarizedExperiment' objects.

Author(s)

Philippine Louail

See Also

Other Filter features in xcms: DratioFilter, PercentMissingFilter, RsdFilter

Description

Defines breaks for binSize sized bins for values ranging from fromX to toX.

Usage

breaks_on_binSize(fromX, toX, binSize)

Arguments

Details

This function creates breaks for bins of size binSize. The function ensures that the full data range is included in the bins, i.e. the last value (upper boundary of the last bin) is always equal toX. This however means that the size of the last bin will not always be equal to the desired bin size. See examples for more details and a comparisom to R's seq function.

Value

A numeric vector defining the lower and upper bounds of the bins.

Author(s)

Johannes Rainer

See Also

binYonX for a binning function.

Other functions to define bins: breaks_on_nBins()

Examples

## Define breaks with a size of 0.13 for a data range from 1 to 10:
breaks_on_binSize(1, 10, 0.13)
## The size of the last bin is however larger than 0.13:
diff(breaks_on_binSize(1, 10, 0.13))
## If we would use seq, the max value would not be included:
seq(1, 10, by = 0.13)

## In the next example we use binSize that leads to an additional last bin with
## a smaller binSize:
breaks_on_binSize(1, 10, 0.51)
## Again, the max value is included, but the size of the last bin is < 0.51.
diff(breaks_on_binSize(1, 10, 0.51))
## Using just seq would result in the following bin definition:
seq(1, 10, by = 0.51)
## Thus it defines one bin (break) less.

Description

Calculate breaks for same-sized bins for data values from fromX to toX.

Usage

breaks_on_nBins(fromX, toX, nBins, shiftByHalfBinSize = FALSE)

Arguments

Details

This generates bins such as a call to seq(fromX, toX, length.out = nBins) would. The first and second element in the result vector thus defines the lower and upper boundary for the first bin, the second and third value for the second bin and so on.

Value

A numeric vector of length nBins + 1 defining the lower and upper bounds of the bins.

Author(s)

Johannes Rainer

See Also

binYonX for a binning function.

Other functions to define bins: breaks_on_binSize()

Examples

## Create breaks to bin values from 3 to 20 into 20 bins
breaks_on_nBins(3, 20, nBins = 20)
## The same call but using shiftByHalfBinSize
breaks_on_nBins(3, 20, nBins = 20, shiftByHalfBinSize = TRUE)

Description

Combines the samples and peaks from multiple xcmsSet objects into a single object. Group and retention time correction data are discarded. The profinfo list is set to be equal to the first object.

Arguments

Value

A xcmsSet object.

Methods

xs1 = "xcmsRaw"

c(xs1, ...)

Author(s)

Colin A. Smith, [email protected]

See Also

xcmsSet-class

Description

Calibrate peaks using mz values of known masses/calibrants. mz values of identified peaks are adjusted based on peaks that are close to the provided mz values. See details below for more information.

The isCalibrated function returns TRUE if chromatographic peaks of the XCMSnExp object x were calibrated and FALSE otherwise.

Usage

CalibrantMassParam(
  mz = list(),
  mzabs = 1e-04,
  mzppm = 5,
  neighbors = 3,
  method = "linear"
)

isCalibrated(object)

## S4 method for signature 'XCMSnExp'
calibrate(object, param)

Arguments

Details

The method does first identify peaks that are close to the provided mz values and, given that there difference to the calibrants is smaller than the user provided cut off (based on arguments mzabs and mzppm), their mz values are replaced with the provided mz values. The mz values of all other peaks are either globally shifted (for method = "shift" or estimated by a linear model through all calibrants. Peaks are considered close to a calibrant mz if the difference between the calibrant and its mz is ⁠<= mzabs + mz * mzppm /1e6⁠.

Adjustment methods: adjustment function/factor is estimated using the difference between calibrant and peak mz values only for peaks that are close enough to the calibrants. The availabel methods are:

• shift: shifts the m/z of each peak by a global factor which corresponds to the average difference between peak mz and calibrant mz.

• linear: fits a linear model throught the differences between calibrant and peak mz values and adjusts the mz values of all peaks using this.

• edgeshift: performs same adjustment as linear for peaks that are within the mz range of the calibrants and shift outside of it.

For more information, details and examples refer to the xcms-direct-injection vignette.

Value

For CalibrantMassParam: a CalibrantMassParam instance. For calibrate: an XCMSnExp object with chromatographic peaks being calibrated. Be aware that the actual raw mz values are not (yet) calibrated, but only the identified chromatographic peaks.

The CalibrantMassParam function returns an instance of the CalibrantMassParam class with all settings and properties set.

The calibrate method returns an XCMSnExp object with the chromatographic peaks being calibrated. Note that only the detected peaks are calibrated, but not the individual mz values in each spectrum.

Note

CalibrantMassParam classes don't have exported getter or setter methods.

Author(s)

Joachim Bargsten, Johannes Rainer

Description

Calibrate peaks of a xcmsSet via a set of known masses

Arguments

Value

Methods

object = "xcmsSet"

calibrate(object, calibrants,method="linear", mzabs=0.0001, mzppm=5, neighbours=3, plotres=FALSE)

See Also

xcmsSet-class,

Description

chromatogram: extract chromatographic data (such as an extracted ion chromatogram, a base peak chromatogram or total ion chromatogram) from an OnDiskMSnExp or XCMSnExp objects. See also the help page of the chromatogram function in the MSnbase package.

Usage

## S4 method for signature 'XCMSnExp'
chromatogram(
  object,
  rt,
  mz,
  aggregationFun = "sum",
  missing = NA_real_,
  msLevel = 1L,
  BPPARAM = bpparam(),
  adjustedRtime = hasAdjustedRtime(object),
  filled = FALSE,
  include = c("apex_within", "any", "none"),
  ...
)

Arguments

Details

Arguments rt and mz allow to specify the MS data slice (i.e. the m/z range and retention time window) from which the chromatogram should be extracted. These parameters can be either a numeric of length 2 with the lower and upper limit, or a matrix with two columns with the lower and upper limits to extract multiple EICs at once. The parameter aggregationSum allows to specify the function to be used to aggregate the intensities across the m/z range for the same retention time. Setting aggregationFun = "sum" would e.g. allow to calculate the total ion chromatogram (TIC), aggregationFun = "max" the base peak chromatogram (BPC).

If for a given retention time no intensity is measured in that spectrum a NA intensity value is returned by default. This can be changed with the parameter missing, setting missing = 0 would result in a 0 intensity being returned in these cases.

Value

chromatogram returns a XChromatograms object with the number of columns corresponding to the number of files in object and number of rows the number of specified ranges (i.e. number of rows of matrices provided with arguments mz and/or rt). All chromatographic peaks with their apex position within the m/z and retention time range are also retained as well as all feature definitions for these peaks.

Note

For XCMSnExp objects, if adjusted retention times are available, the chromatogram method will by default report and use these (for the subsetting based on the provided parameter rt). This can be changed by setting adjustedRtime = FALSE.

Author(s)

Johannes Rainer

See Also

XCMSnExp for the data object. Chromatogram for the object representing chromatographic data.

[XChromatograms] for the object allowing to arrange
multiple [XChromatogram] objects.

[plot] to plot a [XChromatogram] or [MChromatograms] objects.

`as` (`as(x, "data.frame")`) in `MSnbase` for a method to extract
the MS data as `data.frame`.

Examples

## Load a test data set with identified chromatographic peaks
library(MSnbase)
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")

## Disable parallel processing for this example
register(SerialParam())

## Extract the ion chromatogram for one chromatographic peak in the data.
chrs <- chromatogram(faahko_sub, rt = c(2700, 2900), mz = 335)

chrs

## Identified chromatographic peaks
chromPeaks(chrs)

## Plot the chromatogram
plot(chrs)

## Extract chromatograms for multiple ranges.
mzr <- matrix(c(335, 335, 344, 344), ncol = 2, byrow = TRUE)
rtr <- matrix(c(2700, 2900, 2600, 2750), ncol = 2, byrow = TRUE)
chrs <- chromatogram(faahko_sub, mz = mzr, rt = rtr)

chromPeaks(chrs)

plot(chrs)

## Get access to all chromatograms for the second mz/rt range
chrs[1, ]

## Plot just that one
plot(chrs[1, , drop = FALSE])

Description

Extract an ion chromatogram (EIC) for each chromatographic peak in an XcmsExperiment() object. The result is returned as an XChromatograms() of length equal to the number of chromatographic peaks (and one column).

Usage

chromPeakChromatograms(object, ...)

## S4 method for signature 'XcmsExperiment'
chromPeakChromatograms(
  object,
  expandRt = 0,
  expandMz = 0,
  aggregationFun = "max",
  peaks = character(),
  return.type = c("XChromatograms", "MChromatograms"),
  ...,
  progressbar = TRUE
)

Arguments

Author(s)

Johannes Rainer

See Also

featureChromatograms() to extract an EIC for each feature.

Examples

## Load a test data set with detected peaks
library(MSnbase)
library(xcms)
library(MsExperiment)
faahko_sub <- loadXcmsData("faahko_sub2")

## Get EICs for every detected chromatographic peak
chrs <- chromPeakChromatograms(faahko_sub)
chrs

## Order of EICs matches the order in chromPeaks
chromPeaks(faahko_sub) |> head()

## variable "sample_index" provides the index of the sample the EIC was
## extracted from
fData(chrs)$sample_index

## Get the EIC for selected peaks only.
pks <- rownames(chromPeaks(faahko_sub))[c(6, 12)]
pks

## Expand the data on retention time dimension by 15 seconds (on each side)
res <- chromPeakChromatograms(faahko_sub, peaks = pks, expandRt = 5)
plot(res[1, ])

Description

Extract (MS1 or MS2) spectra from an XcmsExperiment or XCMSnExp object for identified chromatographic peaks. To return spectra for selected chromatographic peaks, their peak ID (i.e., row name in the chromPeaks matrix) can be provided with parameter peaks. For msLevel = 1L (only supported for return.type = "Spectra" or return.type = "List") MS1 spectra within the retention time boundaries (in the file in which the peak was detected) are returned. For msLevel = 2L MS2 spectra are returned for a chromatographic peak if their precursor m/z is within the retention time and m/z range of the chromatographic peak. Parameter method allows to define whether all or a single spectrum should be returned:

• method = "all": (default): return all spectra for each chromatographic peak.

• method = "closest_rt": return the spectrum with the retention time closest to the peak's retention time (at apex).

• method = "closest_mz": return the spectrum with the precursor m/z closest to the peaks's m/z (at apex); only supported for msLevel > 1.

• method = "largest_tic": return the spectrum with the largest total signal (sum of peaks intensities).

• method = "largest_bpi": return the spectrum with the largest peak intensity (maximal peak intensity).

• method = "signal": only for object being a XCMSnExp: return the spectrum with the sum of intensities most similar to the peak's apex signal ("maxo"); only supported for msLevel = 2L.

Parameter return.type allows to specify the type of the result object. With return.type = "Spectra" (the default) a Spectra object with all matching spectra is returned. With return.type = "Spectra" a List of Spectra is returned. The length of the list is equal to the number of rows of chromPeaks. Each element of the list contains thus a Spectra with all spectra for one chromatographic peak (or a Spectra of length 0 if no spectrum was found for the respective chromatographic peak).

Parameter chromPeakColumns allows the user to add specific metadata columns from the chromatographic peaks (chromPeaks) to the returned spectra object. This can be useful to keep information such as retention time (rt), m/z (mz). The columns will be named as they are written in the chromPeaks object with the prefix "chrom_peak_". The peak ID (i.e., the row name of the peak in the chromPeaks matrix) is always added to the spectra object as a metadata column named "chrom_peak_id".

See also the LC-MS/MS data analysis vignette for more details and examples.

Usage

chromPeakSpectra(object, ...)

## S4 method for signature 'XcmsExperiment'
chromPeakSpectra(
  object,
  method = c("all", "closest_rt", "closest_mz", "largest_tic", "largest_bpi"),
  msLevel = 2L,
  expandRt = 0,
  expandMz = 0,
  ppm = 0,
  skipFilled = FALSE,
  peaks = character(),
  chromPeakColumns = c("rt", "mz"),
  return.type = c("Spectra", "List"),
  BPPARAM = bpparam()
)

## S4 method for signature 'XCMSnExp'
chromPeakSpectra(
  object,
  msLevel = 2L,
  expandRt = 0,
  expandMz = 0,
  ppm = 0,
  method = c("all", "closest_rt", "closest_mz", "signal", "largest_tic", "largest_bpi"),
  skipFilled = FALSE,
  return.type = c("Spectra", "MSpectra", "List", "list"),
  peaks = character()
)

Arguments

Value

parameter return.type allow to specify the type of the returned object:

• return.type = "Spectra" (default): a Spectra object (defined in the Spectra package). The result contains all spectra for all peaks. Metadata column "peak_id" provides the ID of the respective peak (i.e. its rowname in chromPeaks().

• return.type = "List": List of length equal to the number of chromatographic peaks is returned, each element being a Spectra with the spectra for one chromatographic peak.

For backward compatibility options "MSpectra" and "list" are also supported but are not suggested.

• return.type = "MSpectra" (deprecated): a MSpectra object with elements being Spectrum objects. The result objects contains all spectra for all peaks. Metadata column "peak_id" provides the ID of the respective peak (i.e. its rowname in chromPeaks()).

• return.type = "list": list of lists that are either of length 0 or contain Spectrum2 object(s) within the m/z-rt range. The length of the list matches the number of peaks.

Author(s)

Johannes Rainer

Examples

## Read a file with DDA LC-MS/MS data
library(MsExperiment)
fl <- system.file("TripleTOF-SWATH/PestMix1_DDA.mzML", package = "msdata")

dda <- readMsExperiment(fl)

## Perform MS1 peak detection
dda <- findChromPeaks(dda, CentWaveParam(peakwidth = c(5, 15),
    prefilter = c(5, 1000)))

## Return all MS2 spectro for each chromatographic peaks as a Spectra object
ms2_sps <- chromPeakSpectra(dda)
ms2_sps

## spectra variable *chrom_peak_id* contain the row names of the peaks in the
## chromPeak matrix and allow thus to map chromatographic peaks to the
## returned MS2 spectra
ms2_sps$chrom_peak_id
chromPeaks(dda)

## Alternatively, return the result as a List of Spectra objects. This list
## is parallel to chromPeaks hence the mapping between chromatographic peaks
## and MS2 spectra is easier.
ms2_sps <- chromPeakSpectra(dda, return.type = "List")
names(ms2_sps)
rownames(chromPeaks(dda))
ms2_sps[[1L]]

## Parameter `msLevel` allows to define from which MS level spectra should
## be returned. By default `msLevel = 2L` but with `msLevel = 1L` all
## MS1 spectra with a retention time within the retention time range of
## a chromatographic peak can be returned. Alternatively, selected
## spectra can be returned by specifying the selection criteria/method
## with the `method` parameter. Below we extract for each chromatographic
## peak the MS1 spectra with a retention time closest to the
## chromatographic peak's apex position. Alternatively it would also be
## possible to select the spectrum with the highest total signal or
## highest (maximal) intensity.
ms1_sps <- chromPeakSpectra(dda, msLevel = 1L, method = "closest_rt")
ms1_sps

## Parameter peaks would allow to extract spectra for specific peaks only.
## Peaks can be defined with parameter `peaks` which can be either an
## `integer` with the index of the peak in the `chromPeaks` matrix or a
## `character` with its rowname in `chromPeaks`.
chromPeakSpectra(dda, msLevel = 1L, method = "closest_rt", peaks = c(3, 5))

Description

Collecting Peaks into xcmsFragmentss from several MS-runs using xcmsSet and xcmsRaw.

Arguments

Details

After running collect(xFragments,xSet) The peak table of the xcmsFragments includes the ms1Peaks from all experiments stored in a xcmsSet-object. Further it contains the relevant msN-peaks from the xcmsRaw-objects, which were created temporarily with the paths in xcmsSet.

Value

A matrix with columns:

Methods

object = "xcmsFragments"

collect(object, ...)

Description

For xcms >= 3.15.3 please use compareChromatograms() instead of correlate

Correlate intensities of two chromatograms with each other. If the two Chromatogram objects have different retention times they are first aligned to match data points in the first to data points in the second chromatogram. See help on alignRt in MSnbase::Chromatogram() for more details.

If correlate is called on a single MChromatograms() object a pairwise correlation of each chromatogram with each other is performed and a matrix with the correlation coefficients is returned.

Note that the correlation of two chromatograms depends also on their order, e.g. correlate(chr1, chr2) might not be identical to correlate(chr2, chr1). The lower and upper triangular part of the correlation matrix might thus be different.

Usage

## S4 method for signature 'Chromatogram,Chromatogram'
correlate(
  x,
  y,
  use = "pairwise.complete.obs",
  method = c("pearson", "kendall", "spearman"),
  align = c("closest", "approx"),
  ...
)

## S4 method for signature 'MChromatograms,missing'
correlate(
  x,
  y = NULL,
  use = "pairwise.complete.obs",
  method = c("pearson", "kendall", "spearman"),
  align = c("closest", "approx"),
  ...
)

## S4 method for signature 'MChromatograms,MChromatograms'
correlate(
  x,
  y = NULL,
  use = "pairwise.complete.obs",
  method = c("pearson", "kendall", "spearman"),
  align = c("closest", "approx"),
  ...
)

Arguments

Value

numeric(1) or matrix (if called on MChromatograms objects) with the correlation coefficient. If a matrix is returned, the rows represent the chromatograms in x and the columns the chromatograms in y.

Author(s)

Michael Witting, Johannes Rainer

Examples

library(MSnbase)
chr1 <- Chromatogram(rtime = 1:10 + rnorm(n = 10, sd = 0.3),
    intensity = c(5, 29, 50, NA, 100, 12, 3, 4, 1, 3))
chr2 <- Chromatogram(rtime = 1:10 + rnorm(n = 10, sd = 0.3),
    intensity = c(80, 50, 20, 10, 9, 4, 3, 4, 1, 3))
chr3 <- Chromatogram(rtime = 3:9 + rnorm(7, sd = 0.3),
    intensity = c(53, 80, 130, 15, 5, 3, 2))

chrs <- MChromatograms(list(chr1, chr2, chr3))

## Using `compareChromatograms` instead of `correlate`.
compareChromatograms(chr1, chr2)
compareChromatograms(chr2, chr1)

compareChromatograms(chrs, chrs)

Description

Create a report showing the most significant differences between two sets of samples. Optionally create extracted ion chromatograms for the most significant differences.

Arguments

Details

This method handles creation of summary reports with statistics about which analytes were most significantly different between two sets of samples. It computes Welch's two-sample t-statistic for each analyte and ranks them by p-value. It returns a summary report that can optionally be written out to a tab-separated file.

Additionally, it does all the heavy lifting involved in creating superimposed extracted ion chromatograms for a given number of analytes. It does so by reading the raw data files associated with the samples of interest one at a time. As it does so, it prints the name of the sample it is currently reading. Depending on the number and size of the samples, this process can take a long time.

If a base file name is provided, the report (see Value section) will be saved to a tab separated file. If EICs are generated, they will be saved as 640x480 PNG files in a newly created subdirectory. However this parameter can be changed with the commands arguments. The numbered file names correspond to the rows in the report.

Chromatographic traces in the EICs are colored and labeled by their sample class. Sample classes take their color from the current palette. The color a sample class is assigned is dependent its order in the xcmsSet object, not the order given in the class arguments. Thus levels(sampclass(object))[1] would use color palette()[1] and so on. In that way, sample classes maintain the same color across any number of different generated reports.

When there are multiple sample classes, xcms will produce boxplots of the different classes and will generate a single anova p-value statistic. Like the eic's the plot number corresponds to the row number in the report.

Value

A data frame with the following columns:

Methods

object = "xcmsSet"

diffreport(object, class1 = levels(sampclass(object))[1], class2 = levels(sampclass(object))[2], filebase = character(), eicmax = 0, eicwidth = 200, sortpval = TRUE, classeic = c(class1,class2), value=c("into","maxo","intb"), metlin = FALSE, h=480,w=640, mzdec=2, missing = numeric(), ...)

See Also

xcmsSet-class, palette

Description

dirname allows to get and set the path to the directory containing the source files of the OnDiskMSnExp (or XCMSnExp) object.

Usage

## S4 method for signature 'OnDiskMSnExp'
dirname(path)

## S4 replacement method for signature 'OnDiskMSnExp'
dirname(path) <- value

Arguments

Author(s)

Johannes Rainer

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 (smooth = "loess") or a linear (smooth = "linear") model to the data points. The models are subsequently used to adjust the retention time for each spectrum in each sample.

Usage

do_adjustRtime_peakGroups(
  peaks,
  peakIndex,
  rtime = list(),
  minFraction = 0.9,
  extraPeaks = 1,
  smooth = c("loess", "linear"),
  span = 0.2,
  family = c("gaussian", "symmetric"),
  peakGroupsMatrix = matrix(ncol = 0, nrow = 0),
  subset = integer(),
  subsetAdjust = c("average", "previous")
)

Arguments

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 house keeping compounds. The paraneters minFraction and 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).

Parameter subset allows to define a subset of samples within the experiment that should be aligned. All samples not being part of the subset will be aligned based on the adjustment of the closest sample within the subset. This allows to e.g. exclude blank samples from the alignment process with their retention times being still adjusted based on the alignment results of the real samples.

Value

A list with numeric vectors with the adjusted retention times grouped by sample.

Note

The method ensures that returned adjusted retention times are increasingly ordered, just as the raw retention times.

Author(s)

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" Anal. Chem. 2006, 78:779-787.

Description

This function performs peak density and wavelet based chromatographic peak detection for high resolution LC/MS data in centroid mode [Tautenhahn 2008].

Usage

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(),
  firstBaselineCheck = TRUE,
  roiScales = NULL,
  sleep = 0,
  extendLengthMSW = FALSE,
  verboseBetaColumns = FALSE
)

Arguments

Details

This algorithm is most suitable for high resolution LC/{TOF,OrbiTrap,FTICR}-MS data in centroid mode. In the first phase the method identifies regions of interest (ROIs) representing mass traces that are characterized as regions with less than ppm m/z deviation in consecutive scans in the LC/MS map. In detail, starting with a single m/z, a ROI is extended if a m/z can be found in the next scan (spectrum) for which the difference to the mean m/z of the ROI is smaller than the user defined ppm of the m/z. The mean m/z of the ROI is then updated considering also the newly included m/z value.

These ROIs are then, after some cleanup, analyzed using continuous wavelet transform (CWT) to locate chromatographic peaks on different scales. The first analysis step is skipped, if regions of interest are passed with the roiList parameter.

Value

A matrix, each row representing an identified chromatographic peak, with columns:

mz

Intensity weighted mean of m/z values of the peak across scans.

mzmin

Minimum m/z of the peak.

mzmax

Maximum m/z of the peak.

rt

Retention time of the peak's midpoint.

rtmin

Minimum retention time of the peak.

rtmax

Maximum retention time of the peak.

into

Integrated (original) intensity of the peak.

intb

Per-peak baseline corrected integrated peak intensity.

maxo

Maximum intensity of the peak.

sn

Signal to noise ratio, defined as (maxo - baseline)/sd, sd being the standard deviation of local chromatographic noise.

egauss

RMSE of Gaussian fit.

Additional columns for verboseColumns = TRUE:

mu

Gaussian parameter mu.

sigma

Gaussian parameter sigma.

h

Gaussian parameter h.

f

Region number of the m/z ROI where the peak was localized.

dppm

m/z deviation of mass trace across scans in ppm.

scale

Scale on which the peak was localized.

scpos

Peak position found by wavelet analysis (scan number).

scmin

Left peak limit found by wavelet analysis (scan number).

scmax

Right peak limit found by wavelet analysis (scan numer).

Additional columns for verboseBetaColumns = TRUE:

beta_cor

Correlation between an "ideal" bell curve and the raw data

beta_snr

Signal-to-noise residuals calculated from the beta_cor fit

Note

The centWave was designed to work on centroided mode, thus it is expected that such data is presented to the function.

This function exposes core chromatographic peak detection functionality of the centWave method. While this function can be called directly, users will generally call the corresponding method for the data object instead.

Author(s)

Ralf Tautenhahn, Johannes Rainer

References

Ralf Tautenhahn, Christoph Böttcher, and Steffen Neumann "Highly sensitive feature detection for high resolution LC/MS" BMC Bioinformatics 2008, 9:504

See Also

centWave for the standard user interface method.

Other core peak detection functions: do_findChromPeaks_centWaveWithPredIsoROIs(), do_findChromPeaks_massifquant(), do_findChromPeaks_matchedFilter(), do_findPeaks_MSW()

Examples

## Load the test file
faahko_sub <- loadXcmsData("faahko_sub")

## Subset to one file and restrict to a certain retention time range
data <- filterRt(filterFile(faahko_sub, 1), c(2500, 3000))

## Get m/z and intensity values
mzs <- mz(data)
ints <- intensity(data)

## Define the values per spectrum:
valsPerSpect <- lengths(mzs)

## Calling the function. We're using a large value for noise and prefilter
## to speed up the call in the example - in a real use case we would either
## set the value to a reasonable value or use the default value.
res <- do_findChromPeaks_centWave(mz = unlist(mzs), int = unlist(ints),
    scantime = rtime(data), valsPerSpect = valsPerSpect, noise = 10000,
    prefilter = c(3, 10000))
head(res)

Description

The 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 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 do_findChromPeaks_centWaveAddPredIsoROIs performs centWave based peak detection based in regions of interest (ROIs) representing predicted isotopes for the peaks submitted with argument 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).

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",
  extendLengthMSW = FALSE,
  verboseBetaColumns = FALSE
)

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

Details

For more details on the centWave algorithm see centWave.

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:

mz

Intensity weighted mean of m/z values of the peaks across scans.

mzmin

Minimum m/z of the peaks.

mzmax

Maximum m/z of the peaks.

rt

Retention time of the peak's midpoint.

rtmin

Minimum retention time of the peak.

rtmax

Maximum retention time of the peak.

into

Integrated (original) intensity of the peak.

intb

Per-peak baseline corrected integrated peak intensity.

maxo

Maximum intensity of the peak.

sn

Signal to noise ratio, defined as (maxo - baseline)/sd, sd being the standard deviation of local chromatographic noise.

egauss

RMSE of Gaussian fit.

Additional columns for verboseColumns = TRUE:

mu

Gaussian parameter mu.

sigma

Gaussian parameter sigma.

h

Gaussian parameter h.

f

Region number of the m/z ROI where the peak was localized.

dppm

m/z deviation of mass trace across scans in ppm.

scale

Scale on which the peak was localized.

scpos

Peak position found by wavelet analysis (scan number).

scmin

Left peak limit found by wavelet analysis (scan number).

scmax

Right peak limit found by wavelet analysis (scan numer).

Additional columns for verboseBetaColumns = TRUE:

beta_cor

Correlation between an "ideal" bell curve and the raw data

beta_snr

Signal-to-noise residuals calculated from the beta_cor fit

Author(s)

Hendrik Treutler, Johannes Rainer

See Also

Other core peak detection functions: do_findChromPeaks_centWave(), do_findChromPeaks_massifquant(), do_findChromPeaks_matchedFilter(), do_findPeaks_MSW()

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 centWave method (see do_findChromPeaks_centWave for details on centWave) by specifying withWave = TRUE.

Usage

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,
  criticalValue = 1.125,
  consecMissedLimit = 2,
  unions = 1,
  checkBack = 0,
  withWave = FALSE
)

Arguments

Details

This algorithm's performance has been tested rigorously on high resolution LC/(OrbiTrap, TOF)-MS data in centroid mode. 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 peak spans. The consecMissedLimit parameter has yielded good performance on Orbitrap data when set to (2) and on TOF data it was found best to be at (1). This may change as the algorithm has yet to be tested on many samples. The criticalValue parameter is perhaps most dificult to dial in appropriately and visual inspection of peak identification is the best suggested tool for quick optimization. The ppm and checkBack parameters have shown less influence than the other parameters and exist to give users flexibility and better accuracy.

Value

A matrix, each row representing an identified chromatographic peak, with columns:

mz

Intensity weighted mean of m/z values of the peaks across scans.

mzmin

Minumum m/z of the peak.

mzmax

Maximum m/z of the peak.

rtmin

Minimum retention time of the peak.

rtmax

Maximum retention time of the peak.

rt

Retention time of the peak's midpoint.

into

Integrated (original) intensity of the peak.

maxo

Maximum intensity of the peak.

If withWave is set to TRUE, the result is the same as returned by the do_findChromPeaks_centWave method.

Author(s)

Christopher Conley

References

Conley CJ, Smith R, Torgrip RJ, Taylor RM, Tautenhahn R and Prince JT "Massifquant: open-source Kalman filter-based XC-MS isotope trace feature detection" Bioinformatics 2014, 30(18):2636-43.

See Also

massifquant for the standard user interface method.

Other core peak detection functions: do_findChromPeaks_centWave(), do_findChromPeaks_centWaveWithPredIsoROIs(), do_findChromPeaks_matchedFilter(), do_findPeaks_MSW()

Examples

## Load the test file
faahko_sub <- loadXcmsData("faahko_sub")

## Subset to one file and restrict to a certain retention time range
data <- filterRt(filterFile(faahko_sub, 1), c(2500, 3000))

## Get m/z and intensity values
mzs <- mz(data)
ints <- intensity(data)

## Define the values per spectrum:
valsPerSpect <- lengths(mzs)

## Perform the peak detection using massifquant - setting prefilter to
## a high value to speed up the call for the example
res <- do_findChromPeaks_massifquant(mz = unlist(mzs), int = unlist(ints),
    scantime = rtime(data), valsPerSpect = valsPerSpect,
    prefilter = c(3, 10000))
head(res)

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 (binSize m/z) wide. Within each bin the maximal intensity is selected. The peak detection is then performed in each bin by extending it based on the steps parameter to generate slices comprising bins current_bin - steps +1 to current_bin + steps - 1. Each of these slices is then filtered with matched filtration using 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].

Usage

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,
  sleep = 0
)

Arguments

Details

The intensities are binned by the provided m/z values within each spectrum (scan). Binning is performed such that the bins are centered around the m/z values (i.e. the first bin includes all m/z values between min(mz) - bin_size/2 and min(mz) + bin_size/2).

For more details on binning and missing value imputation see binYonX and imputeLinInterpol methods.

Value

A matrix, each row representing an identified chromatographic peak, with columns:

mz

Intensity weighted mean of m/z values of the peak across scans.

mzmin

Minimum m/z of the peak.

mzmax

Maximum m/z of the peak.

rt

Retention time of the peak's midpoint.

rtmin

Minimum retention time of the peak.

rtmax

Maximum retention time of the peak.

into

Integrated (original) intensity of the peak.

intf

Integrated intensity of the filtered peak.

maxo

Maximum intensity of the peak.

maxf

Maximum intensity of the filtered peak.

i

Rank of peak in merged EIC (<= max).

sn

Signal to noise ratio of the peak

Note

This function exposes core peak detection functionality of the matchedFilter method. While this function can be called directly, users will generally call the corresponding method for the data object instead (e.g. the link{findPeaks.matchedFilter} method).

Author(s)

Colin A 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" Anal. Chem. 2006, 78:779-787.

See Also

binYonX for a binning function, imputeLinInterpol for the interpolation of missing values. matchedFilter for the standard user interface method.

Other core peak detection functions: do_findChromPeaks_centWave(), do_findChromPeaks_centWaveWithPredIsoROIs(), do_findChromPeaks_massifquant(), do_findPeaks_MSW()

Examples

## Load the test file
faahko_sub <- loadXcmsData("faahko_sub")

## Subset to one file and restrict to a certain retention time range
data <- filterRt(filterFile(faahko_sub, 1), c(2500, 3000))

## Get m/z and intensity values
mzs <- mz(data)
ints <- intensity(data)

## Define the values per spectrum:
valsPerSpect <- lengths(mzs)

res <- do_findChromPeaks_matchedFilter(mz = unlist(mzs), int = unlist(ints),
    scantime = rtime(data), valsPerSpect = valsPerSpect)
head(res)

Description

This function performs peak detection in mass spectrometry direct injection spectrum using a wavelet based algorithm.

Usage

do_findPeaks_MSW(
  mz,
  int,
  snthresh = 3,
  verboseColumns = FALSE,
  scantime = numeric(),
  valsPerSpect = integer(),
  ...
)

Arguments

Details

This is a wrapper around the peak picker in Bioconductor's MassSpecWavelet package calling peakDetectionCWT and tuneInPeakInfo functions. See the xcmsDirect vignette for more information.

Value

A matrix, each row representing an identified peak, with columns:

mz

m/z value of the peak at the centroid position.

mzmin

Minimum m/z of the peak.

mzmax

Maximum m/z of the peak.

rt

Always -1.

rtmin

Always -1.

rtmax

Always -1.

into

Integrated (original) intensity of the peak.

maxo

Maximum intensity of the peak.

intf

Always NA.

maxf

Maximum MSW-filter response of the peak.

sn

Signal to noise ratio.

Author(s)

Joachim Kutzera, Steffen Neumann, Johannes Rainer

See Also

MSW for the standard user interface method. peakDetectionCWT from the MassSpecWavelet package.

Other core peak detection functions: do_findChromPeaks_centWave(), do_findChromPeaks_centWaveWithPredIsoROIs(), do_findChromPeaks_massifquant(), do_findChromPeaks_matchedFilter()

Description

The 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 m/z ranges. By default (with parameter ppm = 0) these m/z ranges have all the same (constant) size (depending on parameter binSize). For values of ppm larger than 0 the m/z bins (ranges or slices) will have increasing sizes depending on the m/z value. This better models the m/z-dependent measurement error/precision seen on some MS instruments.

Usage

do_groupChromPeaks_density(
  peaks,
  sampleGroups,
  bw = 30,
  minFraction = 0.5,
  minSamples = 1,
  binSize = 0.25,
  maxFeatures = 50,
  sleep = 0,
  index = seq_len(nrow(peaks)),
  ppm = 0
)

Arguments

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.

Value

A data.frame, each row representing a (mz-rt) feature (i.e. a peak group) with columns:

• "mzmed": median of the peaks' apex mz values.

• "mzmin": smallest mz value of all peaks' apex within the feature.

• "mzmax":largest mz value of all peaks' apex within the feature.

• "rtmed": the median of the peaks' retention times.

• "rtmin": the smallest retention time of the peaks in the group.

• "rtmax": the largest retention time of the peaks in the group.

• "npeaks": the total number of peaks assigned to the feature.

• "peakidx": a list with the indices of all peaks in a feature in the peaks input matrix.

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.

Note

The default settings might not be appropriate for all LC/GC-MS setups, especially the bw and binSize parameter should be adjusted accordingly.

Author(s)

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" Anal. Chem. 2006, 78:779-787.

See Also

Other core peak grouping algorithms: do_groupChromPeaks_nearest(), do_groupPeaks_mzClust()

Examples

## Load the test file
library(xcms)
library(MsExperiment)
faahko_sub <- loadXcmsData("faahko_sub2")

## Disable parallel processing for this example
register(SerialParam())

## Extract the matrix with the identified peaks from the xcmsSet:
pks <- chromPeaks(faahko_sub)

## Perform the peak grouping with default settings:
res <- do_groupChromPeaks_density(pks, sampleGroups = rep(1, 3))

## The feature definitions:
head(res)

Description

The 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).

Usage

do_groupChromPeaks_nearest(
  peaks,
  sampleGroups,
  mzVsRtBalance = 10,
  absMz = 0.2,
  absRt = 15,
  kNN = 10
)

Arguments

Value

A list with elements "featureDefinitions" and "peakIndex". "featureDefinitions" is a matrix, each row representing an (mz-rt) feature (i.e. peak group) with columns:

• "mzmed": median of the peaks' apex mz values.

• "mzmin": smallest mz value of all peaks' apex within the feature.

• "mzmax":largest mz value of all peaks' apex within the feature.

• "rtmed": the median of the peaks' retention times.

• "rtmin": the smallest retention time of the peaks in the feature.

• "rtmax": the largest retention time of the peaks in the feature.

• "npeaks": the total number of peaks assigned to the feature.

"peakIndex" is a list with the indices of all peaks in a feature in the peaks input matrix.

References

Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for processing and visualization of mass spectrometry based molecular profile data. Bioinformatics 2006, 22:634-636.

See Also

Other core peak grouping algorithms: do_groupChromPeaks_density(), do_groupPeaks_mzClust()

Description

The do_groupPeaks_mzClust function performs high resolution correspondence on single spectra samples.

Usage

do_groupPeaks_mzClust(
  peaks,
  sampleGroups,
  ppm = 20,
  absMz = 0,
  minFraction = 0.5,
  minSamples = 1
)

Arguments

Value

A list with elements "featureDefinitions" and "peakIndex". "featureDefinitions" is a matrix, each row representing an (mz-rt) feature (i.e. peak group) with columns:

• "mzmed": median of the peaks' apex mz values.

• "mzmin": smallest mz value of all peaks' apex within the feature.

• "mzmax": largest mz value of all peaks' apex within the feature.

• "rtmed": always -1.

• "rtmin": always -1.

• "rtmax": always -1.

• "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.

"peakIndex" is a list with the indices of all peaks in a peak group in the peaks input matrix.

References

Saira A. Kazmi, Samiran Ghosh, Dong-Guk Shin, Dennis W. Hill and David F. Grant
Alignment of high resolution mass spectra: development of a heuristic approach for metabolomics.
Metabolomics, Vol. 2, No. 2, 75-83 (2006)

See Also

Other core peak grouping algorithms: do_groupChromPeaks_density(), do_groupChromPeaks_nearest()

Description

The 'DratioFilter' class and method enable users to filter features from an 'XcmsExperiment' or 'SummarizedExperiment' object based on the D-ratio or *dispersion ratio*. This is defined as the standard deviation for QC samples divided by the standard deviation for biological test samples, for each feature of the object (Broadhurst et al.).

This 'filter' is part of the possible dispatch of the generic function 'filterFeatures'. Features *above* ('>') the user-input threshold will be removed from the entire dataset.

Usage

DratioFilter(
  threshold = 0.5,
  qcIndex = integer(),
  studyIndex = integer(),
  na.rm = TRUE,
  mad = FALSE
)

## S4 method for signature 'XcmsResult,DratioFilter'
filterFeatures(object, filter, ...)

## S4 method for signature 'SummarizedExperiment,DratioFilter'
filterFeatures(object, filter, assay = 1)

Arguments

Value

For 'DratioFilter': a 'DratioFilter' class. 'filterFeatures' return the input object minus the features that did not met the user input threshold

Author(s)

Philippine Louail

References

Broadhurst D, Goodacre R, Reinke SN, Kuligowski J, Wilson ID, Lewis MR, Dunn WB. Guidelines and considerations for the use of system suitability and quality control samples in mass spectrometry assays applied in untargeted clinical metabolomic studies. Metabolomics. 2018;14(6):72. doi: 10.1007/s11306-018-1367-3. Epub 2018 May 18. PMID: 29805336; PMCID: PMC5960010.

See Also

Other Filter features in xcms: BlankFlag, PercentMissingFilter, RsdFilter

Description

estimatePrecursorIntensity() determines the precursor intensity for a MS 2 spectrum based on the intensity of the respective signal from the neighboring MS 1 spectra (i.e. based on the peak with the m/z matching the precursor m/z of the MS 2 spectrum). Based on parameter method either the intensity of the peak from the previous MS 1 scan is used (method = "previous") or an interpolation between the intensity from the previous and subsequent MS1 scan is used (method = "interpolation", which considers also the retention times of the two MS1 scans and the retention time of the MS2 spectrum).

Usage

## S4 method for signature 'MsExperiment'
estimatePrecursorIntensity(
  object,
  ppm = 10,
  tolerance = 0,
  method = c("previous", "interpolation"),
  BPPARAM = bpparam()
)

## S4 method for signature 'OnDiskMSnExp'
estimatePrecursorIntensity(
  object,
  ppm = 10,
  tolerance = 0,
  method = c("previous", "interpolation"),
  BPPARAM = bpparam()
)

Arguments

Value

numeric with length equal to the number of spectra in x. NA is returned for MS 1 spectra or if no matching peak in a MS 1 scan can be found for an MS 2 spectrum

Author(s)

Johannes Rainer with feedback and suggestions from Corey Broeckling

Description

A general function for asymmetric chromatographic peaks.

Usage

etg(x, H, t1, tt, k1, kt, lambda1, lambdat, alpha, beta)

Arguments

Value

The function evaluated at times x.

Author(s)

Colin A. Smith, [email protected]

References

Jianwei Li. Development and Evaluation of Flexible Empirical Peak Functions for Processing Chromatographic Peaks. Anal. Chem., 69 (21), 4452-4462, 1997. http://dx.doi.org/10.1021/ac970481d

Description

Export the feature table for further analysis in the MetaboAnalyst software (or the MetaboAnalystR R package).

Usage

exportMetaboAnalyst(
  x,
  file = NULL,
  label,
  value = "into",
  digits = NULL,
  groupnames = FALSE,
  ...
)

Arguments

Value

If file is not specified, the function returns the matrix in the format supported by MetaboAnalyst.

Author(s)

Johannes Rainer

Description

UPDATE: the extractMsData and plotMsData functions are deprecated and as(x, "data.frame") and plot(x, type = "XIC") (x being an OnDiskMSnExp or XCMSnExp object) should be used instead. See examples below. Be aware that filtering the raw object might however drop the adjusted retention times. In such cases it is advisable to use the applyAdjustedRtime() function prior to filtering.

Extract a data.frame of retention time, mz and intensity values from each file/sample in the provided rt-mz range (or for the full data range if rt and mz are not defined).

Usage

## S4 method for signature 'OnDiskMSnExp'
extractMsData(object, rt, mz, msLevel = 1L)

## S4 method for signature 'XCMSnExp'
extractMsData(
  object,
  rt,
  mz,
  msLevel = 1L,
  adjustedRtime = hasAdjustedRtime(object)
)

Arguments

Value

A list of length equal to the number of samples/files in object. Each element being a data.frame with columns "rt", "mz" and "i" with the retention time, mz and intensity tuples of a file. If no data is available for the mz-rt range in a file a data.frame with 0 rows is returned for that file.

Author(s)

Johannes Rainer

See Also

XCMSnExp for the data object.

Examples

## Load a test data set with detected peaks
library(MSnbase)
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")

## Disable parallel processing for this example
register(SerialParam())

## Extract the full MS data for a certain retention time range
## as a data.frame
tmp <- filterRt(faahko_sub, rt = c(2800, 2900))
ms_all <- as(tmp, "data.frame")
head(ms_all)
nrow(ms_all)

Description

Feature compounding aims at identifying and grouping LC-MS features representing different ions or adducts (including isotopes) of the same originating compound. The MsFeatures package provides a general framework and functionality to group features based on different properties. The groupFeatures methods for XcmsExperiment() or XCMSnExp objects implemented in xcms extend these to enable the compounding of LC-MS data considering also e.g. feature peak shaped. Note that these functions simply define feature groups but don't actually aggregate or combine the features.

See MsFeatures::groupFeatures() for an overview on the general feature grouping concept as well as details on the individual settings and parameters.

The available options for groupFeatures on xcms preprocessing results (i.e. on XcmsExperiment or XCMSnExp objects after correspondence analysis with groupChromPeaks()) are:

• Grouping by similar retention times: groupFeatures-similar-rtime().

• Grouping by similar feature values across samples: AbundanceSimilarityParam().

• Grouping by similar peak shape of extracted ion chromatograms: EicSimilarityParam().

An ideal workflow grouping features should sequentially perform the above methods (in the listed order).

Compounded feature groups can be accessed with the featureGroups function.

Usage

## S4 method for signature 'XcmsResult'
featureGroups(object)

## S4 replacement method for signature 'XcmsResult'
featureGroups(object) <- value

Arguments

Author(s)

Johannes Rainer, Mar Garcia-Aloy, Vinicius Veri Hernandes

See Also

plotFeatureGroups() for visualization of grouped features.

Description

Extract ion chromatograms for features in an XcmsExperiment or XCMSnExp object. The function returns for each feature the extracted ion chromatograms (along with all associated chromatographic peaks) in each sample. The chromatogram is extracted from the m/z - rt region that includes all chromatographic peaks of a feature. By default, this region is defined using the range of the chromatographic peaks' m/z and retention times (with mzmin = min, mzmax = max, rtmin = min and rtmax = max). For some features, and depending on the data, the m/z and rt range can thus be relatively large. The boundaries of the m/z - rt region can also be restricted by changing parameters mzmin, mzmax, rtmin and rtmax to a different functions, such as median.

By default only chromatographic peaks associated with a feature are included in the returned XChromatograms object. For object being an XCMSnExp object parameter include allows also to return all chromatographic peaks with their apex position within the selected region (include = "apex_within") or any chromatographic peak overlapping the m/z and retention time range (include = "any").

Usage

featureChromatograms(object, ...)

## S4 method for signature 'XcmsExperiment'
featureChromatograms(
  object,
  expandRt = 0,
  expandMz = 0,
  aggregationFun = "max",
  features = character(),
  return.type = "XChromatograms",
  chunkSize = 2L,
  mzmin = min,
  mzmax = max,
  rtmin = min,
  rtmax = max,
  ...,
  progressbar = TRUE,
  BPPARAM = bpparam()
)

## S4 method for signature 'XCMSnExp'
featureChromatograms(
  object,
  expandRt = 0,
  aggregationFun = "max",
  features,
  include = c("feature_only", "apex_within", "any", "all"),
  filled = FALSE,
  n = length(fileNames(object)),
  value = c("maxo", "into"),
  expandMz = 0,
  ...
)

Arguments