selectAnchors {metabCombiner} | R Documentation

## Select Anchors for Nonlinear RT Model

### Description

A subset of possible alignments in the `combinedTable` are used as ordered pairs to anchor a retention time projection model. Alignments of abundant features are prominent targets for anchor selection, but shared identified features (i.e. feature pairs where idx = idy) may be used.

### Usage

    selectAnchors(
      object,
      useID = FALSE,
      tolmz = 0.003,
      tolQ = 0.3,
      tolrtq = 0.3,
      windx = 0.03,
      windy = 0.03,
      brackets_ignore = c("(", "[", "{")
    )

### Arguments

`object` | metabCombiner object.
`useID` | logical. Option to first search for IDs as anchors.
`tolmz` | numeric. m/z tolerance for prospective anchors
`tolQ` | numeric. Quantile Q tolerance for prospective anchors
`tolrtq` | numeric. Linear RT quantile tolerance for prosepctive anchors.
`windx` | numeric. Retention time exclusion window around each anchor in X dataset. Optimal values are between 0.01 and 0.05 min (1-3s)
`windy` | numeric. Retention time exclusion window around each anchor in dataset Y. Optimal values are between 0.01 and 0.05 min (1-3s)
`brackets_ignore` | If useID = TRUE, bracketed identity strings of the types included in this argument will be ignored.

### Details

In order to map between two sets of retention times, a set of ordered pairs need to be selected for the spline fit. This function relies on mutually abundant features to select these ordered pairs. In iterative steps, the most abundant (as indicated by Q value) in one dataset is selected along with its counterpart, and all features within some retention time window specified by `windx` & `windy` arguments are excluded. This process is repeated until all features have been considered.

`tolQ` & `tolmz` arguments restrict to feature pairs that have differences in Q & m/z within these tolerances. `tolrtq` further limits to feature pairs those with relative differences in linear retention time quantiles, calculated as rtqx = (rtx - min(rtx)) / (max(rtx) - min(rtx)) & rtqy = (rty - min(rty)) / (max(rty) - min(rty))

Shared identities (in which idx & idy columns have matching, non-empty & non-bracketed strings) may be used if `useID` is set to TRUE. In this case, shared identities will be searched first and will not be subject to any of the restrictions in m/z, Q, or rt. The iterative process proceeds after processing of shared identities.

### Value

`metabCombiner` object with updated `anchors` slot. This is a data.frame of feature pairs that shall be used to map between retention times using a GAM or LOESS model.

`idx` | identities of features from dataset X
`idy` | identities of features from dataset Y
`mzx` | m/z values of features from dataset X
`mzy` | m/z values of features from dataset Y
`rtx` | retention time values of features from dataset X
`rty` | retention time values of features from dataset Y
`rtProj` | model-projected retention time values from X to Y
`Qx` | abundance quantile values of features from dataset X
`Qy` | abundance quantile values of features from dataset Y
`adductX` | adduct label of features from dataset X
`adductY` | adduct label of features from dataset Y
`group` | m/z feature group of feature pairing
`labels` | anchor labels; "I" for identity, "A" for normal anchors

### See Also

`getAnchors`, `fit_gam`, `fit_loess`

### Examples

    data(plasma30)
    data(plasma20)

    p30 <- metabData(plasma30, samples = "CHEAR")
    p20 <- metabData(plasma20, samples = "Red", rtmax = 17.25)
    p.comb <- metabCombiner(xdata = p30, ydata = p20, binGap = 0.005)

    ##example 1 (no known IDs used)
    p.comb <- selectAnchors(p.comb, tolmz = 0.003, tolQ = 0.3, windx = 0.03,
        windy = 0.02, tolrtq = 0.3)

    ##example 2 (known IDs used)
    p.comb <- selectAnchors(p.comb, useID = TRUE, tolmz = 0.003, tolQ = 0.3)

    ##To View Plot of Ordered Pairs
    anchors = getAnchors(p.comb)
    plot(anchors$rtx, anchors$rty, main = "Selected Anchor Ordered Pairs",
        xlab = "rtx", ylab = "rty")

[Package metabCombiner version 1.2.2 Index]