afex (version 0.18-0)

mixed: p-values for fixed effects of mixed-model via lme4::lmer()

Description

Calculates p-values for all fixed effects in a mixed model. The default method "KR" (= Kenward-Roger) as well as method="S" (Satterthwaite) support LMMs and fit the model with lmer) and then pass it to either anova.merModLmerTest (or Anova). The other methods ("LRT" = likelihood-ratio tests and "PB" = parametric bootstrap) support both LMMs and GLMMs (i.e., with family argument) and fit a full model and restricted models in which the parameters corresponding to the effect (i.e., model term) are withhold (i.e., fixed to 0) and tests statistics are based on comparing the full model with the restricted models. The default is tests based on Type 3 sums of squares. print, summary, and anova methods for the returned object of class "mixed" are available (the last two return the same data.frame). lmer_alt is simply a wrapper for mixed that only returns the "merMod" object and correctly uses the || notation to remove correlation among factors, but otherwise behaves like g/lmer (as for mixed, it calls glmer as soon as a family argument is present).

Usage

mixed(formula, data, type = afex_options("type"),
  method = afex_options("method_mixed"), per_parameter = NULL,
  args_test = list(), test_intercept = FALSE,
  check_contrasts = afex_options("check_contrasts"), expand_re = FALSE,
  all_fit = FALSE, set_data_arg = TRUE, progress = TRUE, cl = NULL,
  return = "mixed", sig_symbols = afex_options("sig_symbols"), ...)

lmer_alt(formula, data, check_contrasts = FALSE, ...)

Arguments

formula

a formula describing the full mixed-model to be fitted. As this formula is passed to lmer, it needs at least one random term.

data

data.frame containing the data. Should have all the variables present in fixed, random, and dv as columns.

type

type of test on which effects are based. Default is to use type 3 tests, taken from afex_options.

method

character vector indicating which methods for obtaining p-values should be used: "KR" corresponds to the Kenward-Roger approximation for degrees of freedom (only LMMs), "S" corresponds to the Satterthwaite approximation for degrees of freedom (via lmerTest, only LMMs), "PB" calculates p-values based on parametric bootstrap, "LRT" calculates p-values via the likelihood ratio tests implemented in the anova method for merMod objects (only recommended for models with many [i.e., > 50] levels for the random factors). The default (currently "KR") is taken from afex_options. For historical compatibility "nested-KR" is also supported which was the default KR-method in previous versions.

per_parameter

character vector specifying for which variable tests should be run for each parameter (instead for the overall effect). Can be useful e.g., for testing ordered factors. Uses grep for selecting parameters among the fixed effects so regular expressions (regex) are possible. See Examples.

args_test

list of arguments passed to the function calculating the p-values. See Details.

test_intercept

logical. Whether or not the intercept should also be fitted and tested for significance. Default is FALSE. Only relevant if type = 3.

check_contrasts

logical. Should contrasts be checked and (if necessary) changed to "contr.sum"? See Details. The default ("TRUE") is taken from afex_options.

expand_re

logical. Should random effects terms be expanded (i.e., factors transformed into numerical variables) before fitting with (g)lmer? Allows to use "||" notation with factors.

all_fit

logical. Should all_fit be used to fit each model with each available optimization algorithm and the results that provided the best fit in each case be used? Warning: This can dramatically increase the optimization time. Adds two new attributes to the returned object designating which algorithm was selected and the log-likelihoods for each algorithm. Note that only warnings from the initial fit are emitted during fitting. The warnings of the chosen models are emitted when printing the returned object.

set_data_arg

logical. Should the data argument in the slot call of the merMod object returned from lmer be set to the passed data argument? Otherwise the name will be data. Helpful if fitted objects are used afterwards (e.g., using lsmeans). Default is TRUE.

progress

if TRUE, shows progress with a text progress bar and other status messages during fitting.

cl

A vector identifying a cluster; used for distributing the estimation of the different models using several cores (if seveal models are calculated). See examples. If ckeck.contrasts, mixed sets the current contrasts (getOption("contrasts")) at the nodes. Note this does not distribute calculation of p-values (e.g., when using method = "PB") across the cluster. Use args_test for this.

