phia (version 0.2-1)

testFactors: Evaluate and Test Combinations of Factor Levels

Description

Calculates and tests the adjusted mean value of the response and other terms of a fitted model, for specific linear combinations of factor levels and specific values of the covariates. This function is specially indicated for post-hoc analyses of models with factors, to test pairwise comparisons of factor levels, simple main effects, and interaction contrasts. In multivariate models, it is possible to define and test contrasts of intra-subjects factors, as in a repeated-measures analysis.

Usage

# S3 method for default
testFactors(model, levels, covariates, offset, terms.formula=~1,
  inherit.contrasts=FALSE,  default.contrasts=c("contr.sum","contr.poly"),
  lht=TRUE, ...)
# S3 method for lm
testFactors(model, ...)
# S3 method for glm
testFactors(model, ..., link=FALSE)
# S3 method for mlm
testFactors(model, levels, covariates, offset, terms.formula=~1,
  inherit.contrasts=FALSE, default.contrasts=c("contr.sum","contr.poly"),
  idata, icontrasts=default.contrasts, lht=TRUE, ...)
# S3 method for lme
testFactors(model, ...)
# S3 method for mer
testFactors(model, ..., link=FALSE)
# S3 method for merMod
testFactors(model, ..., link=FALSE)
# S3 method for testFactors
summary(object, predictors=TRUE, matrices=TRUE, covmat=FALSE, ...)

Value

An object of class "testFactors", that contains the adjusted values and their standard errors for each term, and the otuput of the test, plus other variables used in the calculations. The summary method for this object will display those variables, unless they be omitted by setting the optional arguments predictors, matrices or covmat to FALSE. The argument predictors refers to the coefficients of specified combinations of factor levels, the values of covariates, and the contrast matrices used for terms that include factors; matrices refers to the “linear hypothesis matrix” used by linearHypothesis, and in multivariate linear models, to the “response transformation matrix” as well --- if it exists; covmat refers to the variance-covariance matrix of the adjusted values.

Moreover, summary groups the results of the tests for all terms in one table. By default this table shows the test statistics, their degrees of freedom, and the p-values. If the model is of class "lm", it also shows the sums of squares; and if it is of class "mlm", only the first type of test statistic returned by linearHypothesis (by default “Pillai”) is shown. This variable shape of the ANOVA table is controlled by additional classes assigned to the object (either "testFactors.lm" or "testFactors.mlm", as suitable).

Arguments

model

fitted model. Currently supported classes include "lm", "glm", "mlm", "lme", and "mer" or "merMod" (excluding models fitted by nlmer).

levels

list that defines the factor levels that will be contrasted; see the Details for more information.

covariates

optional numeric vector with specific values of the covariates (see Details).

offset

optional numeric value with a specific value of the offset (if any).

terms.formula

formula that defines the terms of the model that will be calculated and tested. The default value is ~1, and stands for the adjusted mean value. See the Details for more information.

inherit.contrasts

logical value: should the default contrasts of model factors be inherited from the model data frame?

default.contrasts

names of contrast-generating functions to be applied by default to factors and ordered factors, respectively, if inherit.contrasts is FALSE (the default); the contrasts must produce an intra-subjects model matrix in which different terms are orthogonal. The default is c("contr.sum", "contr.poly").

lht

logical indicating if the adjusted values are tested (via linearHypothesis).

link

for models fitted with glm or glmer, logical indicating if the adjusted mean values should represent the link function (FALSE by default, i.e. represent the adjusted means of the response variable).

idata

an optional data frame giving a factor or factors defining the intra-subjects model for multivariate repeated-measures data, as defined in Anova or linearHypothesis.

icontrasts

names of contrast-generating functions to be applied in the within-subject “data”. The default is the same as default.contrasts.

object

object returned by testFactors.

predictors

logical value: should summary return the values of the predictor values used in the calculations?

matrices

logical value: should summary return the matrices used for testing by linearHypothesis?

covmat

logical value: should summary return the covariance matrix of the adjusted values?

...

