afex (version 0.13-145)

aov.car: Convenience wrappers for car::Anova using either a formula or factor based interface.

Description

These functions allow convenient access to Anova (from the car package) for data in the long format (i.e., one observation per row), possibly aggregating the data if there is more than one obersvation per individuum and cell. Hence, mixed between-within ANOVAs can be calculated conveniently without using the rather unhandy format of car::Anova. aov.car can be called using a formula similar to aov specifying an error strata for the within-subject factor(s), aov4 can be called with a lme4-like formula, and ez.glm is called specifying the factors as character vectors.

Usage

aov.car(formula, data, fun.aggregate = NULL, type = 3,
     factorize = TRUE, check.contrasts = TRUE,
     return = "nice", observed = NULL, args.return = list(), ...)

aov4(formula, data, observed = NULL, fun.aggregate = NULL, type = 3,
     factorize = TRUE, check.contrasts = TRUE,
     return = "nice", args.return = list(), ...,
     print.formula = FALSE)

ez.glm(id, dv, data, between = NULL, within = NULL, covariate = NULL,
     observed = NULL, fun.aggregate = NULL, type = 3,
     factorize = TRUE, check.contrasts = TRUE,
     return = "nice", args.return = list(), ..., print.formula = FALSE)

univ(object)

Arguments

formula

