annotated: Create vector or matrix with substrate annotation
In opm: Analysing Phenotype Microarray and Growth Curve Data

Description Usage Arguments Details Value See Also Examples

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.

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

`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.

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.

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.

Other multcomp-functions: opm_mcp

## OPMD and OPMS methods

# default settings
head(x <- annotated(vaas_1))
stopifnot(is.numeric(x), x > 0, !is.null(names(x)))
head(y <- annotated(vaas_4)) # this averages per well over all plates
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]))
stopifnot(y > x, identical(names(y), names(x)))

# generation of logical vectors
head(y <- annotated(vaas_4, output = param_names("disc.name")))
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))
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))
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))
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))
stopifnot(is.numeric(y.ann.eq), !is.null(names(y.ann.eq)))