adjustRtime-obiwarp {xcms}R Documentation

Align retention times across samples using Obiwarp

Description

This method performs retention time adjustment using the Obiwarp method [Prince 2006]. It is based on the code at http://obi-warp.sourceforge.net but supports 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.

The ObiwarpParam class allows to specify all settings for the retention time adjustment based on the obiwarp method. Class Instances should be created using the ObiwarpParam constructor.

binSize,binSize<-: getter and setter for the binSize slot of the object.

centerSample,centerSample<-: getter and setter for the centerSample slot of the object.

response,response<-: getter and setter for the response slot of the object.

distFun,distFun<-: getter and setter for the distFun slot of the object.

gapInit,gapInit<-: getter and setter for the gapInit slot of the object.

gapExtend,gapExtend<-: getter and setter for the gapExtend slot of the object.

factorDiag,factorDiag<-: getter and setter for the factorDiag slot of the object.

factorGap,factorGap<-: getter and setter for the factorGap slot of the object.

localAlignment,localAlignment<-: getter and setter for the localAlignment slot of the object.

initPenalty,initPenalty<-: getter and setter for the initPenalty slot of the object.

adjustRtime,XCMSnExp,ObiwarpParam: performs retention time correction/alignment based on the total mz-rt data using the obiwarp method.

Usage

ObiwarpParam(binSize = 1, centerSample = integer(), response = 1L,
  distFun = "cor_opt", gapInit = numeric(), gapExtend = numeric(),
  factorDiag = 2, factorGap = 1, localAlignment = FALSE,
  initPenalty = 0)

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

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

## 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 'XCMSnExp,ObiwarpParam'
adjustRtime(object, param,
  msLevel = 1L)

Arguments

binSize

numeric(1) defining the bin size (in mz dimension) to be used for the profile matrix generation. See step parameter in profile-matrix documentation for more details.

centerSample

integer(1) defining the index of the center sample in the experiment. It defaults to floor(median(1:length(fileNames(object)))).

response

numeric(1) defining the responsiveness of warping with response = 0 giving linear warping on start and end points and response = 100 warping using all bijective anchors.

distFun

character defining the distance function to be used. Allowed values are "cor" (Pearson's correlation), "cor_opt" (calculate only 10% diagonal band of distance matrix; better runtime), "cov" (covariance), "prd" (product) and "euc" (Euclidian distance). The default value is distFun = "cor_opt".

gapInit

numeric(1) defining the penalty for gap opening. The default value for gapInit depends on the value of distFun: for distFun = "cor" and distFun = "cor_opt" it is 0.3, for distFun = "cov" and distFun = "prd" 0.0 and for distFun = "euc" 0.9.

gapExtend

numeric(1) defining the penalty for gap enlargement. The default value for gapExtend depends on the value of distFun, for distFun = "cor" and distFun = "cor_opt" it is 2.4, for distFun = "cov" 11.7, for distFun = "euc" 1.8 and for distFun = "prd" 7.8.

factorDiag

numeric(1) defining the local weight applied to diagonal moves in the alignment.

factorGap

numeric(1) defining the local weight for gap moves in the alignment.

localAlignment

logical(1) whether a local alignment should be performed instead of the default global alignment.

initPenalty

numeric(1) defining the penalty for initiating an alignment (for local alignment only).

object

For adjustRtime: an XCMSnExp object.

For all other methods: a ObiwarpParam object.

param

A ObiwarpParam object containing all settings for the alignment method.

msLevel

integer defining the MS level on which the retention time should be performed.

value

The value for the slot.

Value

The ObiwarpParam function returns a ObiwarpParam class instance with all of the settings specified for obiwarp retention time adjustment and alignment.

For adjustRtime,XCMSnExp,ObiwarpParam: a XCMSnExp object with the results of the retention time adjustment step. These can be accessed with the adjustedRtime method. Retention time correction does also adjust the retention time of the identified chromatographic peaks (accessed via chromPeaks. Note that retention time correction drops all previous peak grouping results from the result object.

For adjustRtime,OnDiskMSnExp,ObiwarpParam: a numeric with the adjusted retention times per spectra (in the same order than rtime).

Slots

.__classVersion__,binSize,centerSample,response,distFun,gapInit,gapExtend,factorDiag,factorGap,localAlignment,initPenalty

See corresponding parameter above. .__classVersion__ stores the version from the class. Slots values should exclusively be accessed via the corresponding getter and setter methods listed above.

Note

These methods and classes are part of the updated and modernized xcms user interface which will eventually replace the retcor methods. All of the settings to the alignment algorithm can be passed with a ObiwarpParam object.

Alignment using obiwarp is performed on the retention time of spectra of on MS level. Retention times for spectra of other MS levels are subsequently adjusted based on the adjustment function defined on the retention times of the spectra of MS level msLevel.

Calling adjustRtime on an XCMSnExp object will cause all peak grouping (correspondence) results and any previous retention time adjustment results to be dropped.

Author(s)

Colin Smith, Johannes Rainer

References

John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of ESI-LC-MS Proteomics Data Sets by Ordered Bijective Interpolated Warping" 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" Anal. Chem. 2006, 78 (17), 6140-6152.

See Also

retcor.obiwarp for the old user interface. plotAdjustedRtime for visualization of alignment results.

XCMSnExp for the object containing the results of the alignment.

Other retention time correction methods: adjustRtime-peakGroups, adjustRtime

Examples

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 <- readMSData(fls[1:2], mode = "onDisk")

## Perform retention time correction on the OnDiskMSnExp:
res <- adjustRtime(raw_data, param = ObiwarpParam())

## As a result we get a numeric vector with the adjusted retention times for
## all spectra.
head(res)

## We can split this by file to get the adjusted retention times for each
## file
resL <- split(res, fromFile(raw_data))

##############################
## Perform retention time correction on an XCMSnExp:
##
## Perform first the chromatographic peak detection using the matchedFilter
## method.
mfp <- MatchedFilterParam(snthresh = 20, binSize = 1)
res <- findChromPeaks(raw_data, param = mfp)

## Performing the retention time adjustment using obiwarp.
res_2 <- adjustRtime(res, param = ObiwarpParam())

head(rtime(res_2))
head(rtime(raw_data))

## Also the retention times of the detected peaks were adjusted.
tail(chromPeaks(res))
tail(chromPeaks(res_2))

[Package xcms version 3.4.4 Index]