return

the default is to return an object of class "mixed". return = "merMod" will skip the calculation of all submodels and p-values and simply return the full model fitted with lmer. Can be useful in combination with expand_re = TRUE which allows to use "||" with factors. return = "data" will not fit any models but just return the data that would have been used for fitting the model (note that the data is also part of the returned object).

sig_symbols

Character. What should be the symbols designating significance? When entering an vector with length(sig.symbol) < 4 only those elements of the default (c(" +", " *", " **", " ***")) will be replaced. sig_symbols = "" will display the stars but not the +, sig_symbols = rep("", 4) will display no symbols. The default is given by afex_options("sig_symbols").

...

further arguments (such as weights/family) passed to lmer/glmer, such as control.

Value

An object of class "mixed" (i.e., a list) with the following elements:

  1. anova_table a data.frame containing the statistics returned from KRmodcomp. The stat column in this data.frame gives the value of the test statistic, an F-value for method = "KR" and a chi-square value for the other two methods.

  2. full_model the "lmerMod" object returned from fitting the full mixed model.

  3. restricted_models a list of "lmerMod" objects from fitting the restricted models (i.e., each model lacks the corresponding effect)

  4. tests a list of objects returned by the function for obtaining the p-values.

  5. data The data used for fitting (i.e., after excluding missing rows and applying expand_re if requested).

It also has the following attributes, "type" and "method". And the attributes "all_fit_selected" and "all_fit_logLik" if all_fit=TRUE.

Two similar methods exist for objects of class "mixed": print and anova. They print a nice version of the anova_table element of the returned object (which is also invisibly returned). This methods omit some columns and nicely round the other columns. The following columns are always printed:

  1. Effect name of effect

  2. p.value estimated p-value for the effect

