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.

It is also possible to exclude certain samples within an experiment from the estimation of the alignment models. The parameter `subset` allows to define the indices of samples within `object` that should be aligned. Samples not part of this `subset` are left out in the estimation of the alignment models, but their retention times are subsequently adjusted based on the alignment results of the closest sample in `subset` (close in terms of position within the `object`). Alignment could thus be performed on only real samples leaving out e.g. blanks, which are then in turn adjusted based on the closest real sample. Here it is up to the user to ensure that the samples within `object` are ordered correctly (e.g. by injection index).

How the non-subset samples are adjusted bases 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 to use `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 an example.

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.

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

`subsetAdjust`,`subsetAdjust<-`: getter and setter for the `subsetAdjust` 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,
      subset = integer(),
      subsetAdjust = c("average", "previous")
    )

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

    ## 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,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))))`. Note that if `subset` is used, the index passed with `centerSample` is within these subset samples.
`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).
`subset` | `integer` with the indices of samples within the experiment on which the alignment models should be estimated. Samples not part of the subset are adjusted based on the closest subset sample. See description above for more details.
`subsetAdjust` | `character` specifying the method with which non-subset samples should be adjusted. Supported options are `"previous"` and `"average"` (default). See description above for more information.
`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.
`x` | a `PeakGroupsParam` object.

### 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

`binSize,centerSample,response,distFun,gapInit,gapExtend,factorDiag,factorGap,localAlignment,initPenalty,subset,subsetAdjust`

  See corresponding parameter 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

    ## Load a test data set with detected peaks
    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())

    ## Perform retention time correction:
    res <- adjustRtime(faahko_sub, 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(res))

[Package xcms version 3.16.1 Index]