other arguments passed down to linearHypothesis.

Author

Helios De Rosario-Martinez,

Details

The only mandatory argument is model, which may include any number of factor or numeric predictors, and one offset. The simplest usage of this method, where no other argument is defined, calculates the adjusted mean of the model response variable, pooling over all the levels of factor predictors, and setting the numeric predictors (covariates and offset, ifany) to their average values in the model data frame.

The calculations will be done for the linear combinations of factor levels defined by levels. This argument must be a list, with one element for each factor of the model that has to be manipulated (including factors of the intra-subjects design, if suitable). The factors that are not represented in this list will be pooled over, and elements that do not correspond to any factor of the model will be ignored with a warning. levels may be a named list, where the name of each element identifies the represented factor, and its contents may be one of the following:

1. A character string of length 1 or 2, with the name of one or two factor levels. In the former case, the calculations will be restricted to this level of the factor, as in a simple main effects analysis; in the latter, a pairwise contrast will be calculated between both factor levels.

2. A numeric vector without names, as long as the number of levels in the factor. This will create a linear combination of factor levels, with the elements of the vector as coefficients. For instance, if the factor f has three levels, an element f=c(0.5, 0.5, 0) will average the two first levels, and f=c(0.5, 0.5, -1) will contrast the average of the two first levels against the third one.

3. A numeric vector with names equal to some or all the levels of the factor. This is a simplification of the previous option, where some levels can be omitted, and the coefficient of each level is determined by the names of the vector, which do not have to follow a specific order. Omitted levels will automatically be set to zero.

4. A numeric matrix, as an extension of the two previous options for calculating several combinations at a time. Combinations are defined in columns, so if the matrix does not have row names, the number of rows must be equal to the number of levels in the factor, or if the matrix does have row names, they must coincide with the levels of the factor.

Alternatively, levels may be a single formula or an unnamed list of formulas, of the type factorname ~ K1*level1 + K2*level2 ... (see contrastCoefficients for further details). Both types of lists (named list of string or numeric vectors and matrices, and unnamed lists of formulas) may be mixed.

The argument covariates may be used for setting specific values of the model numeric predictors (covariates). It must be a vector of numeric values. If the elements of this vector have names, their values will be assigned to the covariates that match them; covariates of the model with names not represented in this vector will be set to their default value (the average in the model data frame), and elements with names that do not match with covariates will be ignored. On the other hand, if covariates has no names, and its length is equal to the number of covariates of the model, the values will be assigned to those covariates in the same order as they occur in the model. If it has a different length, the vector will be trimmed or reclycled as needed to fit the number of covariates in the model; this feature may be used, for instance, to set all covariates to the same value, e.g. covariates = 0. The argument offset can likewise be used to define a specific value for the offset of the model.

To analyse terms other than the adjusted mean value of the response, use the argument terms.formula. For instance, if the model has the covariates var1, var2, ..., the slopes of the response with respect to them may be added to the analysis by defining terms.formula as ~var1 + var2 .... This formula may be used more generally, for analysing interactions, omitting the mean response, adding the main effects of factors, etc. A different analysis is done for each term of this formula, that must also be contained in the formula of model. For instance, if terms.formula is equal to ~ var1*var2, the function will analyse the adjusted intercept, plus the terms var1, var2, and var1:var2. The intercept stands for the mean value of the response, and terms formed by one or more covariates stand por the slope of the response with respect to the product of those covariates.

If any of the variables in the term is a factor, the function analyses a full set of contrasts for that factor of the remaining part of the term; for instance if var1 were a factor, the term var1 would stand for the contrasts of the intercept, and var1:var2 would stand for the contrasts of the slope var2, across the levels of var1. The set of contrasts used in the analysis is normally defined by the argument default.contrasts: by default, if the factor is ordered it will be a set of “polynomial contrasts”, and otherwise “sum contrasts”; however, if inherit.contrasts is TRUE the contrasts will directly be copied from the ones used to define the model. Factors that have explicit contrasts defined in the model data frame will use those contrasts, regardless of the values defined for default.contrasts and inherit.contrasts. The analysis assumes that the contrasts are orthogonal to the intercept, which is the usual case if the default arguments are provided, and a warning will be issued if non-orthogonal contrasts are used; take special care of not using “treatment contrats” if inherit.contrasts is set to TRUE or default.contrasts is changed.

