annotated {opm}R Documentation

Create vector or matrix with substrate annotation

Description

These methods create vectors or matrices that include numeric values (selected parameter estimates or opm_mcp results) as well as an annotation of the according substrates.

Usage

  ## S4 method for signature 'MOPMX'
annotated(object, what = "kegg", how = "ids",
    output = opm_opt("curve.param"), lmap = NULL, sep = opm_opt("min.mode"),
    conc = FALSE) 
  ## S4 method for signature 'OPMA'
annotated(object, what = "kegg", how = "ids",
    output = opm_opt("curve.param"), lmap = NULL, sep = NULL, conc = FALSE) 
  ## S4 method for signature 'OPMD'
annotated(object, what = "kegg", how = "ids",
    output = opm_opt("curve.param"), lmap = NULL, sep = NULL, conc = FALSE) 
  ## S4 method for signature 'OPMS'
annotated(object, what = "kegg", how = "ids",
    output = opm_opt("curve.param"), lmap = NULL, sep = opm_opt("min.mode"),
    conc = FALSE) 
  ## S4 method for signature 'OPM_MCP_OUT'
annotated(object, what = "kegg",
    how = "ids", output = c("full", "plain"), lmap = NULL, sep = NULL,
    conc = FALSE) 
  ## S4 method for signature 'opm_glht'
annotated(object, what = "kegg", how = "ids",
    output = "numeric", lmap = NULL, sep = opm_opt("comb.value.join"),
    conc = FALSE)

Arguments

object

An object of the classes opm_glht or OPM_MCP_OUT as created by opm_mcp, OPMA, OPMD or OPMS.

what

Character scalar indicating the kind of annotation to use. Passed as eponymous argument to substrate_info.

how

Character scalar. Indicating how the annotation is inserted. Currently ‘ids’, ‘values’ and ‘data.frame’ are supported. See below for details.

output

For the OPMA and OPMS methods, the estimated parameter of interest (see param_names). For the opm_glht method, either a numeric scalar or one of the following character scalars:

numeric

Return the coefficients.

upwards

Return FALSE, NA, or TRUE indicating whether the coefficients are significantly smaller or larger than, or insignificantly different from the cutoff given by opm_opt("threshold"). This is calculated from the confidence intervals stored in object.

downwards

Return TRUE, NA, or FALSE indicating whether the coefficients are significantly smaller or larger than, or insignificantly different from the default cutoff.

smaller

Return TRUE or FALSE indicating whether or not the coefficients are significantly smaller than the default cutoff.

larger

Return TRUE or FALSE indicating whether or not the coefficients are significantly larger than the default cutoff.

equal

Return TRUE or FALSE indicating whether or not the coefficients are insignificantly different from the default cutoff. Note that ‘insignificantly different’ does not mean ‘significantly equal’!

different

Return TRUE or FALSE indicating whether or not the coefficients are significantly different from the default cutoff.

Alternatively, character scalars such as ‘!75.0’, ‘<100’, ‘>150’, ‘=85.0’, ‘,3.0’ or ‘'11.5’ can be provided, with the first character translated to the corresponding meaning in the list above (with ‘,’ for ‘downwards’ and ‘'’ for ‘upwards’) and the remaining string coerced to the cutoff to be used. If a numeric scalar is provided, it is used as cutoff in conjunction with the ‘different’ mode described above.

lmap

Vector to be used for mapping the created logical values, if any. See map_values and the examples below for details. If NULL, ignored. Also ignored if numeric instead of logical values are created.

sep

For the opm_glht method, the single character that has been used as eponymous argument in the call to opm_mcp. Necessary to unambiguously match substrate names within contrast names. For the OPMS method, a numeric scalar working like the cutoff argument of listing. Has only an effect if discretised values are chosen (and are available).

conc

Logical scalar indicating whether concentration information should be added to the output, either as a further matrix column or as attribute, depending on how. Note that concentration information might be partially or entirely NA, depending on the wells in use.

Details

All methods use substrate_info for translating substrate names to IDs. The methods differ only in the way numeric and logical values are generated.

The OPMA methods simply chooses a certain parameter. The OPMD method can also return discretised values and optionally translates them using lmap.

The OPMS method returns the averages of the selected parameter estimates over all contained plates. It is an error to select discretised values instead if they are not available for all plates. If otherwise, the discretised values are aggregated as indicated by the sep argument.

The opm_glht method makes only sense if each coefficient estimated by opm_mcp can be linked to a single substrate. This is usually only possible for the ‘Dunnett’ and ‘Pairs’ type of contrast if applied to the wells. Typical applications are the comparison of a single control well to a series of other wells and the comparison of all or a subset of the wells between two metadata-defined groups. See opm_mcp for details.

