ezMixed: Compute evidence for fixed effects in an mixed effects...
In ez: Easy Analysis and Visualization of Factorial Experiments
Description
Usage
Arguments
Details
Value
Author(s)
References
See Also
Examples
Description
This function provides assessment of fixed effects and their interactions via generalized mixed effects modelling, or generalized additive mixed effects modelling for effects involving numeric predictors to account for potentially non-linear effects of such predictors. See Details section below for implementation notes.
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
ezMixed(
data
, dv
, family = gaussian
, random
, fixed
, covariates = NULL
, add_q = FALSE
, fix_gam = TRUE
, cov_gam = TRUE
, gam_smooth = c('s','te')
, gam_bs = 'ts'
, gam_k = Inf
, use_bam = FALSE
, alarm = FALSE
, term_labels = NULL
, highest = Inf
, return_models = TRUE
, correction = AIC
, progress_dir = NULL
, resume = FALSE
, parallelism = 'none'
, gam_args = NULL
, mer_args = NULL
)
Arguments
data
Data frame containing the data to be analyzed.
dv
.() object specifying the column in data that contains the dependent variable. Values in this column must be numeric.
family
Family to use to represent error.
random
.() object specifying one or more columns in data that contain random effects.
fixed
.() object specifying one or more columns in data that contain fixed effects.
covariates
.() object specifying one or more columns in data that contain variables to be used as fixed effect covariates.
add_q
Logical. If TRUE, quantile values of each observation will be computed for each effect and interaction and these quantile values will be added as a fixed effect predictor. This permits investigating the effect of the fixed effect predictors specified in fixed on the shape of the distribution of residuals. Of course, this only really makes sense when there IS a distribution of residuals (i.e. not binomial data).
fix_gam
Logical. If TRUE (default), generalized additive modelling is used to evaluate the possibly-non-linear effects of numeric fixed effect predictors.
cov_gam
Logical. If TRUE (default), generalized additive modelling is used to represent the possibly-non-linear effects of numeric covariates.
gam_smooth
Vector of one or more elements that are character strings specifying the name of the smoother to use when using gam. If a list of two elements, the first element will be used when evaluating effects and interactions that include a single numeric predictor, while the second element will be used when evaluating effects and interactions that involve multiple numeric predictors.
gam_bs
Character specifying the name of the smooth term to use when using gam.
gam_k
Numeric value specifying the maximum value for k to supply to calls to gam. Higher values yield longer computation times but may better capture non-linear phenomena. If set to Inf (default), ezMixed will automatically use the maximum possible value for k given the number of unique combinations of values in the numeric predictors being evaluated. If a finite positive value is supplied, k will be set to that value or less (if the supplied k exceeds the maximum possible k for a given effect).
use_bam
Logical. If TRUE, bam is used rather than gam.
alarm
Logical. If TRUE, call the alarm function when ezMixed completes.
term_labels
Vector of one or more elements that are character strings specifying effects to explore (useful when you want only a subset of all possible effects and interactions between the predictors supplied to the fixed argument).
highest
Integer specifying the highest order interaction between the fixed effects to test. The default value, Inf, will test to the highest possible order.
return_models
Logical. If TRUE, the returned list object will also include each lmer model (can become memory intensive for complex models and/or large data sets).
correction
Name of a correction for complexity to apply (ex. AIC, BIC, etc) to each model's likelihood before computing likelihood ratios.
progress_dir
Character string specifying name of a folder to be created to store results as they are computed (to save RAM).
resume
Logical. If TRUE and a value is passed to the progress_dir argument, the progress directory will be searched for already completed effects and resume from these. Useful if a run was interrupted.
parallelism
Character string specifying whether and how to compute models in parallel. If “none”, no parallelism will be employed. If “pair”, the restricted and unrestricted models for each effect will be computed in parallel (therefore using only 2 cores). If “full”, then effects themselves will be computed in parallel (using all available cores). Parallelism assumes that a parallel backend has been specified (as in library(doMC);options(cores=4);registerDoMC()) and is likely only to work when running R from a unix terminal.
gam_args
Single character string representing arguments to be passed to calls to gam.
mer_args
Single character string representing arguments to be passed to calls to lmer (or glmer if the value to the family argument is not gaussian).
Details
Computation is achieved via lmer, or gam when the effect under evaluation includes a numeric predictor. Assessment of each effect of interest necessitates building two models: (1) a “unrestricted” model that contains the effect of interest plus any lower order effects and (2) a “restricted” model that contains only the lower order effects (thus “restricting” the effect of interest to zero). These are then compared by means of a likelihood ratio, which needs to be corrected to account for the additional complexity of the unrestricted model relative to the restricted model. The default applied correction is Akaike's Information Criterion (AIC), which in the context of mixed effects models has been demonstrated to be asymptotically equivalent to cross-validation, a gold-standard technique for ensuring that model comparisons optimize prediction of new data.
The complexity-corrected likelihood ratio returned by ezMixed is represented on the log-base-2 scale, which has the following convenient properties:
(1) Resulting values can be discussed as representing “bits of evidence” for or against the evaluated effect.
(2) The bits scale permits easy representation of both very large and very small likelihood ratios.
(3) The bits scale represents equivalent evidence between the restricted and unrestricted models by a value of 0.
(4) The bits scale represents ratios favoring the restricted model symmetrically to those favoring the unrestricted model. That is, say one effect obtains a likelihood ratio of 8, and another effect obtains a likelihood ratio of 0.125; both ratios indicate the same degree of imbalance of evidence (8:1 and 1:8) and on the bits scale they faithfully represent this symmetry as values 3 and -3, respectively.
Value
A list with the following elements:
summary
A data frame summarizing the results, including whether warnings or errors occurred during the assessment of each effect and the bits of evidence associated with each.
formulae
A list of lists, each named for an effect and containing two elements named “unrestricted” and “restricted”, which in turn contain the right-hand-side formulae used to fit the unrestricted and restricted models, respectively.
errors
A list similar to formulae, but instead storing errors encountered in fitting each model.
warnings
A list similar to formulae, but instead storing warnings encountered in fitting each model.
models
(If requested by setting return_models=TRUE) A list similar to formulae but instead storing each fitted model.
Author(s)
Michael A. Lawrence mike.lwrnc@gmail.com
Visit the ez development site at http://github.com/mike-lawrence/ez
for the bug/issue tracker and the link to the mailing list.
References
Glover S, Dixon P. (2004) Likelihood ratios: a simple and flexible statistic for empirical psychologists. Psychonomic Bulletin and Review, 11 (5), 791-806.
Fang, Y. (2011). Asymptotic equivalence between cross-validations and Akaike information criteria in mixed-effects models. Journal of the American Statistical Association, 9, 15-21.
See Also
lmer, glmer, gam, ezMixedProgress, ezPredict, ezPlot2
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#Read in the ANT data (see ?ANT).
data(ANT)
head(ANT)
ezPrecis(ANT)
#Run ezMixed on the accurate RT data
rt = ezMixed(
data = ANT[ANT$error==0,]
, dv = .(rt)
, random = .(subnum)
, fixed = .(cue,flank,group)
)
print(rt$summary)
## Not run:
#Run ezMixed on the error rate data
er = ezMixed(
data = ANT
, dv = .(error)
, random = .(subnum)
, fixed = .(cue,flank,group)
, family = 'binomial'
)
print(er$summary)
## End(Not run)
Example output
subnum group block trial cue flank location direction rt
1 1 Treatment 1 1 None Neutral up left 398.6773
2 1 Treatment 1 2 Center Neutral up left 389.1822
3 1 Treatment 1 3 Double Neutral up left 333.2186
4 1 Treatment 1 4 Spatial Neutral up left 419.7640
5 1 Treatment 1 5 None Congruent up left 446.4754
6 1 Treatment 1 6 Center Congruent up left 338.9766
error
1 0
2 0
3 0
4 0
5 0
6 0
Data frame dimensions: 5760 rows, 10 columns
type missing values min max
subnum factor 0 20 1 20
group factor 0 2 Control Treatment
block numeric 0 6 1 6
trial numeric 0 48 1 48
cue factor 0 4 None Spatial
flank factor 0 3 Neutral Incongruent
location factor 0 2 down up
direction factor 0 2 left right
rt numeric 0 5760 179.5972 657.6986
error numeric 0 2 0 1
bits e w effect
------ - - ------
cue
NA X - cue
flank
NA X - flank
group
NA X - group
cue:flank
NA X - cue:flank
cue:group
NA X - cue:group
flank:group
NA X - flank:group
cue:flank:group
NA X - cue:flank:group
Time taken for ezMixed() to complete: 1 seconds
effect errors warnings bits
1 cue TRUE FALSE NA
2 flank TRUE FALSE NA
3 group TRUE FALSE NA
4 cue:flank TRUE FALSE NA
5 cue:group TRUE FALSE NA
6 flank:group TRUE FALSE NA
7 cue:flank:group TRUE FALSE NA
bits e w effect
------ - - ------
cue
NA X - cue
flank
NA X - flank
group
NA X - group
cue:flank
NA X - cue:flank
cue:group
NA X - cue:group
flank:group
NA X - flank:group
cue:flank:group
NA X - cue:flank:group
Time taken for ezMixed() to complete: 1 seconds
effect errors warnings bits
1 cue TRUE FALSE NA
2 flank TRUE FALSE NA
3 group TRUE FALSE NA
4 cue:flank TRUE FALSE NA
5 cue:group TRUE FALSE NA
6 flank:group TRUE FALSE NA
7 cue:flank:group TRUE FALSE NA
ez documentation built on May 2, 2019, 3:46 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Author(s) References See Also Examples
Description
This function provides assessment of fixed effects and their interactions via generalized mixed effects modelling, or generalized additive mixed effects modelling for effects involving numeric predictors to account for potentially non-linear effects of such predictors. See Details section below for implementation notes.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | ezMixed(
data
, dv
, family = gaussian
, random
, fixed
, covariates = NULL
, add_q = FALSE
, fix_gam = TRUE
, cov_gam = TRUE
, gam_smooth = c('s','te')
, gam_bs = 'ts'
, gam_k = Inf
, use_bam = FALSE
, alarm = FALSE
, term_labels = NULL
, highest = Inf
, return_models = TRUE
, correction = AIC
, progress_dir = NULL
, resume = FALSE
, parallelism = 'none'
, gam_args = NULL
, mer_args = NULL
)
|
Arguments
data |
Data frame containing the data to be analyzed. |
dv |
.() object specifying the column in |
family |
Family to use to represent error. |
random |
.() object specifying one or more columns in |
fixed |
.() object specifying one or more columns in |
covariates |
.() object specifying one or more columns in |
add_q |
Logical. If TRUE, quantile values of each observation will be computed for each effect and interaction and these quantile values will be added as a fixed effect predictor. This permits investigating the effect of the fixed effect predictors specified in |
fix_gam |
Logical. If TRUE (default), generalized additive modelling is used to evaluate the possibly-non-linear effects of numeric fixed effect predictors. |
cov_gam |
Logical. If TRUE (default), generalized additive modelling is used to represent the possibly-non-linear effects of numeric covariates. |
gam_smooth |
Vector of one or more elements that are character strings specifying the name of the smoother to use when using gam. If a list of two elements, the first element will be used when evaluating effects and interactions that include a single numeric predictor, while the second element will be used when evaluating effects and interactions that involve multiple numeric predictors. |
gam_bs |
Character specifying the name of the smooth term to use when using gam. |
gam_k |
Numeric value specifying the maximum value for |
use_bam |
Logical. If TRUE, |
alarm |
Logical. If TRUE, call the |
term_labels |
Vector of one or more elements that are character strings specifying effects to explore (useful when you want only a subset of all possible effects and interactions between the predictors supplied to the |
highest |
Integer specifying the highest order interaction between the fixed effects to test. The default value, |
return_models |
Logical. If TRUE, the returned list object will also include each lmer model (can become memory intensive for complex models and/or large data sets). |
correction |
Name of a correction for complexity to apply (ex. AIC, BIC, etc) to each model's likelihood before computing likelihood ratios. |
progress_dir |
Character string specifying name of a folder to be created to store results as they are computed (to save RAM). |
resume |
Logical. If TRUE and a value is passed to the |
parallelism |
Character string specifying whether and how to compute models in parallel. If “none”, no parallelism will be employed. If “pair”, the restricted and unrestricted models for each effect will be computed in parallel (therefore using only 2 cores). If “full”, then effects themselves will be computed in parallel (using all available cores). Parallelism assumes that a parallel backend has been specified (as in |
gam_args |
Single character string representing arguments to be passed to calls to |
mer_args |
Single character string representing arguments to be passed to calls to |
Details
Computation is achieved via lmer, or gam when the effect under evaluation includes a numeric predictor. Assessment of each effect of interest necessitates building two models: (1) a “unrestricted” model that contains the effect of interest plus any lower order effects and (2) a “restricted” model that contains only the lower order effects (thus “restricting” the effect of interest to zero). These are then compared by means of a likelihood ratio, which needs to be corrected to account for the additional complexity of the unrestricted model relative to the restricted model. The default applied correction is Akaike's Information Criterion (AIC), which in the context of mixed effects models has been demonstrated to be asymptotically equivalent to cross-validation, a gold-standard technique for ensuring that model comparisons optimize prediction of new data.
The complexity-corrected likelihood ratio returned by ezMixed is represented on the log-base-2 scale, which has the following convenient properties:
(1) Resulting values can be discussed as representing “bits of evidence” for or against the evaluated effect.
(2) The bits scale permits easy representation of both very large and very small likelihood ratios.
(3) The bits scale represents equivalent evidence between the restricted and unrestricted models by a value of 0.
(4) The bits scale represents ratios favoring the restricted model symmetrically to those favoring the unrestricted model. That is, say one effect obtains a likelihood ratio of 8, and another effect obtains a likelihood ratio of 0.125; both ratios indicate the same degree of imbalance of evidence (8:1 and 1:8) and on the bits scale they faithfully represent this symmetry as values 3 and -3, respectively.
Value
A list with the following elements:
summary |
A data frame summarizing the results, including whether warnings or errors occurred during the assessment of each effect and the bits of evidence associated with each. |
formulae |
A list of lists, each named for an effect and containing two elements named “unrestricted” and “restricted”, which in turn contain the right-hand-side formulae used to fit the unrestricted and restricted models, respectively. |
errors |
A list similar to |
warnings |
A list similar to |
models |
(If requested by setting |
Author(s)
Michael A. Lawrence mike.lwrnc@gmail.com
Visit the ez development site at http://github.com/mike-lawrence/ez
for the bug/issue tracker and the link to the mailing list.
References
Glover S, Dixon P. (2004) Likelihood ratios: a simple and flexible statistic for empirical psychologists. Psychonomic Bulletin and Review, 11 (5), 791-806.
Fang, Y. (2011). Asymptotic equivalence between cross-validations and Akaike information criteria in mixed-effects models. Journal of the American Statistical Association, 9, 15-21.
See Also
lmer, glmer, gam, ezMixedProgress, ezPredict, ezPlot2
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | #Read in the ANT data (see ?ANT).
data(ANT)
head(ANT)
ezPrecis(ANT)
#Run ezMixed on the accurate RT data
rt = ezMixed(
data = ANT[ANT$error==0,]
, dv = .(rt)
, random = .(subnum)
, fixed = .(cue,flank,group)
)
print(rt$summary)
## Not run:
#Run ezMixed on the error rate data
er = ezMixed(
data = ANT
, dv = .(error)
, random = .(subnum)
, fixed = .(cue,flank,group)
, family = 'binomial'
)
print(er$summary)
## End(Not run)
|
Example output
subnum group block trial cue flank location direction rt
1 1 Treatment 1 1 None Neutral up left 398.6773
2 1 Treatment 1 2 Center Neutral up left 389.1822
3 1 Treatment 1 3 Double Neutral up left 333.2186
4 1 Treatment 1 4 Spatial Neutral up left 419.7640
5 1 Treatment 1 5 None Congruent up left 446.4754
6 1 Treatment 1 6 Center Congruent up left 338.9766
error
1 0
2 0
3 0
4 0
5 0
6 0
Data frame dimensions: 5760 rows, 10 columns
type missing values min max
subnum factor 0 20 1 20
group factor 0 2 Control Treatment
block numeric 0 6 1 6
trial numeric 0 48 1 48
cue factor 0 4 None Spatial
flank factor 0 3 Neutral Incongruent
location factor 0 2 down up
direction factor 0 2 left right
rt numeric 0 5760 179.5972 657.6986
error numeric 0 2 0 1
bits e w effect
------ - - ------
cue
NA X - cue
flank
NA X - flank
group
NA X - group
cue:flank
NA X - cue:flank
cue:group
NA X - cue:group
flank:group
NA X - flank:group
cue:flank:group
NA X - cue:flank:group
Time taken for ezMixed() to complete: 1 seconds
effect errors warnings bits
1 cue TRUE FALSE NA
2 flank TRUE FALSE NA
3 group TRUE FALSE NA
4 cue:flank TRUE FALSE NA
5 cue:group TRUE FALSE NA
6 flank:group TRUE FALSE NA
7 cue:flank:group TRUE FALSE NA
bits e w effect
------ - - ------
cue
NA X - cue
flank
NA X - flank
group
NA X - group
cue:flank
NA X - cue:flank
cue:group
NA X - cue:group
flank:group
NA X - flank:group
cue:flank:group
NA X - cue:flank:group
Time taken for ezMixed() to complete: 1 seconds
effect errors warnings bits
1 cue TRUE FALSE NA
2 flank TRUE FALSE NA
3 group TRUE FALSE NA
4 cue:flank TRUE FALSE NA
5 cue:group TRUE FALSE NA
6 flank:group TRUE FALSE NA
7 cue:flank:group TRUE FALSE NA
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.