A formula specifying the ANOVA model similar to aov (for aov.car or similar to lme4:lmer for aov4). Should include an error term (i.e., Error(id/ ) or (

data

A data.frame containing the data. Mandatory.

fun.aggregate

The function for aggregating the data before running the ANOVA if there is more than one obervation per individuum and cell of the design. The default NULL issues a warning if aggregation is necessary and uses

type

The type of sums of squares for the ANOVA. Defaults to 3. Passed to Anova. Possible values are "II", "III", 2, or 3.

factorize

logical. Should between subject factors be factorized (with note) before running the analysis. Default is TRUE. If one wants to run an ANCOVA, needs to be set to FALSE (in which case centering on 0 is checked on numeric variables

check.contrasts

logical. Should contrasts for between-subject factors be checked and (if necessary) changed to be "contr.sum". See details.

return

What should be returned? If "nice" (the default) will return a nice ANOVA table (produced by nice.anova. Possible values are c("Anova", "lm", "data", "nice", "full", "all", "univariate

observed

character vector indicating which of the variables are observed (i.e, measured) as compared to experimentally manipulated. The default behavior is to return a ANOVA table with generalized eta squared effect size for which this information is

args.return

list of further arguments passed to the function which produces the return value. Currently only supports return = "nice" (the default) which then passes arguments to nice.anova

...

Further arguments passed to fun.aggregate.

id

character vector (of length 1) indicating the subject identifier column in data.

dv

character vector (of length 1) indicating the column containing the dependent variable in data.

between

character vector indicating the between-subject(s) factor(s)/column(s) in data. Default is NULL indicating no between-subjects factors.

within

character vector indicating the within-subject(s) factor(s)/column(s) in data. Default is NULL indicating no within-subjects factors.

covariate

character vector indicating the between-subject(s) covariate(s) (i.e., column(s)) in data. Default is NULL indicating no covariates.

print.formula

ez.glm is a wrapper for aov.car. This boolean argument indicates whether the formula in the call to car.aov should be printed.

object

An object of class Anova.mlm as returned by aov.car, ez.glm, or Anova.

Value

• aov.car, aov4, and ez.glm are wrappers to Anova, the return value is dependent on the return argument. When argument return is "nice" (the default) a nice ANOVA table is returnd (nice.anova) with the following columns: Effect, df, MSE (mean-squared errors), F (potentially with significant symbols), ges (generalized eta-squared), p. If return = "full" or return = "all" a list list with the following elements: [object Object],[object Object],[object Object],[object Object],[object Object] If return = "univariate" the object returned from univ. univ returns a list of data.frames containing the univariate results (i.e., the classical ANOVA results) from an object of class "Anova.mlm". This is essentially the output from summary.Anova.mlm with multivariate = FALSE, e.g. summary(aov.car(...), multivriate = FALSE), as a list instead of printed to the console. For objects of class "anova" (i.e., the object returned by car::Anova for a purely between-subjects ANOVA) the object is returned unaltered. The elements of the list returned by univ are: anova, mauchly, and spehricity.correction (containing both, Greenhouse-Geisser and Hyundt-Feldt correction). If return = "marginal" A list with data.frames containing the marginal means for all effects. Numerical variables are ignored. If return = "aov", an object returned from aov with the (possibly aggregated) data fitted with aov using "contr.sum" for all factors as long as check.contrasts = TRUE. This object can be passed to lsmeans::lsmeans for post-hoc tests or lsmeans::lsmip for plotting. Note that aov is not reliably working for unbalanced data.

encoding

UTF-8

Details

Type 3 sums of squares are default in afex. Note that type 3 sums of squares are said to be dangerous and/or problematic. On the other side they are the default in in SPSS and SAS and recommended by e.g. Maxwell and Delaney (2004). For a brief discussion see http://stats.stackexchange.com/q/6208/442{here}. However, note that lower order effects (e.g., main effects) in type 3 ANOVAs are only meaningful with http://www.ats.ucla.edu/stat/mult_pkg/faq/general/effect.htm{effects coding}. That is, contrasts should be set to contr.sum via options(contrasts=c('contr.sum','contr.poly')). This should be done automatically when loading afex and afex will issue a warning when running type 3 SS and http://www.ats.ucla.edu/stat/r/library/contrast_coding.htm{other coding schemes}. You can check the coding with options("contrasts"). The formulas for aov.car or aov4 must contain a single Error term specyfying the ID column and potential within-subject factors (you can use mixed with multiple error terms). Factors outside the Error term are treated as between-subject factors (the within-subject factors specified in the Error term are ignored outside the Error term, i.e., it is not necessary to specify them outside the Error term, see Examples). Suppressing the intercept (i.e, via 0 + or - 1) is ignored. Specific specifications of effects (e.g., excluding terms with - or using ^) could be okay but is not tested. Using the I or poly function within the formula is not tested and not supported! For ez.glm either between or within must not be NULL. ez.glm will concatante all between-subject factors using * (i.e., producing all main effects and interactions) and all covariates by + (i.e., adding only the main effects to the existing between-subject factors). The within-subject factors do fully interact with all between-subject factors and covariates. This is essentially identical to the behavior of SPSS's glm function. To run an ANCOVA you need to set factorize = FALSE and make sure that all variables have the correct type (i.e., factors are factors and numeric variables are numeric and centered). Note that the default behavior is to return a nice.anova data.frame. This includes calculation of generalized eta squared for which all non manipluated (i.e., observed) variables need to be specified via the observed argument. Changing the effect size to "pes" (partial eta-squared) via args.return or the return value via return removes this necessity. If check.contrasts = TRUE, contrasts will be set to "contr.sum" for all between-subject factors if default contrasts are not equal to "contr.sum" or attrib(factor, "contrasts") != "contr.sum". (within-subject factors are hard-coded "contr.sum".)

References

Maxwell, S. E., & Delaney, H. D. (2004). Designing Experiments and Analyzing Data: A Model-Comparisons Perspective. Mahwah, N.J.: Lawrence Erlbaum Associates.

See Also

nice.anova creats the nice ANOVA tables which are by default returned. See also there for a slightly longer discussion of the available effect sizes. mixed provides a (formula) interface for obtaining p-values for mixed-models via lme4.

Examples

# Examples from a pureyl within-design from
# Maxwell & Delaney (2004, Chapter 11),
# Table 12.5 (p. 578):
data(md_12.1)
ez.glm("id", "rt", md_12.1, within = c("angle", "noise"), 
       args.return=list(correction = "none", es = "none"))

# Default output
ez.glm("id", "rt", md_12.1, within = c("angle", "noise"))       


# examples using obk.long (see ?obk.long), a long version of the OBrienKaiser dataset from car.

data(obk.long, package = "afex")

# run univariate mixed ANOVA for the full design:
aov.car(value ~ treatment * gender + Error(id/(phase*hour)), 
        data = obk.long, observed = "gender")

aov4(value ~ treatment * gender + (phase*hour|id), 
        data = obk.long, observed = "gender")

ez.glm("id", "value", obk.long, between = c("treatment", "gender"), 
        within = c("phase", "hour"), observed = "gender")

# both calls return the same:
##                         Effect          df   MSE         F  ges      p
## 1                    treatment       2, 10 22.81    3.94 +  .20    .05
## 2                       gender       1, 10 22.81    3.66 +  .11    .08
## 3             treatment:gender       2, 10 22.81      2.86  .18    .10
## 4                        phase 1.60, 15.99  5.02 16.13 ***  .15  .0003
## 5              treatment:phase 3.20, 15.99  5.02    4.85 *  .10    .01
## 6                 gender:phase 1.60, 15.99  5.02      0.28 .003    .71
## 7       treatment:gender:phase 3.20, 15.99  5.02      0.64  .01    .61
## 8                         hour 1.84, 18.41  3.39 16.69 ***  .13 <.0001
## 9               treatment:hour 3.68, 18.41  3.39      0.09 .002    .98
## 10                 gender:hour 1.84, 18.41  3.39      0.45 .004    .63
## 11       treatment:gender:hour 3.68, 18.41  3.39      0.62  .01    .64
## 12                  phase:hour 3.60, 35.96  2.67      1.18  .02    .33
## 13        treatment:phase:hour 7.19, 35.96  2.67      0.35 .009    .93
## 14           gender:phase:hour 3.60, 35.96  2.67      0.93  .01    .45
## 15 treatment:gender:phase:hour 7.19, 35.96  2.67      0.74  .02    .65


# replicating ?Anova using aov.car:
aov.car(value ~ treatment * gender + Error(id/(phase*hour)), 
        data = obk.long, type = 2, return = "Anova")
# in contrast to aov you do not need the within-subject factors outside Error()

# replicating ?Anova using ez.glm:
ez.glm("id", "value", obk.long, c("treatment", "gender"), 
        c("phase", "hour"), type = 2, return = "Anova")

#both return:
## Type II Repeated Measures MANOVA Tests: Pillai test statistic
##                             Df test stat approx F num Df den Df       Pr(>F)    
## (Intercept)                  1     0.970      318      1     10 0.0000000065 ***
## treatment                    2     0.481        5      2     10      0.03769 *  
## gender                       1     0.204        3      1     10      0.14097    
## treatment:gender             2     0.364        3      2     10      0.10447    
## phase                        1     0.851       26      2      9      0.00019 ***
## treatment:phase              2     0.685        3      4     20      0.06674 .  
## gender:phase                 1     0.043        0      2      9      0.82000    
## treatment:gender:phase       2     0.311        1      4     20      0.47215    
## hour                         1     0.935       25      4      7      0.00030 ***
## treatment:hour               2     0.301        0      8     16      0.92952    
## gender:hour                  1     0.293        1      4      7      0.60237    
## treatment:gender:hour        2     0.570        1      8     16      0.61319    
## phase:hour                   1     0.550        0      8      3      0.83245    
## treatment:phase:hour         2     0.664        0     16      8      0.99144    
## gender:phase:hour            1     0.695        1      8      3      0.62021    
## treatment:gender:phase:hour  2     0.793        0     16      8      0.97237    
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 

# ANCOVA: adding a covariate (necessary to set factorize = FALSE)
aov.car(value ~ treatment * gender + age + Error(id/(phase*hour)), 
        data = obk.long, observed = c("gender", "age"), factorize = FALSE)

aov4(value ~ treatment * gender + age + (phase*hour|id), 
        data = obk.long, observed = c("gender", "age"), factorize = FALSE)


ez.glm("id", "value", obk.long, between = c("treatment", "gender"), 
        within = c("phase", "hour"), covariate = "age", 
        observed = c("gender", "age"), factorize = FALSE)

# aggregating over one within-subjects factor (phase) with warning:
aov.car(value ~ treatment * gender + Error(id/hour), data = obk.long, observed = "gender")

ez.glm("id", "value", obk.long, c("treatment", "gender"), "hour", observed = "gender")

# runs with "numeric" factors
obk.long$hour2 <- as.numeric(as.character(obk.long$hour))

aov.car(value ~ treatment * gender + Error(id/hour2), 
        data = obk.long, type = 2,observed = c("gender"))

# only between
aov.car(value ~ treatment * gender + Error(id), 
        data = obk.long, observed = c("gender"))
aov4(value ~ treatment * gender + (1|id), print.formula = TRUE,
        data = obk.long, observed = c("gender"))
ez.glm("id", "value", obk.long, c("treatment", "gender"), 
        within = NULL, print.formula = TRUE, observed = "gender")

# only within
aov.car(value ~ Error(id/(phase*hour)), data = obk.long, type = 2)

aov4(value ~ (phase*hour|id), data = obk.long, type = 2, 
     print.formula = TRUE)

ez.glm("id", "value", obk.long,  NULL, c("phase", "hour"), 
        type = 2, print.formula = TRUE)

# using return = "full":

str(aov.car(value ~ Error(id/(phase*hour)), data = obk.long, return = "full"), 1)

## List of 4
##  $ Anova:List of 14
##   ..- attr(*, "class")= chr "Anova.mlm"
##  $ lm   :List of 11
##   ..- attr(*, "class")= chr [1:2] "mlm" "lm"
##  $ data :'data.frame':  16 obs. of  16 variables:
##  $ idata:'data.frame':  15 obs. of  2 variables:
##  $ marginal:List of 3

# use args.return arguments:
aov.car(value ~ treatment * gender + Error(id/(phase*hour)), 
        data = obk.long, args.return = list(correction = "none", es = "pes"))

aov.car(value ~ treatment * gender + Error(id/(phase*hour)), 
        data = obk.long,observed = "gender", 
        args.return = list(correction = "none", MSE = FALSE))