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.0.2 Index]