calcScores: Compute Feature Similarity Scores
In metabCombiner: Method for Combining LC-MS Metabolomics Feature Measurements

Description Usage Arguments Details Value See Also Examples

Calculates a pairwise similarity (between 0 & 1) between all grouped features in metabCombiner object. The similarity score calculation is described in scorePairs.

calcScores(
  object,
  A,
  B,
  C,
  fit = c("gam", "loess"),
  groups = NULL,
  useAdduct = FALSE,
  adduct = 1.25,
  usePPM = FALSE,
  brackets_ignore = c("(", "[", "{")
)

`object`	metabCombiner object.
`A`	Numeric weight for penalizing m/z differences.
`B`	Numeric weight for penalizing differences between fitted & observed retention times
`C`	Numeric weight for differences in Q (abundance quantiles).
`fit`	Character. Choice of fitted rt model, "gam" or "loess."
`groups`	integer. Vector of feature groups to score. If set to NULL (default), will compute scores for all feature groups.
`useAdduct`	logical. Option to penalize mismatches in (non-empty, non-bracketed) adduct column annotations.
`adduct`	numeric. If useAdduct is TRUE, divides score of mismatched, non-empty and non-bracked adduct column labels by this value.
`usePPM`	logical. Option to use relative (as opposed to absolute) m/z differences in score computations.
`brackets_ignore`	If useAdduct = TRUE, bracketed adduct character strings of these types will be ignored according to this argument

This function updates the rtProj, score, rankX, and rankY columns in the combinedTable report. First, using the RT mapping model computed in the previous step(s), rtx values are projected onto rty. Then similarity scores are calculated based on m/z, rt (fitted vs observed), and Q differences, with multiplicative weight penalties A, B, and C.

If the datasets contain representative set of shared identities (idx = idy), evaluateParams provides some guidance on appropriate A, B, and C values to use. In testing, the best values for A should lie between 50 and 120, according to mass accuracy; B should lie between 5 and 15 depending on fitting accuracy (higher if datasets processed under roughly identical conditions) ; C should vary between 0 and 1, depending on sample similarity. See examples below.

If using ppm (usePPM = TRUE), do not use the above guidelines for A values. The suggested range is between 0.01 and 0.05, though this hasn't been thoroughly tested yet. Also, if using adduct information (useAdduct = TRUE), the score is divided by the numeric adduct argument if non-empty and non-bracketed adduct values do not match. Be sure that adduct annotations are accurate before using this functionality.

metabCombiner object with updated combinedTable. rtProj column will contain fitted retention times determined from previously computed model; score will contain computed pairwise similarity scores of feature pairs; rankX & rankY are the integer ranks of scores for x & y features in descending order.

evaluateParams, scorePairs

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)

#example: moderate m/z deviation, accurate rt fit, high sample similarity
p.comb <- calcScores(p.comb, A = 90, B = 14, C = 0.8, useAdduct = FALSE,
         groups = NULL, fit = "gam", usePPM = FALSE)
cTable = combinedTable(p.comb)  #to view results

#example 2: high m/z deviation, moderate rt fit, low sample similarity
p.comb <- calcScores(p.comb, A = 50, B = 8, C = 0.2)

#example 3: low m/z deviation, poor rt fit, moderate sample similarity
p.comb <- calcScores(p.comb, A = 120, B = 5, C = 0.5)

#example 4: using ppm for mass deviation; note different A value
p.comb <- calcScores(p.comb, A = 0.05, B = 14, C = 0.5, usePPM = TRUE)

#example 5: limiting to specific m/z groups 1-1000
p.comb <- calcScores(p.comb, A = 90, B = 14, C = 0.5, groups = seq(1,1000))

#example 6: using adduct information
p.comb <- calcScores(p.comb, A = 90, B = 14, C = 0.5, useAdduct = TRUE,
                     adduct = 1.25)