labelRows {metabCombiner} | R Documentation

## Annotate and Remove Report Rows

### Description

This is a method for annotating identity-matched, removable, & conflicting feature pair alignment (FPA) rows in the `combinedTable` report. Simple thresholds for score, rank, retention time error and delta score can computationally reduce the set of possible FPAs to the most likely compound matches. FPAs falling within some small measure (in score or mz/rt) of the top-ranked row are organized into subgroups to facilitate inspection; setting delta to 0 automatically reduces to 1-1 matches.

`reduceTable` behaves identically to labelRows, but with delta set to 0 & remove set to TRUE, automatically limiting to 1 - 1 feature matches constrained by rank and score threshold parameters. Rank threshold defaults are also stricter with reduceTable.

### Usage

    labelRows(
      object,
      minScore = 0.5,
      maxRankX = 3,
      maxRankY = 3,
      method = c("score", "mzrt"),
      delta = 0.1,
      maxRTerr = 10,
      resolveConflicts = FALSE,
      rtOrder = TRUE,
      remove = FALSE,
      balanced = TRUE,
      brackets_ignore = c("(", "[", "{")
    )

    reduceTable(
      object,
      maxRankX = 2,
      maxRankY = 2,
      minScore = 0.5,
      maxRTerr = 10,
      rtOrder = TRUE,
      brackets_ignore = c("(", "[", "{")
    )

### Arguments

`object` | Either a `metabCombiner` object or `combinedTable`.
`minScore` | numeric minimum allowable score (between 0 & 1) for metabolomics feature pair alignments
`maxRankX` | integer maximum allowable rank for X dataset features.
`maxRankY` | integer maximum allowable rank for Y dataset features.
`method` | Conflict detection method. If equal to "score" (default), assigns a conflict subgroup if score of lower-ranking FPA is within some tolerance of higher-ranking FPA. If set to "mzrt", assigns a conflicting subgroup if within a small m/z & rt distance of the top-ranked FPA.
`delta` | numeric score or mz/rt distances used to define subgroups. If method = "score", a value (between 0 & 1) score difference between a pair of conflicting FPAs. If method = "mzrt", a length 4 numeric: (m/z, rt, m/z, rt) tolerances, the first pair for X dataset features and the second pair for Y dataset features.
`maxRTerr` | numeric maximum allowable error between model-projected retention time (rtProj) and observed retention time (rty)
`resolveConflicts` | logical option to computationally resolve conflicting rows to a final set of 1-1 feature pair alignments
`rtOrder` | logical. If resolveConflicts set to TRUE, then this imposes retention order consistency on rows deemed "RESOLVED" within subgroups.
`remove` | Logical. Option to keep or discard rows deemed removable.
`balanced` | Logical. Optional processing of "balanced" groups, defined as groups with an equal number of features from input datasets where all features have a 1-1 match.
`brackets_ignore` | character. Bracketed identity strings of the types in this argument will be ignored

### Details

`metabCombiner` initially reports all possible FPAs in the rows of the `combinedTable` report. Most of these are misalignments that require removal. This function is used to automate most of the reduction process by labeling rows as removable or conflicting, based on certain conditions, and is performed after computing similarity scores.

A label may take on one of four values:

a) "": No determination made b) "IDENTITY": an alignment with matching identity "idx & idy" strings c) "REMOVE": a row determined to be a misalignment d) "CONFLICT": competing alignments for one or multiple shared features

The labeling rules are as follows: 1) Rows with matching idx & idy strings are labeled "IDENTITY". These rows are not labeled "REMOVE", irrespective of subsequent criteria. 2) Groups determined to be 'balanced': label rows with rankX > 1 & rankY > 1 "REMOVE" irrespective of `delta` criteria 3) Rows with a score < `minScore`: label "REMOVE" 4) Rows with rankX > `maxRankX` and/or rankY > `maxRankY`: label "REMOVE" 5) Conflicting subgroup assignment as determined by `method` & `delta` arguments. Conflicting alignments following outside `delta` thresholds: labeled "REMOVE". Otherwise, they are assigned a "CONFLICT" label and subgroup number.

### Value

updated `combinedTable` or `metabCombiner` object. The table will have three new columns:

`labels` | characterization of feature alignments as described
`subgroup` | conflicting subgroup number of feature alignments
`alt` | alternate subgroup for rows in multiple feature pair conflicts

### 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.0075)
    p.comb = selectAnchors(p.comb, tolmz = 0.003, tolQ = 0.3, windy = 0.02)
    p.comb = fit_gam(p.comb, k = 20, iterFilter = 1)
    p.comb = calcScores(p.comb, A = 90, B = 14, C = 0.5)

    ###merge combinedTable and featdata
    cTable = cbind.data.frame(combinedTable(p.comb), featdata(p.comb))

    ##example using score-based conflict detection method
    lTable = labelRows(cTable, maxRankX = 3, maxRankY = 2, minScore = 0.5,
             method = "score", maxRTerr = 0.5, delta = 0.2)

    ##example using mzrt-based conflict detection method
    lTable = labelRows(cTable, method = "mzrt", maxRankX = 3, maxRankY = 2,
                         delta = c(0.005, 0.5, 0.005,0.3), maxRTerr = 0.5)

[Package metabCombiner version 1.4.0 Index]