Because the current implementation of the opm_glht method attempts to identify the substrates within the names of the estimated coefficients (differences of means), some care must be taken when translating well coordinates to substrate names in the call to opm_mcp. Substrate IDs cannot be identified if they are abbreviated, i.e. a low value of the max argument passed to wells is used, and not accompanied by the well coordinates, i.e. if the in.parens argument is set to FALSE.

In the case of the ‘Pairs’ type of contrasts, some problems can be avoided by setting the ‘comb.value.join’ entry of opm_opt to another value. The same value must be used in the calls to opm_mcp and annotated, however.

Value

For how = "ids", a numeric or logical vector whose names are the IDs of the respective substrates in the database as chosen by what.

For how = "values", a numeric matrix containing the chosen computed values as first column together with data obtained via web service associated with the chosen database, in analogy to the download argument of substrate_info but after conversion to a numeric matrix. This option is not available for all values of what. See substrate_info for details.

The first column name of the matrix is like the ‘value’ entry returned by param_names in ‘reserved.md.names’ mode. The second one is ‘Concentration’ if conc is TRUE. Depending on the subsequent analysis, it might be necessary to convert the matrix to a data frame, to convert the column names to syntactical names (see make.names from the base package), or to remove all rows and columns with missing values.

For how = "data.frame", much like how = "values", but the numeric matrix is converted to a data frame, the column names are made syntactic, and all essentially binary (zero/one) columns are converted to factors.

See Also

Other multcomp-functions: opm_mcp

Examples

## OPMD and OPMS methods

# default settings
head(x <- annotated(vaas_1))

##     <NA>   C00721   C00208   C01083   C00185   C08240 
## 123.4558 248.1809 284.0994 269.7548 180.7536 287.7959

stopifnot(is.numeric(x), x > 0, !is.null(names(x)))
head(y <- annotated(vaas_4)) # this averages per well over all plates

##      <NA>    C00721    C00208    C01083    C00185    C08240 
##  74.55616 130.25350  99.63986 107.51617  72.97884  98.05762

stopifnot(is.numeric(x), y > 0, identical(names(y), names(x)))

# AUC instead of maximum height
head(y <- annotated(vaas_1, output = param_names()[4]))

##      <NA>    C00721    C00208    C01083    C00185    C08240 
##  8918.137 18391.590 21960.080 18531.180 11831.150 19254.160

stopifnot(y > x, identical(names(y), names(x)))

# generation of logical vectors
head(y <- annotated(vaas_4, output = param_names("disc.name")))

##   <NA> C00721 C00208 C01083 C00185 C08240 
##  FALSE  FALSE  FALSE  FALSE  FALSE  FALSE

stopifnot(is.logical(y), identical(names(y), names(x)))

# mapping of logical vectors: FALSE => 1, NA => 2, TRUE => 3
head(y <- annotated(vaas_4, output = param_names("disc.name"), lmap = 1:3))

##   <NA> C00721 C00208 C01083 C00185 C08240 
##      1      1      1      1      1      1

stopifnot(is.numeric(y), y > 0, identical(names(y), names(x)))

## 'opm_glht' method

# generation of 'opm_ghlt' test object
y <- opm_mcp(vaas_4[, , 1:4], model = ~ J(Well, Species),
  m.type = "aov", linfct = c(Pairs.Well = 1), full = FALSE)

# generation of numerical vector
head(y.ann <- annotated(y))

##       <NA>     C00721     C00208     C01083 
##  -32.00967 -119.35382 -127.27708 -105.33792

stopifnot(is.numeric(y.ann), !is.null(names(y.ann)))

# generation of logical vector indicating whether the compared groups behave
# equally (= insignificantly different) regarding the considered substrates
head(y.ann.eq <- annotated(y, output = "equal", lmap = 1:3))

##   <NA> C00721 C00208 C01083 
##      3      3      3      3

stopifnot(y.ann.eq > 0, identical(names(y.ann.eq), names(x)[1:4]))

# generation of numeric vector with FALSE => 1, NA => 2 and TRUE => 3 and
# substrate names after translation of relevant characters to Greek letters
head(y.ann.eq <- annotated(y, output = "equal", what = "greek", lmap = 1:3))

## Negative Control          Dextrin        D-Maltose      D-Trehalose 
##                3                3                3                3

stopifnot(is.numeric(y.ann.eq), !is.null(names(y.ann.eq)))
[Package opm version 1.3.63 Index]