opm_mcp: Multiple comparison of group means
In opm: Analysing Phenotype Microarray and Growth Curve Data

Description Usage Arguments Details Value Author(s) See Also Examples

This function provides linear-hypothesis testing and multiple comparisons for group means of curve parameters based on the multcomp package.

  ## S4 method for signature 'MOPMX'
opm_mcp(object, model, linfct = 1L,
    m.type = "glm", rhs = 0, alternative = "two.sided", glht.args = list(),
    ops = "+", output = "mcp", sep = opm_opt("comb.value.join"), ...) 
  ## S4 method for signature 'OPMS'
opm_mcp(object, model, linfct = 1L,
    m.type = "glm", rhs = 0, alternative = "two.sided", glht.args = list(),
    ops = "+", output = "mcp", sep = opm_opt("comb.value.join"), ...) 
  ## S4 method for signature 'data.frame'
opm_mcp(object, model, linfct = 1L,
    m.type = c("glm", "lm", "aov"), rhs = 0, alternative = "two.sided",
    glht.args = list(), ops = "+",
    output = c("mcp", "data", "model", "linfct", "contrast"),
    sep = opm_opt("comb.value.join"), split.at = param_names("split.at"))

`object`	Either an `OPMS` object, or a data frame derived via `extract` containing factor variables that determine experimental groups for multiple comparison of means and can be selected using `model`.
`model`	A model formula, or a character vector or a list containing the names of factors to be included in the model for fitting. In order to join two or more metadata-variables into one factor use pseudo-function `J` (described in `extract`). This is necessary especially when `linfct = Pairs`, see the examples below. For model specifications using formulae in general, see `formula` (in the stats package). For the way models are used by opm for selecting metadata entries, see `metadata`. If `object` is of class `OPMS`, `model` is passed to `extract` after removal of the relevant reserved names (see `param_names`, which can nevertheless be included in the model formula as they are always contained in the resulting data frame. If `model` is a list or vector, it is used for selecting metadata, too, and for running the tests automatically converted to a formula, using one to several operators as specified with `ops`. Non-syntactical names within `formula` are converted to syntactical ones for use with `glht`. This is done in the same way in the data frame passed to that function. If the `output` argument is set to ‘model’, the function returns the converted `model` argument, which is useful in exploring the conducted conversions before running the proper tests.
`linfct`	A specification of the linear hypotheses to be tested analogously to `linfct` in `glht`. A variety of objects can be used for this argument: One of the classes of objects accepted by `glht` from the multcomp package as `linfct` argument. Such objects will not be modified. Linear functions can be specified by either the matrix of coefficients or by symbolic descriptions of one or more linear hypotheses. The set of existing types of contrast is extended with the contrast type ‘Pairs’. Here all pair-wise comparison concerning the first entry in `model` are computed. Alternatively, the factor whose levels should determine the pairs can be addressed directly with, for example, `linfct = c(Pairs.Well = 1)`. The Dunnett-type contrast has the special feature, that users are free to directly define the group which should serve as the control or base in the set of contrasts. In analogy to `Pairs`, the name of the level, separated from the string ‘Dunnett’ by any sign, can be stated. See examples below and in the vignettes and further `contrMat` from the multcomp package. In situations where metadata have non-syntactic names, special signs are exchanged against dots. When applying `linfct = c(Pairs = 1)` or `linfct = c(Dunnett = 1)` with the above mentioned extension, the sign between the `linfct` name and the metadata name must not be a dot. An object inheriting from the `AsIs` as created by `I` from the base package. Such objects, irrespective of their class, will be converted to an argument list for and then passed to `mcp` from the multcomp package. Other objects will be treated as a selection of factors from the data just like `model`, i.e. they will be converted like any `metadata` key (but note that character vectors would be passed to `glht`). If this yielded a numeric or logical vector, it would be treated as specifying the positions of factors within `model`. If names were present, they would be used as the values of the arguments passed to `mcp`. Otherwise `opm_opt("contrast.type")` would be used. (See the `type` argument of `contrMat`.) The modified object would then be used as the argument list in a call to `mcp`. After the conversions, if any, this argument is passed to `glht` as `linfct` argument. If the `output` argument is set to `linfct`, the function returns the converted `linfct` argument, which is useful in exploring the conducted conversions before running the proper tests.
`m.type`	Character scalar indicating which of the following model types to use in model fitting: `glm`, `aov` or `lm`. See the eponymous functions in the stats package for details.
`rhs`	Numeric vector passed to `glht` in the multcomp package. Also considered when creating contrasts of the ‘Pairs’ type.
`alternative`	Character scalar also passed to that function (but only if `linfct` is or yields a matrix), and also relevant for ‘Pairs’-type contrasts.
`glht.args`	List of additional arguments for the multiple comparison procedure passed to `glht`. See `glht` in the multcomp package for details.
`ops`	Character vector. `ops` is ignored if `model` is directly provided as a formula. Otherwise the provided list or character vector is converted to formula, and `ops` then specifies the operator(s) to insert between the variables in the right part of the `model` formula. Thus, `ops` should contain ‘+’, ‘*’, or ‘:’ as elements. ‘+’ is the default, and the elements are recycled as usual if necessary. See the description of `formula` for further details (in the stats package).
`output`	Character scalar determining the main output mode. See below under ‘Value’.
`split.at`	Character vector. See `extract`. Cannot be set in the case of the `OPMS` method.
`sep`	Character scalar (comprising a single character) passed to `extract`.
`...`	Optional arguments passed to `extract`. Most of them would be passed to `wells` for creating substrate names. Some restrictions are necessary here if the resulting object shall latter on be analysed with `annotated`; see there for details. This holds particularly if `object` is of class `MOPMX`. In that case, setting `full` to `FALSE` is likely to cause most combinations of wells and plates to be omitted because the well names get non-unique.

This function internally reshapes the data in object into a ‘flat’ data frame the structure of which is described under ‘value’. In the default output mode, glht from the multcomp package is applied to this data frame. This causes (general linear) models and, by indicating a contrast type, user-defined simultaneous multiple testing procedures to be inferred.

Since either the user or this function itself makes use of mcp, we refer to the ‘Details’ section of the glht function. The mcp function must be used with care when defining parameters of interest in two-way ANOVA or ANCOVA models. The definition of treatment differences might be problem-specific. An automated determination of the parameters of interest would be impossible and thus only comparisons for the main effects (ignoring covariates and interactions) would be generated and a warning issued.

The kind of object returned by this function are determined by the output argument:

mcp: The default. An object of class glht as the result of the multiple comparison of means. Methods for print, summary, confint, coef and vcov are available for this class. See glht in the multcomp package for details.
data: Reshaped (‘flattened’) data frame of the class OPM_MCP_OUT. It contains one column for the measured values, one factorial variable determining the well, one factorial variable for the curve parameter (see param_names) and additional factorial variables selected by model as factors. The column names are converted to syntactical names. Such a data frame might be of use for model-building approaches not covered by this function.
model: The model argument after the conversions conducted by opm_mcp, if any.
linfct: The linfct argument after the conversions conducted by opm_mcp, if any.
contrast: A list of contrast matrices as specified by model and linfct. As these matrices would be guaranteed to fit to object, they could serve as template matrices to be further specified by the user. Note that this only works if linfct either is an object of class mcp or convertible to such an object, and if its values are character scalars that can be passed as type argument to contrMat from the multcomp package.

Lea A.I. Vaas, Markus Goeker

multcomp::glht multcomp::contrMat stats::lm stats::formula

Other multcomp-functions: annotated

# helper function for plotting with better suitable margins
plot_with_margin <- function(x, mar, ...) {
  old.mar <- par(mar = mar)
  on.exit(par(old.mar)) # tidy up
  plot(x, ...)
}
do.plot <- FALSE # change this to see the plots

## OPMS method

# return the intermediary data frame, do not conduct statistical tests
head(x <- opm_mcp(vaas_4, model = list("Species", "Strain"),
  output = "data"))
stopifnot(is.data.frame(x), dim(x) == c(384, 5))

# watch the converted 'model' argument
(x <- opm_mcp(vaas_4, model = list("Species", "Strain"),
  output = "model"))
stopifnot(inherits(x, "formula")) # left side is set automatically

# watch the converted 'linfct' argument
(x <- opm_mcp(vaas_4, model = list("Species", "Strain"),
  linfct = c(Dunnett = 1), output = "linfct"))
stopifnot(inherits(x, "mcp"))

# create a template contrast matrix
(x <- opm_mcp(vaas_4, model = list("Species", "Strain"),
  linfct = c(Dunnett = 1), output = "contrast"))
stopifnot(is.list(x), sapply(x, inherits, "contrMat"),
  names(x) == "Species") # the selection is as specified by 'linfct'

# comparison using specified model comparing 'Species' pooled over
# complete plates
(x <- opm_mcp(vaas_4, model = list("Species"), m.type = "lm",
  linfct = c(Dunnett = 1))) # refers to 'Species'
stopifnot(inherits(x, "glht"), length(coef(x)) == 1)
if (do.plot)
  plot_with_margin(x, c(3, 20, 3, 2), main = "Species")

# comparison of only A01 - A04 against each other, Tukey style
# note that the left side of the model is set automatically
(x <- opm_mcp(vaas_4[, , 1:4],
  model = ~ Well + Species, m.type = "lm",
  linfct = c(Tukey = 1))) # the number refers to 'Well'
stopifnot(inherits(x, "glht"), length(coef(x)) == 6)
if (do.plot)
  plot_with_margin(x, c(3, 18, 3, 2), main = "Tukey, A01 - A04")

# Dunnett-type comparison of selected wells
(x <- opm_mcp(vaas_4[, , 1:4], model = ~ Well,
  m.type = "lm", linfct = c(Dunnett = 1)))
stopifnot(inherits(x, "glht"), length(coef(x)) == 3)
if (do.plot)
  plot_with_margin(x, c(3, 20, 3, 2), main = "Dunnett, A01 vs. A02 - A04")
# by default 'Dunnett' uses first level as reference

# Dunnett-type comparison with selected control-group
(x <- opm_mcp(vaas_4[, , 1:5], output = "mcp", model = ~ Well,
  linfct = c(`Dunnett.A05 (D-Cellobiose)` = 1)))
if (do.plot)
  plot_with_margin(x, c(3, 20, 3, 2), main = "Dunnett, vs. A05")

# manually defined contrast matrix
(contr <- opm_mcp(vaas_4[, , 1:4], linfct = c(Tukey = 1),
  model = ~ Well, output = "contrast")) # create template, Tukey style
contr <- contr$Well[c(1:3, 6), ] # select comparisons of interest
(x <- opm_mcp(vaas_4[, , 1:4],
  model = ~ Well, m.type = "lm", linfct = contr)) # run tests
if (do.plot)
  plot_with_margin(x, c(3, 20, 3, 2), main = "My own contrasts")

# joining of selected metadata using pseudofunction J
(x <- opm_mcp(vaas_4[, , 1:4], model = ~ J(Well + Species),
  linfct = c(Dunnett = 1), full = FALSE)) # use short well names
if (do.plot)
  plot_with_margin(x, c(3, 22, 3, 2), main = "Dunnett, Well/Species joined")

# comparing wells pairwise regarding the tested species
(x <- opm_mcp(vaas_4[, , 1:4], model = ~ J(Well + Species),
  linfct = c(Pairs.Well = 1), full = FALSE)) # use short well names
if (do.plot)
  plot_with_margin(x, c(3, 22, 3, 2),
    main = "Wells compared between species")
# i.e. 'Pairs.Well' means 'Pairs' type of comparison for each 'Well'
# separately within a joined factor (the first one in 'model', hence
# 'c(Pairs.Well = 1)', with '1' referring to the elements of 'model').

# pairwise comparison of Species regarding the tested strains
xx <- c(vaas_4, vaas_4) # temporary test data
(x <- opm_mcp(xx[, , 1:4], model = ~ J(Strain + Species),
  linfct = c(Pairs.Species = 1), full = FALSE)) # use short well names
if (do.plot)
  plot_with_margin(x, c(3, 22, 3, 2),
    main = "Strains compared within species")
# i.e. 'Pairs.Species' means 'Pairs' type of comparison for each 'Species'
# separately within a joined factor (the first one in 'model', hence
# 'c(Pairs.Species = 1)', with '1' referring to the elements of 'model').

## one could check the number of calculated tests as follows:
#if (nrow(confint(result)$confint) > 20L)
#  warning("number of performed comparisons exceeds 20")

## data-frame method (usually unnecessary to directly apply it)
x <- extract(vaas_4, as.labels = list("Species", "Strain"), subset = "A",
  dataframe = TRUE)

# without the tests, returning the converted data frame
head(y <- opm_mcp(x, output = "data", model = list("Species", "Strain")))
stopifnot(is.data.frame(y), dim(y) == c(384, 5)) # same result as above

# now with conducting the tests
(y <- opm_mcp(x, model = "Species", m.type = "lm",
  linfct = c(Dunnett = 1)))
stopifnot(inherits(y, "glht"), length(coef(y)) == 1)
if (do.plot)
  plot_with_margin(y, c(3, 20, 3, 2), main = "Species (from data frame)")

# testing for subsets of object
(y <- opm_mcp(subset(x, x$Species == "Escherichia coli"),
  linfct = c(Dunnett = 1), model = "Strain", m.type = "lm"))
stopifnot(inherits(y, "glht"), length(coef(y)) == 1)
if (do.plot)
  plot_with_margin(y, c(3, 15, 3, 2), main = "Dunnett (from data frame)")