In generalized linear models, the adjusted means represent the expected values of the response by default, but the expected value of the link function may be shown by setting the argument link=FALSE. On the other hand, slope values and standard errors always refer to the link function.

For multivariate models, the arguments idata, and icontrasts may be used to define an intra-subjects model for multivariate repeated-measures data, as described for Anova or linearHypothesis in package car. Note, however, that the combinations of intra-subjects factor levels are defined in levels, and other arguments defined in those functions like idesign, imatrix or iterms will have no effect in testFactors.

The significance of adjusted values is tested by a call to linearHypothesis for each term, unless lht is set to FALSE. Extra arguments may be passed down to that function, for instance to specify the test statistic that will be evaluated.

See Also

linearHypothesis in package car. interactionMeans, and testInteractions as useful wrappers of testFactors.

Examples

# Example with factors and covariates
# Analyse prestige of Canadian occupations depending on
# education, income and type of occupation
# See ?Prestige for a description of the data set

prestige.mod <- lm(prestige ~ (education+log2(income))*type, data=Prestige)

# Pairwise comparisons for factor "type", to see how it influences
# the mean value of  prestige and interacts with log.income

# 1: "white collar" vs "blue collar"
wc.vs.bc <- list(type=c("wc", "bc"))
testFactors(prestige.mod, wc.vs.bc, terms.formula=~log2(income))
# 2: "professional" vs. "blue collar"
prof.vs.bc <- list(type=c("prof", "bc"))
testFactors(prestige.mod, prof.vs.bc, terms.formula=~log2(income))
# 3: "professional" vs. "white collar"
prof.vs.wc <- list(type=c("prof", "wc"))
testFactors(prestige.mod, prof.vs.wc, terms.formula=~log2(income))


# Interaction contrasts in a repeated-measures experiment
# See ?OBrienKaiser for a description of the data set

mod.ok <- lm(cbind(pre.1, pre.2, pre.3, pre.4, pre.5, 
  post.1, post.2, post.3, post.4, post.5, 
  fup.1, fup.2, fup.3, fup.4, fup.5) ~  treatment*gender, 
  data=OBrienKaiser)

# intra-subjects data:
phase <- factor(rep(c("pretest", "posttest", "followup"), each=5))
hour <- ordered(rep(1:5, 3))
idata <- data.frame(phase, hour)
Anova(mod.ok, idata=idata, idesign=~phase*hour)

# Contrasts across "phase", for different contrasts of "treatment"
# Using different definitions of the argument "levels"

# 1: Treatment "A" vs. treatment "B".
A.vs.B <- list(treatment=c("A", "B"))
# The following are equivalent:
# A.vs.B <- list(treatment=c(A=1, B=-1, control=0))
# A.vs.B <- list(treatment=c(A=1, B=-1))
# A.vs.B <- list(treatment ~ A - B)
# A.vs.B <- treatment ~ A - B
testFactors(mod.ok, A.vs.B, idata=idata, terms.formula=~0+phase)

# 2: Controls vs. treatments
control.vs.AB <- list(treatment=c(A=0.5, B=0.5, control=-1))
# The following is equivalent:
# control.vs.AB <- treatment ~ (A+B)/2 - control
testFactors(mod.ok, control.vs.AB, idata=idata, terms.formula=~0+phase)

# Shortcut to get only the adjusted values and simplified ANOVA tables
contr <- list(A.vs.B=A.vs.B, control.vs.AB=control.vs.AB)
anovaTables <- function(contrast) summary(testFactors(mod.ok, contrast,
  idata=idata, terms.formula=~0+phase),
  predictors=FALSE, matrices=FALSE)
  
lapply(contr,anovaTables)