For LMMs with method="KR" or method="S" the following further columns are returned (note: the Kenward-Roger correction does two separate things: (1) it computes an effective number for the denominator df; (2) it scales the statistic by a calculated amount, see also http://stackoverflow.com/a/25612960/289572):

  1. F computed F statistic

  2. ndf numerator degrees of freedom (number of parameters used for the effect)

  3. ddf denominator degrees of freedom (effective residual degrees of freedom for testing the effect), computed from the Kenward-Roger correction using pbkrtest::KRmodcomp

  4. F.scaling scaling of F-statistic computing from Kenward-Roger approximation (only printed if method="nested-KR")

For models with method="LRT" the following further columns are returned:

  1. df.large degrees of freedom (i.e., estimated paramaters) for full model (i.e., model containing the corresponding effect)

  2. df.small degrees of freedom (i.e., estimated paramaters) for restricted model (i.e., model without the corresponding effect)

  3. chisq 2 times the difference in likelihood (obtained with logLik) between full and restricted model

  4. df difference in degrees of freedom between full and restricted model (p-value is based on these df).

For models with method="PB" the following further column is returned:

  1. stat 2 times the difference in likelihood (obtained with logLik) between full and restricted model (i.e., a chi-square value).

Note that anova can also be called with additional mixed and/or merMod objects. In this casethe full models are passed on to anova.merMod (with refit=FALSE, which differs from the default of anova.merMod) which produces the known LRT tables.

The summary method for objects of class mixed simply calls summary.merMod on the full model.

If return = "merMod", an object of class "merMod", as returned from g/lmer, is returned.

Details

For an introduction to mixed-modeling for experimental designs see Barr, Levy, Scheepers, & Tily (2013; I highly recommend reading this paper if you use this function), arguments for using the Kenward-Roger approximation for obtaining p-values are given by Judd, Westfall, and Kenny (2012). Further introductions to mixed-modeling for experimental designs are given by Baayen and colleagues (Baayen, 2008; Baayen, Davidson & Bates, 2008; Baayen & Milin, 2010). Specific recommendations on which random effects structure to specify for confirmatory tests can be found in Barr and colleagues (2013) and Barr (2013), but also see Bates et al. (2015).

p-value Calculations

When method = "KR" (the default, implemented via KRmodcomp), the Kenward-Roger approximation for degrees-of-freedom is calculated using anova.merModLmerTest (if test_intercept=FALSE) or Anova (if test_intercept=TRUE), which is only applicable to linear-mixed models (LMMs). The test statistic in the output is an F-value (F). A similar method that requires less RAM is method = "S" which calculates the Satterthwaite approximation for degrees-of-freedom via anova.merModLmerTest and is also only applicable to LMMs. method = "KR" or method = "S" provide the best control for Type 1 errors for LMMs (Luke, 2017).

method = "PB" calculates p-values using parametric bootstrap using PBmodcomp. This can be used for linear and also generalized linear mixed models (GLMMs) by specifying a family argument to mixed. Note that you should specify further arguments to PBmodcomp via args_test, especially nsim (the number of simulations to form the reference distribution) or cl (for using multiple cores). For other arguments see PBmodcomp. Note that REML (argument to [g]lmer) will be set to FALSE if method is PB.

method = "LRT" calculates p-values via likelihood ratio tests implemented in the anova method for "merMod" objects. This is the method recommended by Barr et al. (2013; which did not test the other methods implemented here). Using likelihood ratio tests is only recommended for models with many levels for the random effects (> 50), but can be pretty helpful in case the other methods fail (due to memory and/or time limitations). The lme4 faq also recommends the other methods over likelihood ratio tests.

Implementation Details

For methods "KR" and "S" type 3 and 2 tests are implemented as in Anova.

For all other methods, type 3 tests are obtained by comparing a model in which only the tested effect is excluded with the full model (containing all effects). For method "nested-KR" (which was the default in previous versions) this corresponds to the (type 3) Wald tests given by car::Anova for "lmerMod" models. The submodels in which the tested effect is excluded are obtained by manually creating a model matrix which is then fitted in "lme4". This is done to avoid R's "feature" to not allow this behavior.

Type 2 tests are truly sequential. They are obtained by comparing a model in which the tested effect and all higher oder effect (e.g., all three-way interactions for testing a two-way interaction) are excluded with a model in which only effects up to the order of the tested effect are present and all higher order effects absent. In other words, there are multiple full models, one for each order of effects. Consequently, the results for lower order effects are identical of whether or not higher order effects are part of the model or not. This latter feature is not consistent with classical ANOVA type 2 tests but a consequence of the sequential tests (and I didn't find a better way of implementing the Type 2 tests). This does not correspond to the (type 2) Wald test reported by car::Anova.

If check_contrasts = TRUE, contrasts will be set to "contr.sum" for all factors in the formula if default contrasts are not equal to "contr.sum" or attrib(factor, "contrasts") != "contr.sum". Furthermore, the current contrasts (obtained via getOption("contrasts")) will be set at the cluster nodes if cl is not NULL.

Expand Random Effects

expand_re = TRUE allows to expand the random effects structure before passing it to lmer. This allows to disable estimation of correlation among random effects for random effects term containing factors using the || notation which may aid in achieving model convergence (see Bates et al., 2015). This is achieved by first creating a model matrix for each random effects term individually, rename and append the so created columns to the data that will be fitted, replace the actual random effects term with the so created variables (concatenated with +), and then fit the model. The variables are renamed by prepending all variables with rei (where i is the number of the random effects term) and replacing ":" with "_by_".

lmer_alt is simply a wrapper for mixed that is intended to behave like lmer (or glmer if a family argument is present), but also allows to use || with factors correctly (by always using expand_re = TRUE). This means that lmer_alt per default does not enforce a specific contrast on factors and only returns the "merMod" object without calculating any additional models or p-values (this is achieved by setting return = "merMod"). Note that it most likely differs from g/lmer in how it handles missing values so it is recommended to only pass data without missing values to it!

One consequence of using expand_re = TRUE is that the data that is fitted will not be the same as the passed data.frame which can lead to problems with e.g., the predict method. However, the actual data uzsed for fitting is also returned as part of the mixed object so can be used from there.

References

Baayen, R. H. (2008). Analyzing linguistic data: a practical introduction to statistics using R. Cambridge, UK; New York: Cambridge University Press.

Baayen, R. H., Davidson, D. J., & Bates, D. M. (2008). Mixed-effects modeling with crossed random effects for subjects and items. Journal of Memory and Language, 59(4), 390-412. doi:10.1016/j.jml.2007.12.005

Baayen, R. H., & Milin, P. (2010). Analyzing Reaction Times. International Journal of Psychological Research, 3(2), 12-28.

Barr, D. J. (2013). Random effects structure for testing interactions in linear mixed-effects models. Frontiers in Quantitative Psychology and Measurement, 328. doi:10.3389/fpsyg.2013.00328

Barr, D. J., Levy, R., Scheepers, C., & Tily, H. J. (2013). Random effects structure for confirmatory hypothesis testing: Keep it maximal. Journal of Memory and Language, 68(3), 255-278. doi:10.1016/j.jml.2012.11.001

Bates, D., Kliegl, R., Vasishth, S., & Baayen, H. (2015). Parsimonious Mixed Models. arXiv:1506.04967 [stat]. Retrieved from http://arxiv.org/abs/1506.04967

Dalal, D. K., & Zickar, M. J. (2012). Some Common Myths About Centering Predictor Variables in Moderated Multiple Regression and Polynomial Regression. Organizational Research Methods, 15(3), 339-362. doi:10.1177/1094428111430540

Judd, C. M., Westfall, J., & Kenny, D. A. (2012). Treating stimuli as a random factor in social psychology: A new and comprehensive solution to a pervasive but largely ignored problem. Journal of Personality and Social Psychology, 103(1), 54-69. doi:10.1037/a0028347

Luke, S. (2017). Evaluating significance in linear mixed-effects models in R. Behavior Research Methods. https://doi.org/10.3758/s13428-016-0809-y

Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates.

See Also

aov_ez and aov_car for convenience functions to analyze experimental deisgns with classical ANOVA or ANCOVA wrapping Anova.

see the following for the data sets from Maxwell and Delaney (2004) used and more examples: md_15.1, md_16.1, and md_16.4.

Examples

Run this code
# NOT RUN {
###########################
## Full Analysis Example ##
###########################

# }
# NOT RUN {
### split-plot experiment (Singmann & Klauer, 2011, Exp. 2)
## between-factor: instruction
## within-factor: inference & type
## hypothesis: three-way interaction
data("sk2011.2")

# use only affirmation problems (S&K also splitted the data like this)
sk2_aff <- droplevels(sk2011.2[sk2011.2$what == "affirmation",])

# set up model with maximal by-participant random slopes 
sk_m1 <- mixed(response ~ instruction*inference*type+(inference*type|id), sk2_aff)

sk_m1 # prints ANOVA table with nicely rounded numbers (i.e., as characters)
nice(sk_m1)  # returns the same but without printing potential warnings
anova(sk_m1) # returns and prints numeric ANOVA table (i.e., not-rounded)
summary(sk_m1) # lmer summary of full model

# same model but using Satterthwaite approximation of df
# very similar results but faster
sk_m1b <- mixed(response ~ instruction*inference*type+(inference*type|id), 
                sk2_aff, method="S")
nice(sk_m1b)
# identical results as:
lmerTest::anova(sk_m1$full_model)

# suppressing correlation among random slopes:
# very similar results, but significantly faster and often less convergence warnings. 
sk_m2 <- mixed(response ~ instruction*inference*type+(inference*type||id), sk2_aff,
               expand_re = TRUE)
sk_m2

## mixed objects can be passed to lsmeans directly:

# recreates basically Figure 4 (S&K, 2011, upper panel)
# only the 4th and 6th x-axis position are flipped
lsmip(sk_m1, instruction~type+inference)

# set up reference grid for custom contrasts:
# this can be made faster via:
lsm.options(lmer.df = "Kenward-Roger") # set df for lsmeans to KR
# lsm.options(lmer.df = "Satterthwaite") # the default
# lsm.options(lmer.df = "asymptotic") # the fastest, no df
(rg1 <- lsmeans(sk_m1, c("instruction", "type", "inference")))

# set up contrasts on reference grid:
contr_sk2 <- list(
  ded_validity_effect = c(rep(0, 4), 1, rep(0, 5), -1, 0),
  ind_validity_effect = c(rep(0, 5), 1, rep(0, 5), -1),
  counter_MP = c(rep(0, 4), 1, -1, rep(0, 6)),
  counter_AC = c(rep(0, 10), 1, -1)
)

# test the main double dissociation (see S&K, p. 268)
contrast(rg1, contr_sk2, adjust = "holm")
# only plausibility effect is not significant here.
# }
# NOT RUN {
###################################################
## Replicating Maxwell & Delaney (2004) Examples ##
###################################################

### replicate results from Table 15.4 (Maxwell & Delaney, 2004, p. 789)
data(md_15.1)
# random intercept plus random slope
(t15.4a <- mixed(iq ~ timecat + (1+time|id),data=md_15.1))

# to also replicate exact parameters use treatment.contrasts and the last level as base level:
contrasts(md_15.1$timecat) <- contr.treatment(4, base = 4)
(t15.4b <- mixed(iq ~ timecat + (1+time|id),data=md_15.1, check_contrasts=FALSE))
summary(t15.4a)  # gives "wrong" parameters extimates
summary(t15.4b)  # identical parameters estimates

# for more examples from chapter 15 see ?md_15.1

### replicate results from Table 16.3 (Maxwell & Delaney, 2004, p. 837)
data(md_16.1)

# original results need treatment contrasts:
(mixed1_orig <- mixed(severity ~ sex + (1|id), md_16.1, check_contrasts=FALSE))
summary(mixed1_orig$full_model)

# p-value stays the same with afex default contrasts (contr.sum),
# but estimates and t-values for the fixed effects parameters change.
(mixed1 <- mixed(severity ~ sex + (1|id), md_16.1))
summary(mixed1$full_model)


# data for next examples (Maxwell & Delaney, Table 16.4)
data(md_16.4)
str(md_16.4)

### replicate results from Table 16.6 (Maxwell & Delaney, 2004, p. 845)
# Note that (1|room:cond) is needed because room is nested within cond.
# p-value (almost) holds.
(mixed2 <- mixed(induct ~ cond + (1|room:cond), md_16.4))
# (differences are dut to the use of Kenward-Roger approximation here,
# whereas M&W's p-values are based on uncorrected df.)

# again, to obtain identical parameter and t-values, use treatment contrasts:
summary(mixed2) # not identical

# prepare new data.frame with contrasts:
md_16.4b <- within(md_16.4, cond <- C(cond, contr.treatment, base = 2))
str(md_16.4b)

# p-value stays identical:
(mixed2_orig <- mixed(induct ~ cond + (1|room:cond), md_16.4b, check_contrasts=FALSE))
summary(mixed2_orig$full_model) # replicates parameters


### replicate results from Table 16.7 (Maxwell & Delaney, 2004, p. 851)
# F-values (almost) hold, p-values (especially for skill) are off
(mixed3 <- mixed(induct ~ cond + skill + (1|room:cond), md_16.4))

# however, parameters are perfectly recovered when using the original contrasts:
mixed3_orig <- mixed(induct ~ cond + skill + (1|room:cond), md_16.4b, check_contrasts=FALSE)
summary(mixed3_orig)


### replicate results from Table 16.10 (Maxwell & Delaney, 2004, p. 862)
# for this we need to center cog:
md_16.4b$cog <- scale(md_16.4b$cog, scale=FALSE)

# F-values and p-values are relatively off:
(mixed4 <- mixed(induct ~ cond*cog + (cog|room:cond), md_16.4b))
# contrast has a relatively important influence on cog
(mixed4_orig <- mixed(induct ~ cond*cog + (cog|room:cond), md_16.4b, check_contrasts=FALSE))

# parameters are again almost perfectly recovered:
summary(mixed4_orig)

####################
## Other Examples ##
####################

# }
# NOT RUN {
# use the obk.long data (not reasonable, no random slopes)
data(obk.long)
mixed(value ~ treatment * phase + (1|id), obk.long)

# Examples for using the per.parammeter argument:
data(obk.long, package = "afex")
obk.long$hour <- ordered(obk.long$hour)

# tests only the main effect parameters of hour individually per parameter.
mixed(value ~ treatment*phase*hour +(1|id), per_parameter = "^hour$", data = obk.long)

# tests all parameters including hour individually
mixed(value ~ treatment*phase*hour +(1|id), per_parameter = "hour", data = obk.long)

# tests all parameters individually
mixed(value ~ treatment*phase*hour +(1|id), per_parameter = ".", data = obk.long)

# example data from package languageR:
# Lexical decision latencies elicited from 21 subjects for 79 English concrete nouns, 
# with variables linked to subject or word. 
data(lexdec, package = "languageR")

# using the simplest model
m1 <- mixed(RT ~ Correct + Trial + PrevType * meanWeight + 
    Frequency + NativeLanguage * Length + (1|Subject) + (1|Word), data = lexdec)
m1
# Mixed Model Anova Table (Type 3 tests, KR-method)
# 
# Model: RT ~ Correct + Trial + PrevType * meanWeight + Frequency + NativeLanguage * 
# Model:     Length + (1 | Subject) + (1 | Word)
# Data: lexdec
#                  Effect         df         F p.value
# 1               Correct 1, 1627.73   8.15 **    .004
# 2                 Trial 1, 1592.43   7.57 **    .006
# 3              PrevType 1, 1605.39      0.17     .68
# 4            meanWeight   1, 75.39 14.85 ***   .0002
# 5             Frequency   1, 76.08 56.53 ***  <.0001
# 6        NativeLanguage   1, 27.11      0.70     .41
# 7                Length   1, 75.83   8.70 **    .004
# 8   PrevType:meanWeight 1, 1601.18    6.18 *     .01
# 9 NativeLanguage:Length 1, 1555.49 14.24 ***   .0002
# ---
# Signif. codes:  0 <U+2018>***<U+2019> 0.001 <U+2018>**<U+2019> 0.01 <U+2018>*<U+2019> 0.05 <U+2018>+<U+2019> 0.1 <U+2018> <U+2019> 1

# Fitting a GLMM using parametric bootstrap:
require("mlmRev") # for the data, see ?Contraception

gm1 <- mixed(use ~ age + I(age^2) + urban + livch + (1 | district), method = "PB",
 family = binomial, data = Contraception, args_test = list(nsim = 10))
## note that nsim = 10 is way too low for all real examples!

#######################
### Using Multicore ###
#######################

require(parallel)
(nc <- detectCores()) # number of cores
cl <- makeCluster(rep("localhost", nc)) # make cluster
# to keep track of what the function is doindg redirect output to outfile:
# cl <- makeCluster(rep("localhost", nc), outfile = "cl.log.txt")

## There are two ways to use multicore:

# 1. Obtain fits with multicore:
mixed(value ~ treatment*phase*hour +(1|id), data = obk.long, method = "LRT", cl = cl)

# 2. Obtain PB samples via multicore: 
mixed(use ~ age + I(age^2) + urban + livch + (1 | district), family = binomial,
 method = "PB", data = Contraception, args_test = list(nsim = 10, cl = cl))

## Both ways can be combined:
mixed(use ~ age + I(age^2) + urban + livch + (1 | district), family = binomial, 
 method = "PB", data = Contraception, args_test = list(nsim = 10, cl = cl), cl = cl)


#### use all_fit = TRUE and expand_re = TRUE:
data("sk2011.2") 
sk2_aff <- droplevels(sk2011.2[sk2011.2$what == "affirmation",])

require(optimx) # uses two more algorithms
sk2_aff_b <- mixed(response ~ instruction*type+(inference*type||id), sk2_aff,
               expand_re = TRUE, all_fit = TRUE)
attr(sk2_aff_b, "all_fit_selected")
attr(sk2_aff_b, "all_fit_logLik")

# considerably faster with multicore:
clusterEvalQ(cl, library(optimx)) # need to load optimx in cluster
sk2_aff_b2 <- mixed(response ~ instruction*type+(inference*type||id), sk2_aff,
               expand_re = TRUE, all_fit = TRUE, cl=cl)
attr(sk2_aff_b2, "all_fit_selected")
attr(sk2_aff_b2, "all_fit_logLik")


stopCluster(cl)

# }

Run the code above in your browser using DataLab