From 9387e5247904da8f4a9c8f2e4ad8722092e63abe Mon Sep 17 00:00:00 2001 From: singmann Date: Sun, 16 Aug 2015 21:09:31 +0200 Subject: [PATCH] shortened startup message, changed line endigs to LF --- .gitignore | 1 + DESCRIPTION | 50 ++-- NAMESPACE | 172 ++++++------ R/afex-package.R | 44 ++-- R/zzz.R | 48 ++-- man/afex-package.Rd | 56 ++-- man/afex_aov-methods.Rd | 106 ++++---- man/afex_options.Rd | 82 +++--- man/allFit.Rd | 122 ++++----- man/aov_car.Rd | 656 +++++++++++++++++++++++----------------------- man/compare.2.vectors.Rd | 164 ++++++------ man/deprecated.Rd | 54 ++-- man/ems.Rd | 92 +++---- man/ks2013.3.Rd | 80 +++--- man/md_12.1.Rd | 98 +++---- man/md_15.1.Rd | 138 +++++----- man/md_16.1.Rd | 78 +++--- man/md_16.4.Rd | 76 +++--- man/mixed.Rd | 666 +++++++++++++++++++++++------------------------ man/nice.Rd | 194 +++++++------- man/obk.long.Rd | 104 ++++---- man/round_ps.Rd | 62 ++--- man/set_sum_contrasts.Rd | 60 ++--- man/sk2011.1.Rd | 90 +++---- man/sk2011.2.Rd | 100 +++---- 25 files changed, 1697 insertions(+), 1696 deletions(-) diff --git a/.gitignore b/.gitignore index b900386..724d6ad 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ # produced vignettes vignettes/*.html vignettes/*.pdf +.Rproj.user diff --git a/DESCRIPTION b/DESCRIPTION index 38392b5..efb9b83 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,25 +1,25 @@ -Package: afex -Type: Package -Title: Analysis of Factorial Experiments -Depends: R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17) -Suggests: ascii, xtable, parallel, plyr, optimx, nloptr, knitr, lattice, multcomp, testthat, mlmRev -Imports: stringr, coin, Matrix, pbkrtest (>= 0.3-6), car, stats, utils -Description: Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. - aov_ez(), aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), - or mixed between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per - row), potentially aggregating multiple observations per individual and cell of the design. mixed() - fits mixed models using lme4::lmer() and computes p-values for all fixed effects using either - Kenward-Roger approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and - GLMMs), or likelihood ratio tests (LMMs and GLMMs). afex uses type 3 sums of squares as default - (imitating commercial statistical software). -URL: https://github.com/singmann/afex -License: GPL (>=3) -Encoding: UTF-8 -VignetteBuilder: knitr -Authors@R: c(person(given="Henrik", family="Singmann", role=c("aut", "cre"), email="singmann+afex@gmail.com"), - person(given="Ben", family="Bolker", role=c("aut")), person(given="Jake", family="Westfall", - role=c("aut")), person(given="Søren", family="Højsgaard", role=c("ctb")), person(given="John", - family="Fox", role=c("ctb")), person(given="Michael A.", family="Lawrence", role=c("ctb")), - person(given="Ulf", family="Mertens", role=c("ctb")) ) -Version: 0.14-1 -Date: 2015-08-13 +Package: afex +Type: Package +Title: Analysis of Factorial Experiments +Depends: R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17) +Suggests: ascii, xtable, parallel, plyr, optimx, nloptr, knitr, lattice, multcomp, testthat, mlmRev +Imports: stringr, coin, Matrix, pbkrtest (>= 0.3-6), car, stats, utils +Description: Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. aov_ez(), + aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), or mixed + between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per row), + potentially aggregating multiple observations per individual and cell of the design. mixed() fits mixed + models using lme4::lmer() and computes p-values for all fixed effects using either Kenward-Roger + approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and GLMMs), or likelihood ratio + tests (LMMs and GLMMs). afex uses type 3 sums of squares as default (imitating commercial statistical + software). +URL: https://github.com/singmann/afex +License: GPL (>=3) +Encoding: UTF-8 +VignetteBuilder: knitr +Authors@R: c(person(given="Henrik", family="Singmann", role=c("aut", "cre"), email="singmann+afex@gmail.com"), + person(given="Ben", family="Bolker", role=c("aut")), person(given="Jake", family="Westfall", role=c("aut")), + person(given="Søren", family="Højsgaard", role=c("ctb")), person(given="John", family="Fox", role=c("ctb")), + person(given="Michael A.", family="Lawrence", role=c("ctb")), person(given="Ulf", family="Mertens", + role=c("ctb")) ) +Version: 0.14-1 +Date: 2015-08-16 diff --git a/NAMESPACE b/NAMESPACE index b6f6351..e814e59 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,86 +1,86 @@ -# Generated by roxygen2 (4.1.1): do not edit by hand - -S3method(anova,afex_aov) -S3method(anova,mixed) -S3method(lsm.basis,afex_aov) -S3method(lsm.basis,mixed) -S3method(nice,afex_aov) -S3method(nice,anova) -S3method(nice,mixed) -S3method(print,afex_aov) -S3method(print,mixed) -S3method(recover.data,afex_aov) -S3method(recover.data,mixed) -S3method(summary,afex_aov) -S3method(summary,mixed) -export(afex_options) -export(allFit) -export(aov.car) -export(aov4) -export(aov_4) -export(aov_car) -export(aov_ez) -export(compare.2.vectors) -export(ems) -export(ez.glm) -export(mixed) -export(nice) -export(round_ps) -export(set_default_contrasts) -export(set_deviation_contrasts) -export(set_effects_contrasts) -export(set_sum_contrasts) -export(set_treatment_contrasts) -import(pbkrtest) -importClassesFrom(Matrix,Matrix) -importFrom(Matrix,Matrix) -importFrom(Matrix,rankMatrix) -importFrom(Matrix,sparseMatrix) -importFrom(car,Anova) -importFrom(coin,approximate) -importFrom(coin,median_test) -importFrom(coin,oneway_test) -importFrom(coin,pvalue) -importFrom(coin,statistic) -importFrom(coin,wilcox_test) -importFrom(lme4,findbars) -importFrom(lme4,fixef) -importFrom(lme4,getME) -importFrom(lme4,glmer) -importFrom(lme4,glmerControl) -importFrom(lme4,isGLMM) -importFrom(lme4,isREML) -importFrom(lme4,lmer) -importFrom(lme4,lmerControl) -importFrom(lme4,nobars) -importFrom(lsmeans,lsm.basis) -importFrom(lsmeans,recover.data) -importFrom(parallel,clusterApplyLB) -importFrom(parallel,clusterCall) -importFrom(parallel,clusterEvalQ) -importFrom(parallel,clusterExport) -importFrom(reshape2,dcast) -importFrom(stats,"contrasts<-") -importFrom(stats,anova) -importFrom(stats,as.formula) -importFrom(stats,coef) -importFrom(stats,logLik) -importFrom(stats,model.frame) -importFrom(stats,model.matrix) -importFrom(stats,setNames) -importFrom(stats,t.test) -importFrom(stats,terms) -importFrom(stats,update) -importFrom(stats,vcov) -importFrom(stats,wilcox.test) -importFrom(stats,xtabs) -importFrom(stringr,str_c) -importFrom(stringr,str_detect) -importFrom(stringr,str_extract) -importFrom(stringr,str_replace_all) -importFrom(utils,ls.str) -importMethodsFrom(Matrix,"%*%") -importMethodsFrom(Matrix,diag) -importMethodsFrom(Matrix,isSymmetric) -importMethodsFrom(Matrix,solve) -importMethodsFrom(Matrix,t) +# Generated by roxygen2 (4.1.1): do not edit by hand + +S3method(anova,afex_aov) +S3method(anova,mixed) +S3method(lsm.basis,afex_aov) +S3method(lsm.basis,mixed) +S3method(nice,afex_aov) +S3method(nice,anova) +S3method(nice,mixed) +S3method(print,afex_aov) +S3method(print,mixed) +S3method(recover.data,afex_aov) +S3method(recover.data,mixed) +S3method(summary,afex_aov) +S3method(summary,mixed) +export(afex_options) +export(allFit) +export(aov.car) +export(aov4) +export(aov_4) +export(aov_car) +export(aov_ez) +export(compare.2.vectors) +export(ems) +export(ez.glm) +export(mixed) +export(nice) +export(round_ps) +export(set_default_contrasts) +export(set_deviation_contrasts) +export(set_effects_contrasts) +export(set_sum_contrasts) +export(set_treatment_contrasts) +import(pbkrtest) +importClassesFrom(Matrix,Matrix) +importFrom(Matrix,Matrix) +importFrom(Matrix,rankMatrix) +importFrom(Matrix,sparseMatrix) +importFrom(car,Anova) +importFrom(coin,approximate) +importFrom(coin,median_test) +importFrom(coin,oneway_test) +importFrom(coin,pvalue) +importFrom(coin,statistic) +importFrom(coin,wilcox_test) +importFrom(lme4,findbars) +importFrom(lme4,fixef) +importFrom(lme4,getME) +importFrom(lme4,glmer) +importFrom(lme4,glmerControl) +importFrom(lme4,isGLMM) +importFrom(lme4,isREML) +importFrom(lme4,lmer) +importFrom(lme4,lmerControl) +importFrom(lme4,nobars) +importFrom(lsmeans,lsm.basis) +importFrom(lsmeans,recover.data) +importFrom(parallel,clusterApplyLB) +importFrom(parallel,clusterCall) +importFrom(parallel,clusterEvalQ) +importFrom(parallel,clusterExport) +importFrom(reshape2,dcast) +importFrom(stats,"contrasts<-") +importFrom(stats,anova) +importFrom(stats,as.formula) +importFrom(stats,coef) +importFrom(stats,logLik) +importFrom(stats,model.frame) +importFrom(stats,model.matrix) +importFrom(stats,setNames) +importFrom(stats,t.test) +importFrom(stats,terms) +importFrom(stats,update) +importFrom(stats,vcov) +importFrom(stats,wilcox.test) +importFrom(stats,xtabs) +importFrom(stringr,str_c) +importFrom(stringr,str_detect) +importFrom(stringr,str_extract) +importFrom(stringr,str_replace_all) +importFrom(utils,ls.str) +importMethodsFrom(Matrix,"%*%") +importMethodsFrom(Matrix,diag) +importMethodsFrom(Matrix,isSymmetric) +importMethodsFrom(Matrix,solve) +importMethodsFrom(Matrix,t) diff --git a/R/afex-package.R b/R/afex-package.R index 03c5470..e9da737 100644 --- a/R/afex-package.R +++ b/R/afex-package.R @@ -1,22 +1,22 @@ -#' Analysis of Factorial Experiments. -#' -#' \tabular{ll}{ -#' Package: \tab afex\cr -#' Type: \tab Package\cr -#' Version: \tab 0.14-1\cr -#' Date: \tab 2015-08-13\cr -#' Depends: \tab R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17)\cr -#' Encoding: \tab UTF-8\cr -#' License: \tab GPL (>=3)\cr -#' URL: \tab https://github.com/singmann/afex\cr -#' } -#' -#' Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. aov_ez(), aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), or mixed between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per row), potentially aggregating multiple observations per individual and cell of the design. mixed() fits mixed models using lme4::lmer() and computes p-values for all fixed effects using either Kenward-Roger approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and GLMMs), or likelihood ratio tests (LMMs and GLMMs). afex uses type 3 sums of squares as default (imitating commercial statistical software). -#' -#' @aliases afex-package -#' @name afex-package -#' @docType package -#' @title The afex Package -#' @author Henrik Singmann, Ben Bolker, Jake Westfall, with contributions from Søren Højsgaard, John Fox, Michael A. Lawrence, Ulf Mertens -#' @keywords package -NULL +#' Analysis of Factorial Experiments. +#' +#' \tabular{ll}{ +#' Package: \tab afex\cr +#' Type: \tab Package\cr +#' Version: \tab 0.14-1\cr +#' Date: \tab 2015-08-16\cr +#' Depends: \tab R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17)\cr +#' Encoding: \tab UTF-8\cr +#' License: \tab GPL (>=3)\cr +#' URL: \tab https://github.com/singmann/afex\cr +#' } +#' +#' Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. aov_ez(), aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), or mixed between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per row), potentially aggregating multiple observations per individual and cell of the design. mixed() fits mixed models using lme4::lmer() and computes p-values for all fixed effects using either Kenward-Roger approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and GLMMs), or likelihood ratio tests (LMMs and GLMMs). afex uses type 3 sums of squares as default (imitating commercial statistical software). +#' +#' @aliases afex-package +#' @name afex-package +#' @docType package +#' @title The afex Package +#' @author Henrik Singmann, Ben Bolker, Jake Westfall, with contributions from Søren Højsgaard, John Fox, Michael A. Lawrence, Ulf Mertens +#' @keywords package +NULL diff --git a/R/zzz.R b/R/zzz.R index 9cbc611..f3f021c 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,24 +1,24 @@ - - -## set default options for afex.options: -.afexEnv <- new.env() -assign("type", 3, envir = .afexEnv) -assign("check.contrasts", TRUE, envir = .afexEnv) -assign("method_mixed", "KR", envir = .afexEnv) -assign("return_aov", "afex_aov", envir = .afexEnv) -assign("es_aov", "ges", envir = .afexEnv) -assign("correction_aov", "GG", envir = .afexEnv) -assign("factorize", TRUE, envir = .afexEnv) - -.onAttach <- function(libname, pkgname) { - #assign(".oldContrasts", options("contrasts"), envir = .GlobalEnv) - packageStartupMessage("************\nWelcome to afex. Important changes in the current version:") - packageStartupMessage("- Functions for computing ANOVAs have been renamed to: aov_car(), aov_ez(), and aov_4().\n- ANOVA functions now return an object of class 'afex_aov' as default, see: ?aov_car\n- Objects of class 'afex_aov' can be directly passed to lsmeans for contrasts and follow-up tests.\n- As 'afex_aov' calculations can be costly reset previous behavior via: afex_options(return_aov='nice')\n- Many more arguments can now be set globally via options, see: afex_options()\n************") - #if (options("contrasts")[[1]][1] != "contr.sum") { - #packageStartupMessage("Setting contrasts to effects coding: options(contrasts=c('contr.sum', 'contr.poly'))\nThis affects all functions using contrasts (e.g., lmer, lm, aov, ...).\nTo reset default settings run: options(contrasts=c('contr.treatment', 'contr.poly')) (all afex functions should be unaffected by this)\n") - # \nPrevious contrasts saved in '.oldContrasts'. - #options(contrasts=c('contr.sum', 'contr.poly')) - #} else packageStartupMessage("Contrasts already set to effects coding: options(contrasts=c('contr.sum', '...'))\n") - #packageStartupMessage("afex loads the required packages (e.g., lme4, car, pbkrtest) in an order that should not lead to problems.\nLoading any of the packages (specifically lme4) beforehand can lead to problems (especially with older versions of either).\nLoading nlme in addition to afex (before or after loading it), may especially lead to problems.\n************") -} - + + +## set default options for afex.options: +.afexEnv <- new.env() +assign("type", 3, envir = .afexEnv) +assign("check.contrasts", TRUE, envir = .afexEnv) +assign("method_mixed", "KR", envir = .afexEnv) +assign("return_aov", "afex_aov", envir = .afexEnv) +assign("es_aov", "ges", envir = .afexEnv) +assign("correction_aov", "GG", envir = .afexEnv) +assign("factorize", TRUE, envir = .afexEnv) + +.onAttach <- function(libname, pkgname) { + #assign(".oldContrasts", options("contrasts"), envir = .GlobalEnv) + packageStartupMessage("************\nWelcome to afex. Important changes in the current version:") + packageStartupMessage("- Functions for ANOVAs have been renamed to: aov_car(), aov_ez(), and aov_4().\n- ANOVA functions return an object of class 'afex_aov' as default, see: ?aov_car\n- 'afex_aov' objects can be passed to lsmeans for contrasts and follow-up tests.\n- Reset previous (faster) behavior via: afex_options(return_aov='nice')\n- Many more arguments can now be set globally via options, see: afex_options()\n************") + #if (options("contrasts")[[1]][1] != "contr.sum") { + #packageStartupMessage("Setting contrasts to effects coding: options(contrasts=c('contr.sum', 'contr.poly'))\nThis affects all functions using contrasts (e.g., lmer, lm, aov, ...).\nTo reset default settings run: options(contrasts=c('contr.treatment', 'contr.poly')) (all afex functions should be unaffected by this)\n") + # \nPrevious contrasts saved in '.oldContrasts'. + #options(contrasts=c('contr.sum', 'contr.poly')) + #} else packageStartupMessage("Contrasts already set to effects coding: options(contrasts=c('contr.sum', '...'))\n") + #packageStartupMessage("afex loads the required packages (e.g., lme4, car, pbkrtest) in an order that should not lead to problems.\nLoading any of the packages (specifically lme4) beforehand can lead to problems (especially with older versions of either).\nLoading nlme in addition to afex (before or after loading it), may especially lead to problems.\n************") +} + diff --git a/man/afex-package.Rd b/man/afex-package.Rd index 539ade4..d865979 100644 --- a/man/afex-package.Rd +++ b/man/afex-package.Rd @@ -1,28 +1,28 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/afex-package.R -\docType{package} -\name{afex-package} -\alias{afex-package} -\title{The afex Package} -\description{ -Analysis of Factorial Experiments. -} -\details{ -\tabular{ll}{ -Package: \tab afex\cr -Type: \tab Package\cr -Version: \tab 0.14-1\cr -Date: \tab 2015-08-13\cr -Depends: \tab R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17)\cr -Encoding: \tab UTF-8\cr -License: \tab GPL (>=3)\cr -URL: \tab https://github.com/singmann/afex\cr -} - -Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. aov_ez(), aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), or mixed between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per row), potentially aggregating multiple observations per individual and cell of the design. mixed() fits mixed models using lme4::lmer() and computes p-values for all fixed effects using either Kenward-Roger approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and GLMMs), or likelihood ratio tests (LMMs and GLMMs). afex uses type 3 sums of squares as default (imitating commercial statistical software). -} -\author{ -Henrik Singmann, Ben Bolker, Jake Westfall, with contributions from Søren Højsgaard, John Fox, Michael A. Lawrence, Ulf Mertens -} -\keyword{package} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/afex-package.R +\docType{package} +\name{afex-package} +\alias{afex-package} +\title{The afex Package} +\description{ +Analysis of Factorial Experiments. +} +\details{ +\tabular{ll}{ +Package: \tab afex\cr +Type: \tab Package\cr +Version: \tab 0.14-1\cr +Date: \tab 2015-08-16\cr +Depends: \tab R (>= 3.0.0), lme4 (>= 1.0.5), reshape2, lsmeans (>= 2.17)\cr +Encoding: \tab UTF-8\cr +License: \tab GPL (>=3)\cr +URL: \tab https://github.com/singmann/afex\cr +} + +Provides convenience functions for analyzing factorial experiments using ANOVA or mixed models. aov_ez(), aov_car(), and aov_4() allow specification of between, within (i.e., repeated-measures), or mixed between-within (i.e., split-plot) ANOVAs for data in long format (i.e., one observation per row), potentially aggregating multiple observations per individual and cell of the design. mixed() fits mixed models using lme4::lmer() and computes p-values for all fixed effects using either Kenward-Roger approximation for degrees of freedom (LMM only), parametric bootstrap (LMMs and GLMMs), or likelihood ratio tests (LMMs and GLMMs). afex uses type 3 sums of squares as default (imitating commercial statistical software). +} +\author{ +Henrik Singmann, Ben Bolker, Jake Westfall, with contributions from Søren Højsgaard, John Fox, Michael A. Lawrence, Ulf Mertens +} +\keyword{package} + diff --git a/man/afex_aov-methods.Rd b/man/afex_aov-methods.Rd index 7e4bcfb..2665ad9 100644 --- a/man/afex_aov-methods.Rd +++ b/man/afex_aov-methods.Rd @@ -1,53 +1,53 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/methods.afex_aov.R -\name{afex_aov-methods} -\alias{afex_aov-methods} -\alias{anova.afex_aov} -\alias{lsm.basis.afex_aov} -\alias{print.afex_aov} -\alias{recover.data.afex_aov} -\alias{summary.afex_aov} -\title{Methods for afex_aov objects} -\usage{ -\method{anova}{afex_aov}(object, es = afex_options("es_aov"), - observed = NULL, correction = afex_options("correction_aov"), - MSE = TRUE, intercept = FALSE, ...) - -\method{print}{afex_aov}(x, ...) - -\method{summary}{afex_aov}(object, ...) - -\method{recover.data}{afex_aov}(object, ...) - -\method{lsm.basis}{afex_aov}(object, trms, xlev, grid, ...) -} -\arguments{ -\item{object,x}{object of class \code{afex_aov} as returned from \code{\link{aov_car}} and related functions.} - -\item{es}{Effect Size to be reported. The default is given by \code{afex_options("es_aov")}, which is initially set to \code{"ges"} (i.e., reporting generalized eta-squared, see details). Also supported is partial eta-squared (\code{"pes"}) or \code{"none"}.} - -\item{observed}{character vector referring to the observed (i.e., non manipulated) variables/effects in the design. Important for calculation of generalized eta-squared (ignored if \code{es} is not \code{"ges"}), see details.} - -\item{correction}{Character. Which sphericity correction of the degrees of freedom should be reported for the within-subject factors. The default is given by \code{afex_options("correction_aov")}, which is initially set to \code{"GG"} corresponding to the Greenhouse-Geisser correction. Possible values are \code{"GG"}, \code{"HF"} (i.e., Hyunh-Feldt correction), and \code{"none"} (i.e., no correction).} - -\item{MSE}{logical. Should the column containing the Mean Sqaured Error (MSE) be displayed? Default is \code{TRUE}.} - -\item{intercept}{logical. Should intercept (if present) be included in the ANOVA table? Default is \code{FALSE} which hides the intercept.} - -\item{...}{further arguments passed through, see description of return value for details.} - -\item{trms,xlev,grid}{same as for \code{\link{lsm.basis}}.} -} -\value{ -\describe{ - \item{\code{anova}}{Returns an ANOVA table of class \code{c("anova", "data.frame")}. Information such as effect size (\code{es}) or df-correction are calculated each time this method is called.} - \item{\code{summary}}{For ANOVAs containing within-subject factors it returns the full output of the within-subject tests: the uncorrected results, results containing Greenhousse-Geisser and Hyunh-Feldt correction, and the results of the Mauchly test of sphericity (all achieved via \code{summary.Anova.mlm}). For other ANOVAs, the \code{anova} table is simply returned.} - \item{\code{print}}{Prints (and invisibly returns) the ANOVA table as constructed from \code{\link{nice}} (i.e., as strings rounded nicely). Arguments in \code{...} are passed to \code{nice} allowing to pass arguments such as \code{es} and \code{correction}.} - \item{\code{recover.data} and \code{lsm.basis}}{Provide the backbone for using \code{\link{lsmeans}} and related functions from \pkg{lsmeans} directly on \code{afex_aov} objects by returning a \code{\link{ref.grid}} object. Should not be called directly but through the functionality provided by \pkg{lsmeans}.} - -} -} -\description{ -Methods defined for objects returned from the ANOVA functions \code{\link{aov_car}} et al. of class \code{afex_aov} containing both the ANOVA fitted via \code{car::Anova} and base R's \code{aov}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/methods.afex_aov.R +\name{afex_aov-methods} +\alias{afex_aov-methods} +\alias{anova.afex_aov} +\alias{lsm.basis.afex_aov} +\alias{print.afex_aov} +\alias{recover.data.afex_aov} +\alias{summary.afex_aov} +\title{Methods for afex_aov objects} +\usage{ +\method{anova}{afex_aov}(object, es = afex_options("es_aov"), + observed = NULL, correction = afex_options("correction_aov"), + MSE = TRUE, intercept = FALSE, ...) + +\method{print}{afex_aov}(x, ...) + +\method{summary}{afex_aov}(object, ...) + +\method{recover.data}{afex_aov}(object, ...) + +\method{lsm.basis}{afex_aov}(object, trms, xlev, grid, ...) +} +\arguments{ +\item{object,x}{object of class \code{afex_aov} as returned from \code{\link{aov_car}} and related functions.} + +\item{es}{Effect Size to be reported. The default is given by \code{afex_options("es_aov")}, which is initially set to \code{"ges"} (i.e., reporting generalized eta-squared, see details). Also supported is partial eta-squared (\code{"pes"}) or \code{"none"}.} + +\item{observed}{character vector referring to the observed (i.e., non manipulated) variables/effects in the design. Important for calculation of generalized eta-squared (ignored if \code{es} is not \code{"ges"}), see details.} + +\item{correction}{Character. Which sphericity correction of the degrees of freedom should be reported for the within-subject factors. The default is given by \code{afex_options("correction_aov")}, which is initially set to \code{"GG"} corresponding to the Greenhouse-Geisser correction. Possible values are \code{"GG"}, \code{"HF"} (i.e., Hyunh-Feldt correction), and \code{"none"} (i.e., no correction).} + +\item{MSE}{logical. Should the column containing the Mean Sqaured Error (MSE) be displayed? Default is \code{TRUE}.} + +\item{intercept}{logical. Should intercept (if present) be included in the ANOVA table? Default is \code{FALSE} which hides the intercept.} + +\item{...}{further arguments passed through, see description of return value for details.} + +\item{trms,xlev,grid}{same as for \code{\link{lsm.basis}}.} +} +\value{ +\describe{ + \item{\code{anova}}{Returns an ANOVA table of class \code{c("anova", "data.frame")}. Information such as effect size (\code{es}) or df-correction are calculated each time this method is called.} + \item{\code{summary}}{For ANOVAs containing within-subject factors it returns the full output of the within-subject tests: the uncorrected results, results containing Greenhousse-Geisser and Hyunh-Feldt correction, and the results of the Mauchly test of sphericity (all achieved via \code{summary.Anova.mlm}). For other ANOVAs, the \code{anova} table is simply returned.} + \item{\code{print}}{Prints (and invisibly returns) the ANOVA table as constructed from \code{\link{nice}} (i.e., as strings rounded nicely). Arguments in \code{...} are passed to \code{nice} allowing to pass arguments such as \code{es} and \code{correction}.} + \item{\code{recover.data} and \code{lsm.basis}}{Provide the backbone for using \code{\link{lsmeans}} and related functions from \pkg{lsmeans} directly on \code{afex_aov} objects by returning a \code{\link{ref.grid}} object. Should not be called directly but through the functionality provided by \pkg{lsmeans}.} + +} +} +\description{ +Methods defined for objects returned from the ANOVA functions \code{\link{aov_car}} et al. of class \code{afex_aov} containing both the ANOVA fitted via \code{car::Anova} and base R's \code{aov}. +} + diff --git a/man/afex_options.Rd b/man/afex_options.Rd index 663e2ca..17baea8 100644 --- a/man/afex_options.Rd +++ b/man/afex_options.Rd @@ -1,41 +1,41 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/helpers.R -\name{afex_options} -\alias{afex_options} -\title{Set/get global afex options} -\usage{ -afex_options(...) -} -\arguments{ -\item{...}{One of three: (1) nothing, then returns all options; (2) a name of an option element, then returns its' value; (3) a name-value pair which sets the corresponding option to the new value (and returns nothing).} -} -\value{ -depends on input, see above. -} -\description{ -Global afex options are used, for example, by \code{\link{aov_car}} (et al.) and \code{\link{mixed}}. But can be changed in each functions directly using an argument (which has precedence over the global options). -} -\details{ -The following arguments are currently set: -\itemize{ -\item \code{check.contrasts} should contrasts be checked and changed to sum-to-zero contrasts? Default is \code{TRUE}. -\item \code{type} type of sums-of-squares to be used for testing effects, default is 3 which reports Type 3 tests. -\item \code{method_mixed}: Method used to obtain p-values in \code{\link{mixed}}, default is \code{"KR"} (which will change to \code{"LRT"} soon). (\code{mixed()} only) -\item \code{return_aov}: Return value of the ANOVA functions (see \code{\link{aov_car}}), default is \code{"nice"}. -\item \code{es_aov}: Effect size reported for ANOVAs (see \code{\link{aov_car}}), default is \code{"ges"} (generalized eta-squared). -\item \code{correction_aov}: Correction used for within-subjects factors with more than two levels for ANOVAs (see \code{\link{aov_car}} or \code{\link{nice}}), default is \code{"GG"} (Greenhouse-Geisser correction). (ANOVA functions only) -\item \code{factorize}: Should between subject factors be factorized (with note) before running the analysis? Default is \code{TRUE}. (ANOVA functions only) -} -} -\examples{ -afex_options() - -afex_options("return_aov") - -afex_options("return_aov", "check.contrasts") # returns only first value! - -\dontrun{ -afex_options(return_aov = "nice") -} -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/helpers.R +\name{afex_options} +\alias{afex_options} +\title{Set/get global afex options} +\usage{ +afex_options(...) +} +\arguments{ +\item{...}{One of three: (1) nothing, then returns all options; (2) a name of an option element, then returns its' value; (3) a name-value pair which sets the corresponding option to the new value (and returns nothing).} +} +\value{ +depends on input, see above. +} +\description{ +Global afex options are used, for example, by \code{\link{aov_car}} (et al.) and \code{\link{mixed}}. But can be changed in each functions directly using an argument (which has precedence over the global options). +} +\details{ +The following arguments are currently set: +\itemize{ +\item \code{check.contrasts} should contrasts be checked and changed to sum-to-zero contrasts? Default is \code{TRUE}. +\item \code{type} type of sums-of-squares to be used for testing effects, default is 3 which reports Type 3 tests. +\item \code{method_mixed}: Method used to obtain p-values in \code{\link{mixed}}, default is \code{"KR"} (which will change to \code{"LRT"} soon). (\code{mixed()} only) +\item \code{return_aov}: Return value of the ANOVA functions (see \code{\link{aov_car}}), default is \code{"nice"}. +\item \code{es_aov}: Effect size reported for ANOVAs (see \code{\link{aov_car}}), default is \code{"ges"} (generalized eta-squared). +\item \code{correction_aov}: Correction used for within-subjects factors with more than two levels for ANOVAs (see \code{\link{aov_car}} or \code{\link{nice}}), default is \code{"GG"} (Greenhouse-Geisser correction). (ANOVA functions only) +\item \code{factorize}: Should between subject factors be factorized (with note) before running the analysis? Default is \code{TRUE}. (ANOVA functions only) +} +} +\examples{ +afex_options() + +afex_options("return_aov") + +afex_options("return_aov", "check.contrasts") # returns only first value! + +\dontrun{ +afex_options(return_aov = "nice") +} +} + diff --git a/man/allFit.Rd b/man/allFit.Rd index 6628efd..d50998f 100644 --- a/man/allFit.Rd +++ b/man/allFit.Rd @@ -1,61 +1,61 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/allFit.R -\name{allFit} -\alias{allFit} -\title{Refit \code{lmer} model using multiple optimizers} -\usage{ -allFit(m, meth.tab = cbind(optimizer = rep(c("bobyqa", "Nelder_Mead", - "optimx", "nloptwrap"), c(1, 1, 2, 2)), method = c("", "", "nlminb", - "L-BFGS-B", "NLOPT_LN_NELDERMEAD", "NLOPT_LN_BOBYQA")), verbose = TRUE, - maxfun = 1e+05, ...) -} -\arguments{ -\item{m}{a fitted model with \code{lmer}} - -\item{meth.tab}{a matrix (or data.frame) with columns -- method the name of a specific optimization method to pass to the optimizer -(leave blank for built-in optimizers) -- optimizer the \code{optimizer} function to use} - -\item{verbose}{print progress messages?} - -\item{maxfun}{number of iterations to allow for the optimization rountine.} - -\item{...}{further arguments passed to \code{\link{update.merMod}} such as data.} -} -\value{ -a list of fitted \code{merMod} objects -} -\description{ -Attempt to re-fit a [g]lmer model with a range of optimizers. -The default is to use all known optimizers for R that satisfy the -requirements (do not require explicit gradients, allow -box constraints), in three categories; (i) built-in -(\code{minqa::bobyqa}, \code{lme4::Nelder_Mead}), (ii) wrapped via optimx -(most of optimx's optimizers that allow box constraints require -an explicit gradient function to be specified; the two provided -here are really base R functions that can be accessed via optimx, -(iii) wrapped via nloptr. -} -\details{ -Needs packages \pkg{nloptr} and \pkg{optimx} to try out all optimizers. \pkg{optimx} needs to be loaded explicitly using \code{library} or \code{require}. -} -\examples{ -\dontrun{ -require(optimx) -gm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd), -data = cbpp, family = binomial) -gm_all <- allFit(gm1) -t(sapply(gm_all,fixef)) ## extract fixed effects -sapply(gm_all,logLik) ## log-likelihoods -sapply(gm_all,getME,"theta") ## theta parameters -!sapply(gm_all,inherits,"try-error") ## was fit OK? -} -} -\author{ -Ben Bolker -} -\seealso{ -slice, slice2D in the bbmle package -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/allFit.R +\name{allFit} +\alias{allFit} +\title{Refit \code{lmer} model using multiple optimizers} +\usage{ +allFit(m, meth.tab = cbind(optimizer = rep(c("bobyqa", "Nelder_Mead", + "optimx", "nloptwrap"), c(1, 1, 2, 2)), method = c("", "", "nlminb", + "L-BFGS-B", "NLOPT_LN_NELDERMEAD", "NLOPT_LN_BOBYQA")), verbose = TRUE, + maxfun = 1e+05, ...) +} +\arguments{ +\item{m}{a fitted model with \code{lmer}} + +\item{meth.tab}{a matrix (or data.frame) with columns +- method the name of a specific optimization method to pass to the optimizer +(leave blank for built-in optimizers) +- optimizer the \code{optimizer} function to use} + +\item{verbose}{print progress messages?} + +\item{maxfun}{number of iterations to allow for the optimization rountine.} + +\item{...}{further arguments passed to \code{\link{update.merMod}} such as data.} +} +\value{ +a list of fitted \code{merMod} objects +} +\description{ +Attempt to re-fit a [g]lmer model with a range of optimizers. +The default is to use all known optimizers for R that satisfy the +requirements (do not require explicit gradients, allow +box constraints), in three categories; (i) built-in +(\code{minqa::bobyqa}, \code{lme4::Nelder_Mead}), (ii) wrapped via optimx +(most of optimx's optimizers that allow box constraints require +an explicit gradient function to be specified; the two provided +here are really base R functions that can be accessed via optimx, +(iii) wrapped via nloptr. +} +\details{ +Needs packages \pkg{nloptr} and \pkg{optimx} to try out all optimizers. \pkg{optimx} needs to be loaded explicitly using \code{library} or \code{require}. +} +\examples{ +\dontrun{ +require(optimx) +gm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd), +data = cbpp, family = binomial) +gm_all <- allFit(gm1) +t(sapply(gm_all,fixef)) ## extract fixed effects +sapply(gm_all,logLik) ## log-likelihoods +sapply(gm_all,getME,"theta") ## theta parameters +!sapply(gm_all,inherits,"try-error") ## was fit OK? +} +} +\author{ +Ben Bolker +} +\seealso{ +slice, slice2D in the bbmle package +} + diff --git a/man/aov_car.Rd b/man/aov_car.Rd index 71aedd0..b613669 100644 --- a/man/aov_car.Rd +++ b/man/aov_car.Rd @@ -1,328 +1,328 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/aov_car.R -\encoding{UTF-8} -\name{aov_car} -\alias{aov_4} -\alias{aov_car} -\alias{aov_ez} -\title{Convenient ANOVA estimation for factorial designs} -\usage{ -aov_ez(id, dv, data, between = NULL, within = NULL, covariate = NULL, - observed = NULL, fun.aggregate = NULL, type = afex_options("type"), - factorize = afex_options("factorize"), - check.contrasts = afex_options("check.contrasts"), - return = afex_options("return_aov"), - anova_table = list(), ..., print.formula = FALSE) - -aov_car(formula, data, fun.aggregate = NULL, type = afex_options("type"), - factorize = afex_options("factorize"), - check.contrasts = afex_options("check.contrasts"), - return = afex_options("return_aov"), observed = NULL, - anova_table = list(), ...) - -aov_4(formula, data, observed = NULL, fun.aggregate = NULL, type = afex_options("type"), - factorize = afex_options("factorize"), - check.contrasts = afex_options("check.contrasts"), - return = afex_options("return_aov"), - anova_table = list(), ..., print.formula = FALSE) -} -\arguments{ -\item{formula}{A formula specifying the ANOVA model similar to \code{\link{aov}} (for \code{aov_car} or similar to \code{lme4:lmer} for \code{aov_4}). Should include an error term (i.e., \code{Error(id/...)} for \code{aov_car} or \code{(...|id)} for \code{aov_4}). Note that the within-subject factors do not need to be outside the Error term (this contrasts with \code{aov}). See Details.} - -\item{data}{A \code{data.frame} containing the data. Mandatory.} - -\item{fun.aggregate}{The function for aggregating the data before running the ANOVA if there is more than one observation per individual and cell of the design. The default \code{NULL} issues a warning if aggregation is necessary and uses \code{\link{mean}}. Pass \code{mean} directly to avoid the warning.} - -\item{type}{The type of sums of squares for the ANOVA. The default is given by \code{afex_options("type")}, which is \strong{initially set to 3}. Passed to \code{\link[car]{Anova}}. Possible values are \code{"II"}, \code{"III"}, \code{2}, or \code{3}.} - -\item{factorize}{logical. Should between subject factors be factorized (with note) before running the analysis. he default is given by \code{afex_options("factorize")}, which is initially \code{TRUE}. If one wants to run an ANCOVA, needs to be set to \code{FALSE} (in which case centering on 0 is checked on numeric variables).} - -\item{check.contrasts}{\code{logical}. Should contrasts for between-subject factors be checked and (if necessary) changed to be \code{"contr.sum"}. See details. The default is given by \code{afex_options("check.contrasts")}, which is initially \code{TRUE}.} - -\item{return}{What should be returned? The default is given by \code{afex_options("return_aov")}, which is initially \code{"afex_aov"}, returning an S3 object of class \code{afex_aov} for which various \link[=afex_aov-methods]{methods} exist (see there and below for more details). To avoid the (potentially costly) computation via \code{aov} set \code{return} to \code{"nice"} in which case only the nice ANOVA table is returned (produced by \code{\link{nice}}, this was the previous default return value). Other values are currently still supported for backward compatibility.} - -\item{observed}{\code{character} vector indicating which of the variables are observed (i.e, measured) as compared to experimentally manipulated. The default effect size reported (generalized eta-squared) requires correct specification of the obsered (in contrast to manipulated) variables.} - -\item{anova_table}{\code{list} of further arguments passed to function producing the ANOVA table. Arguments such as \code{es} (effect size) or \code{correction} are passed to either \code{anova.afex_aov} or \code{nice}. Note that those settings can also be changed once an object of class \code{afex_aov} is created by invoking the \code{anova} method directly.} - -\item{...}{Further arguments passed to \code{fun.aggregate}.} - -\item{id}{\code{character} vector (of length 1) indicating the subject identifier column in \code{data}.} - -\item{dv}{\code{character} vector (of length 1) indicating the column containing the \strong{dependent variable} in \code{data}.} - -\item{between}{\code{character} vector indicating the \strong{between}-subject(s) factor(s)/column(s) in \code{data}. Default is \code{NULL} indicating no between-subjects factors.} - -\item{within}{\code{character} vector indicating the \strong{within}-subject(s)(or repeated-measures) factor(s)/column(s) in \code{data}. Default is \code{NULL} indicating no within-subjects factors.} - -\item{covariate}{\code{character} vector indicating the between-subject(s) covariate(s) (i.e., column(s)) in \code{data}. Default is \code{NULL} indicating no covariates.} - -\item{print.formula}{\code{aov_ez} and \code{aov_4} are wrapper for \code{aov_car}. This boolean argument indicates whether the formula in the call to \code{car.aov} should be printed.} -} -\value{ -\code{aov_car}, \code{aov_4}, and \code{aov_ez} are wrappers for \code{\link[car]{Anova}} and \code{\link{aov}}, the return value is dependent on the \code{return} argument. Per default, an S3 object of class \code{"afex_aov"} is returned containing the following slots: - -\describe{ - \item{\code{"anova_table"}}{An ANOVA table of class \code{c("anova", "data.frame")}.} - \item{\code{"aov"}}{\code{aov} object returned from \code{\link{aov}} (should not be used to evaluate significance of effects, but can be passed to \code{lsmeans} for post-hoc tests).} - \item{\code{"Anova"}}{object returned from \code{\link[car]{Anova}}, an object of class \code{"Anova.mlm"} (if within-subjects factors are present) or of class \code{c("anova", "data.frame")}.} - \item{\code{"lm"}}{the object fitted with \code{lm} and passed to \code{Anova} (i.e., an object of class \code{"lm"} or \code{"mlm"}). Also returned if \code{return = "lm"}.} - \item{\code{"data"}}{a list containing: (1) \code{long} (the possibly aggregated data in long format used for \code{aov}), \code{wide} (the data used to fit the \code{lm} object), and \code{idata} (if within-subject factors are present, the \code{idata} argument passed to \code{car::Anova}). Also returned if \code{return = "data"}.} - \item{\code{"information"}}{A list containing information such as name of dependent variable and id variable.} -} - -The \link[=afex_aov-methods]{print} method for \code{afex_aov} objects (invisibly) returns (and prints) the same as if \code{return} is \code{"nice"}: a nice ANOVA table (produced by \code{\link{nice}}) with the following columns: \code{Effect}, \code{df}, \code{MSE} (mean-squared errors), \code{F} (potentially with significant symbols), \code{ges} (generalized eta-squared), \code{p}. -} -\description{ -These functions allow convenient specification of any type of ANOVAs (i.e., purely within-subjects ANOVAs, purely between-subjects ANOVAs, and mixed between-within or split-plot ANOVAs) for data in the \strong{long} format (i.e., one observation per row). If the data has more than one observation per individual and cell of the design (e.g., multiple responses per condition), the data will by automatically aggregated. The default settings reproduce results from commercial statistical packages such as SPSS or SAS. \code{aov_ez} is called specifying the factors as character vectors, \code{aov_car} is called using a formula similar to \code{\link{aov}} specifying an error strata for the within-subject factor(s), and \code{aov_4} is called with a \pkg{lme4}-like formula (all ANOVA functions return identical results). The returned object contains the ANOVA also fitted via base R's \code{\link{aov}} which can be passed to e.g., \pkg{lsmeans} for further analysis (e.g., follow-up tests, contrasts, plotting, etc.). These functions employ \code{\link[car]{Anova}} (from the \pkg{car} package) to provide test of effects avoiding the somewhat unhandy format of \code{car::Anova}. -} -\details{ -\subsection{Details of ANOVA Specification}{ -\code{aov_ez} will concatenate all between-subject factors using \code{*} (i.e., producing all main effects and interactions) and all covariates by \code{+} (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 \code{glm} function. - -The \code{formula}s for \code{aov_car} or \code{aov_4} must contain a single \code{Error} term specifying the \code{ID} column and potential within-subject factors (you can use \code{\link{mixed}} for running mixed-effects models with multiple error terms). Factors outside the \code{Error} term are treated as between-subject factors (the within-subject factors specified in the \code{Error} term are ignored outside the \code{Error} term; in other words, it is not necessary to specify them outside the \code{Error} term, see Examples).\cr -Suppressing the intercept (i.e, via \code{0 +} or \code{- 1}) is ignored. Specific specifications of effects (e.g., excluding terms with \code{-} or using \code{^}) could be okay but is not tested. Using the \code{\link{I}} or \code{\link{poly}} function within the formula is not tested and not supported! - -To run an ANCOVA you need to set \code{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 include calculation of the effect size generalized eta-squared for which \strong{all non-manipluated (i.e., observed)} variables need to be specified via the \code{observed} argument to obtain correct results. When changing the effect size to \code{"pes"} (partial eta-squared) or \code{"none"} via \code{anova_table} this becomes unnecessary. - -If \code{check.contrasts = TRUE}, contrasts will be set to \code{"contr.sum"} for all between-subject factors if default contrasts are not equal to \code{"contr.sum"} or \code{attrib(factor, "contrasts") != "contr.sum"}. (within-subject factors are hard-coded \code{"contr.sum"}.) -} - -\subsection{Statistical Issues}{ -\strong{Type 3 sums of squares are default in \pkg{afex}.} While some authors argue that so-called type 3 sums of squares are dangerous and/or problematic (most notably Venables, 2000), they are the default in many commercial statistical application such as SPSS or SAS. Furthermore, statisticians with an applied perspective recommend type 3 tests (e.g., Maxwell and Delaney, 2004). Consequently, they are the default for the ANOVA functions described here. For some more discussion on this issue see \href{http://stats.stackexchange.com/q/6208/442}{here}. - -Note that lower order effects (e.g., main effects) in type 3 ANOVAs are only meaningful with \href{http://www.ats.ucla.edu/stat/mult_pkg/faq/general/effect.htm}{effects coding}. That is, contrasts should be set to \code{\link{contr.sum}} to obtain meaningful results. This is imposed automatically for the functions discussed here as long as \code{check.contrasts} is \code{TRUE} (the default). I nevertheless recommend to set the contrasts globally to \code{contr.sum} via running \code{\link{set_sum_contrasts}}. For a discussion of the other (non-recommended) coding schemes see \href{http://www.ats.ucla.edu/stat/r/library/contrast_coding.htm}{here}. -} - -\subsection{Follow-Up Contrasts and Post-Hoc Tests}{ -The S3 object returned per default can be directly passed to \code{lsmeans::lsmeans} for further analysis. This allows to test any type of contrasts that might be of interest independent of whether or not this contrast involves between-subject variables, within-subject variables, or a combination thereof. The general procedure to run those contrasts is the following (see Examples for a full example): - - \enumerate{ - \item Estimate an \code{afex_aov} object with the function returned here. For example: \code{x <- aov_car(dv ~ a*b + (id/c), d)} - \item Obtain a \code{\link[lsmeans]{ref.grid}} object by running \code{\link[lsmeans]{lsmeans}} on the \code{afex_aov} object from step 1 using the factors involved in the contrast. For example: \code{r <- lsmeans(x, ~a:c)} - \item Create a list containing the desired contrasts on the reference grid object from step 2. For example: \code{con1 <- list(a_x = c(-1, 1, 0, 0, 0, 0), b_x = c(0, 0, -0.5, -0.5, 0, 1))} - \item Test the contrast on the reference grid using \code{\link[lsmeans]{contrast}}. For example: \code{contrast(r, con1)} - \item To control for multiple testing p-value adjustments can be specified. For example the Bonferroni-Holm correction: \code{contrast(r, con1, adjust = "holm")} - } - - Note that \pkg{lsmeans} allows for a variety of advanced settings and simplifiations, for example: all pairwise comparison of a single factor using one command (e.g., \code{lsmeans(x, "a", contr = "pairwise")}) or advanced control for multiple testing by passing objects to \pkg{multcomp}. A comprehensive overview of the functionality is provided in the accompanying vignettes (see \href{http://cran.r-project.org/package=lsmeans}{here}). - - A caveat regarding the use of \pkg{lsmeans} concerns the assumption of sphericity for ANOVAs including within-subjects/repeated-measures factors (with more than two levels). While the ANOVA tables per default report results using the Greenhousse-Geisser correction, no such correction is available when using \pkg{lsmeans}. This may result in anti-conservative tests. - - \pkg{lsmeans} is loaded/attached automatically when loading \pkg{afex} via \code{library} or \code{require}. -} - -\subsection{Methods for \code{afex_aov} Objects}{ -A full overview over the methods provided for \code{afex_aov} objects is provided in the corresponding help page: \code{\link{afex_aov-methods}}. The probably most important ones for end-users are \code{summary} and \code{anova}. - -The \code{summary} method returns, for ANOVAs containing within-subject (repeated-measures) factors with more than two levels, the complete univariate analysis: Results without df-correction, the Greenhouse-Geisser corrected results, the Hyunh-Feldt corrected results, and the results of the Mauchly test for sphericity. - -The \code{anova} method returns a \code{data.frame} of class \code{"anova"} containing the ANOVA table in numeric form (i.e., the one in slot \code{anova_table} of a \code{afex_aov}). This method has arguments such as \code{correction} and \code{es} and can be used to obtain an ANOVA table with different correction than the one initially specified. -} -} -\note{ -Calculation of ANOVA models via \code{aov} (which is done per default) can be comparatively slow and produce comparatively large objects for ANOVAs with many within-subjects factors or levels. To avoid this calculation set the return argument to \code{"nice"}. This can also be done globally via \code{afex_options(return_aov = "nice")}. \code{return = "nice"} also produces the default output of previous versions of afex (versions 0.13 and earlier). - -The id variable and variables entered as within-subjects (i.e., repeated-measures) factors are silently converted to factors. Levels of within-subject factors are converted to valid variable names using \code{\link{make.names}(...,unique=TRUE)}. Unused factor levels are silently dropped on all variables. - -Contrasts attached to a factor as an attribute are probably not preserved and not supported. - -The workhorse is \code{aov_car}. \code{aov_4} and \code{aov_ez} only construe and pass an appropriate formula to \code{aov_car}. Use \code{print.formula = TRUE} to view this formula. - -In contrast to \code{\link{aov}} \code{aov_car} assumes that all factors to the right of \code{/} in the \code{Error} term are belonging together. Consequently, \code{Error(id/(a*b))} and \code{Error(id/a*b)} are identical (which is not true for \code{\link{aov}}). -} -\examples{ - -########################## -## 1: Specifying ANOVAs ## -########################## - -# Example using a purely within-subjects design -# (Maxwell & Delaney, 2004, Chapter 12, Table 12.5, p. 578): -data(md_12.1) -aov_ez("id", "rt", md_12.1, within = c("angle", "noise"), - anova_table=list(correction = "none", es = "none")) - -# Default output -aov_ez("id", "rt", md_12.1, within = c("angle", "noise")) - - -# examples using obk.long (see ?obk.long), a long version of the OBrienKaiser dataset (car package). -# Data is a split-plot or mixed design: contains both within- and between-subjects factors. -data(obk.long, package = "afex") - -# estimate mixed ANOVA on the full design: -aov_car(value ~ treatment * gender + Error(id/(phase*hour)), - data = obk.long, observed = "gender") - -aov_4(value ~ treatment * gender + (phase*hour|id), - data = obk.long, observed = "gender") - -aov_ez("id", "value", obk.long, between = c("treatment", "gender"), - within = c("phase", "hour"), observed = "gender") - -# the three calls return the same ANOVA table: -## Effect df MSE F ges p.value -## 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 - - -# "numeric" variables are per default converted to factors (as long as factorize = TRUE): -obk.long$hour2 <- as.numeric(as.character(obk.long$hour)) - -# gives same results as calls before -aov_car(value ~ treatment * gender + Error(id/hour2*phase), - data = obk.long, observed = c("gender")) - - -# 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) - -aov_4(value ~ treatment * gender + age + (phase*hour|id), - data = obk.long, observed = c("gender", "age"), factorize = FALSE) - -aov_ez("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") - -aov_ez("id", "value", obk.long, c("treatment", "gender"), "hour", observed = "gender") - -# aggregating over both within-subjects factors (again with warning), -# only between-subjects factors: -aov_car(value ~ treatment * gender + Error(id), data = obk.long, observed = c("gender")) -aov_4(value ~ treatment * gender + (1|id), data = obk.long, observed = c("gender")) -aov_ez("id", "value", obk.long, between = c("treatment", "gender"), observed = "gender") - -# only within-subject factors (ignoring between-subjects factors) -aov_car(value ~ Error(id/(phase*hour)), data = obk.long) -aov_4(value ~ (phase*hour|id), data = obk.long) -aov_ez("id", "value", obk.long, within = c("phase", "hour")) - -### changing defaults of ANOVA table: - -# no df-correction & partial eta-squared: -aov_car(value ~ treatment * gender + Error(id/(phase*hour)), - data = obk.long, anova_table = list(correction = "none", es = "pes")) - -# no df-correction and no MSE -aov_car(value ~ treatment * gender + Error(id/(phase*hour)), - data = obk.long,observed = "gender", - anova_table = list(correction = "none", MSE = FALSE)) - - -########################### -## 2: Follow-up Analysis ## -########################### - -# use data as above -data(obk.long, package = "afex") - -# 1. obtain afex_aov object: -a1 <- aov_ez("id", "value", obk.long, between = c("treatment", "gender"), - within = c("phase", "hour"), observed = "gender") - -# 1b. plot data: -lsmip(a1, gender ~ hour | treatment+phase) - -# 2. obtain reference grid object: -r1 <- lsmeans(a1, ~treatment +phase) -r1 - -# 3. create list of contrasts on the reference grid: -c1 <- list( - A_B_pre = c(0, -1, 1, rep(0, 6)), # A versus B for pretest - A_B_comb = c(0, 0, 0, 0, -0.5, 0.5, 0, -0.5, 0.5), # A vs. B for post and follow-up combined - effect_post = c(0, 0, 0, -1, 0.5, 0.5, 0, 0, 0), # control versus A&B post - effect_fup = c(0, 0, 0, 0, 0, 0, -1, 0.5, 0.5), # control versus A&B follow-up - effect_comb = c(0, 0, 0, -0.5, 0.25, 0.25, -0.5, 0.25, 0.25) # control versus A&B combined -) - -# 4. test contrasts on reference grid: -contrast(r1, c1) - -# same as before, but using Bonferroni-Holm correction for multiple testing: -contrast(r1, c1, adjust = "holm") - -# 2. (alternative): all pairwise comparisons of treatment: -lsmeans(a1, "treatment", contr = "pairwise") - -####################### -## 3: Other examples ## -####################### -data(obk.long, package = "afex") - -# replicating ?Anova using aov_car: -obk_anova <- aov_car(value ~ treatment * gender + Error(id/(phase*hour)), - data = obk.long, type = 2) -# in contrast to aov you do not need the within-subject factors outside Error() - -str(obk_anova, 1, give.attr = FALSE) -## List of 6 -## $ anova_table:Classes 'anova' and 'data.frame': 15 obs. of 6 variables: -## $ aov :List of 5 -## $ Anova :List of 14 -## $ lm :List of 13 -## $ data :List of 3 -## $ information:List of 5 - -obk_anova$Anova -## 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 - -} -\author{ -Henrik Singmann - -The design of these functions was influenced by \code{\link[ez]{ezANOVA}} from package \pkg{ez}. -} -\references{ -Maxwell, S. E., & Delaney, H. D. (2004). \emph{Designing Experiments and Analyzing Data: A Model-Comparisons Perspective}. Mahwah, N.J.: Lawrence Erlbaum Associates. - -Venables, W.N. (2000). \emph{Exegeses on linear models}. Paper presented to the S-Plus User's Conference, Washington DC, 8-9 October 1998, Washington, DC. Available from: \url{http://www.stats.ox.ac.uk/pub/MASS3/Exegeses.pdf} -} -\seealso{ -Various methods for objects of class \code{afex_aov} are available: \code{\link{afex_aov-methods}} - -\code{\link{nice}} creates the nice ANOVA tables which is by default printed. See also there for a slightly longer discussion of the available effect sizes. - -\code{\link{mixed}} provides a (formula) interface for obtaining p-values for mixed-models via \pkg{lme4}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/aov_car.R +\encoding{UTF-8} +\name{aov_car} +\alias{aov_4} +\alias{aov_car} +\alias{aov_ez} +\title{Convenient ANOVA estimation for factorial designs} +\usage{ +aov_ez(id, dv, data, between = NULL, within = NULL, covariate = NULL, + observed = NULL, fun.aggregate = NULL, type = afex_options("type"), + factorize = afex_options("factorize"), + check.contrasts = afex_options("check.contrasts"), + return = afex_options("return_aov"), + anova_table = list(), ..., print.formula = FALSE) + +aov_car(formula, data, fun.aggregate = NULL, type = afex_options("type"), + factorize = afex_options("factorize"), + check.contrasts = afex_options("check.contrasts"), + return = afex_options("return_aov"), observed = NULL, + anova_table = list(), ...) + +aov_4(formula, data, observed = NULL, fun.aggregate = NULL, type = afex_options("type"), + factorize = afex_options("factorize"), + check.contrasts = afex_options("check.contrasts"), + return = afex_options("return_aov"), + anova_table = list(), ..., print.formula = FALSE) +} +\arguments{ +\item{formula}{A formula specifying the ANOVA model similar to \code{\link{aov}} (for \code{aov_car} or similar to \code{lme4:lmer} for \code{aov_4}). Should include an error term (i.e., \code{Error(id/...)} for \code{aov_car} or \code{(...|id)} for \code{aov_4}). Note that the within-subject factors do not need to be outside the Error term (this contrasts with \code{aov}). See Details.} + +\item{data}{A \code{data.frame} containing the data. Mandatory.} + +\item{fun.aggregate}{The function for aggregating the data before running the ANOVA if there is more than one observation per individual and cell of the design. The default \code{NULL} issues a warning if aggregation is necessary and uses \code{\link{mean}}. Pass \code{mean} directly to avoid the warning.} + +\item{type}{The type of sums of squares for the ANOVA. The default is given by \code{afex_options("type")}, which is \strong{initially set to 3}. Passed to \code{\link[car]{Anova}}. Possible values are \code{"II"}, \code{"III"}, \code{2}, or \code{3}.} + +\item{factorize}{logical. Should between subject factors be factorized (with note) before running the analysis. he default is given by \code{afex_options("factorize")}, which is initially \code{TRUE}. If one wants to run an ANCOVA, needs to be set to \code{FALSE} (in which case centering on 0 is checked on numeric variables).} + +\item{check.contrasts}{\code{logical}. Should contrasts for between-subject factors be checked and (if necessary) changed to be \code{"contr.sum"}. See details. The default is given by \code{afex_options("check.contrasts")}, which is initially \code{TRUE}.} + +\item{return}{What should be returned? The default is given by \code{afex_options("return_aov")}, which is initially \code{"afex_aov"}, returning an S3 object of class \code{afex_aov} for which various \link[=afex_aov-methods]{methods} exist (see there and below for more details). To avoid the (potentially costly) computation via \code{aov} set \code{return} to \code{"nice"} in which case only the nice ANOVA table is returned (produced by \code{\link{nice}}, this was the previous default return value). Other values are currently still supported for backward compatibility.} + +\item{observed}{\code{character} vector indicating which of the variables are observed (i.e, measured) as compared to experimentally manipulated. The default effect size reported (generalized eta-squared) requires correct specification of the obsered (in contrast to manipulated) variables.} + +\item{anova_table}{\code{list} of further arguments passed to function producing the ANOVA table. Arguments such as \code{es} (effect size) or \code{correction} are passed to either \code{anova.afex_aov} or \code{nice}. Note that those settings can also be changed once an object of class \code{afex_aov} is created by invoking the \code{anova} method directly.} + +\item{...}{Further arguments passed to \code{fun.aggregate}.} + +\item{id}{\code{character} vector (of length 1) indicating the subject identifier column in \code{data}.} + +\item{dv}{\code{character} vector (of length 1) indicating the column containing the \strong{dependent variable} in \code{data}.} + +\item{between}{\code{character} vector indicating the \strong{between}-subject(s) factor(s)/column(s) in \code{data}. Default is \code{NULL} indicating no between-subjects factors.} + +\item{within}{\code{character} vector indicating the \strong{within}-subject(s)(or repeated-measures) factor(s)/column(s) in \code{data}. Default is \code{NULL} indicating no within-subjects factors.} + +\item{covariate}{\code{character} vector indicating the between-subject(s) covariate(s) (i.e., column(s)) in \code{data}. Default is \code{NULL} indicating no covariates.} + +\item{print.formula}{\code{aov_ez} and \code{aov_4} are wrapper for \code{aov_car}. This boolean argument indicates whether the formula in the call to \code{car.aov} should be printed.} +} +\value{ +\code{aov_car}, \code{aov_4}, and \code{aov_ez} are wrappers for \code{\link[car]{Anova}} and \code{\link{aov}}, the return value is dependent on the \code{return} argument. Per default, an S3 object of class \code{"afex_aov"} is returned containing the following slots: + +\describe{ + \item{\code{"anova_table"}}{An ANOVA table of class \code{c("anova", "data.frame")}.} + \item{\code{"aov"}}{\code{aov} object returned from \code{\link{aov}} (should not be used to evaluate significance of effects, but can be passed to \code{lsmeans} for post-hoc tests).} + \item{\code{"Anova"}}{object returned from \code{\link[car]{Anova}}, an object of class \code{"Anova.mlm"} (if within-subjects factors are present) or of class \code{c("anova", "data.frame")}.} + \item{\code{"lm"}}{the object fitted with \code{lm} and passed to \code{Anova} (i.e., an object of class \code{"lm"} or \code{"mlm"}). Also returned if \code{return = "lm"}.} + \item{\code{"data"}}{a list containing: (1) \code{long} (the possibly aggregated data in long format used for \code{aov}), \code{wide} (the data used to fit the \code{lm} object), and \code{idata} (if within-subject factors are present, the \code{idata} argument passed to \code{car::Anova}). Also returned if \code{return = "data"}.} + \item{\code{"information"}}{A list containing information such as name of dependent variable and id variable.} +} + +The \link[=afex_aov-methods]{print} method for \code{afex_aov} objects (invisibly) returns (and prints) the same as if \code{return} is \code{"nice"}: a nice ANOVA table (produced by \code{\link{nice}}) with the following columns: \code{Effect}, \code{df}, \code{MSE} (mean-squared errors), \code{F} (potentially with significant symbols), \code{ges} (generalized eta-squared), \code{p}. +} +\description{ +These functions allow convenient specification of any type of ANOVAs (i.e., purely within-subjects ANOVAs, purely between-subjects ANOVAs, and mixed between-within or split-plot ANOVAs) for data in the \strong{long} format (i.e., one observation per row). If the data has more than one observation per individual and cell of the design (e.g., multiple responses per condition), the data will by automatically aggregated. The default settings reproduce results from commercial statistical packages such as SPSS or SAS. \code{aov_ez} is called specifying the factors as character vectors, \code{aov_car} is called using a formula similar to \code{\link{aov}} specifying an error strata for the within-subject factor(s), and \code{aov_4} is called with a \pkg{lme4}-like formula (all ANOVA functions return identical results). The returned object contains the ANOVA also fitted via base R's \code{\link{aov}} which can be passed to e.g., \pkg{lsmeans} for further analysis (e.g., follow-up tests, contrasts, plotting, etc.). These functions employ \code{\link[car]{Anova}} (from the \pkg{car} package) to provide test of effects avoiding the somewhat unhandy format of \code{car::Anova}. +} +\details{ +\subsection{Details of ANOVA Specification}{ +\code{aov_ez} will concatenate all between-subject factors using \code{*} (i.e., producing all main effects and interactions) and all covariates by \code{+} (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 \code{glm} function. + +The \code{formula}s for \code{aov_car} or \code{aov_4} must contain a single \code{Error} term specifying the \code{ID} column and potential within-subject factors (you can use \code{\link{mixed}} for running mixed-effects models with multiple error terms). Factors outside the \code{Error} term are treated as between-subject factors (the within-subject factors specified in the \code{Error} term are ignored outside the \code{Error} term; in other words, it is not necessary to specify them outside the \code{Error} term, see Examples).\cr +Suppressing the intercept (i.e, via \code{0 +} or \code{- 1}) is ignored. Specific specifications of effects (e.g., excluding terms with \code{-} or using \code{^}) could be okay but is not tested. Using the \code{\link{I}} or \code{\link{poly}} function within the formula is not tested and not supported! + +To run an ANCOVA you need to set \code{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 include calculation of the effect size generalized eta-squared for which \strong{all non-manipluated (i.e., observed)} variables need to be specified via the \code{observed} argument to obtain correct results. When changing the effect size to \code{"pes"} (partial eta-squared) or \code{"none"} via \code{anova_table} this becomes unnecessary. + +If \code{check.contrasts = TRUE}, contrasts will be set to \code{"contr.sum"} for all between-subject factors if default contrasts are not equal to \code{"contr.sum"} or \code{attrib(factor, "contrasts") != "contr.sum"}. (within-subject factors are hard-coded \code{"contr.sum"}.) +} + +\subsection{Statistical Issues}{ +\strong{Type 3 sums of squares are default in \pkg{afex}.} While some authors argue that so-called type 3 sums of squares are dangerous and/or problematic (most notably Venables, 2000), they are the default in many commercial statistical application such as SPSS or SAS. Furthermore, statisticians with an applied perspective recommend type 3 tests (e.g., Maxwell and Delaney, 2004). Consequently, they are the default for the ANOVA functions described here. For some more discussion on this issue see \href{http://stats.stackexchange.com/q/6208/442}{here}. + +Note that lower order effects (e.g., main effects) in type 3 ANOVAs are only meaningful with \href{http://www.ats.ucla.edu/stat/mult_pkg/faq/general/effect.htm}{effects coding}. That is, contrasts should be set to \code{\link{contr.sum}} to obtain meaningful results. This is imposed automatically for the functions discussed here as long as \code{check.contrasts} is \code{TRUE} (the default). I nevertheless recommend to set the contrasts globally to \code{contr.sum} via running \code{\link{set_sum_contrasts}}. For a discussion of the other (non-recommended) coding schemes see \href{http://www.ats.ucla.edu/stat/r/library/contrast_coding.htm}{here}. +} + +\subsection{Follow-Up Contrasts and Post-Hoc Tests}{ +The S3 object returned per default can be directly passed to \code{lsmeans::lsmeans} for further analysis. This allows to test any type of contrasts that might be of interest independent of whether or not this contrast involves between-subject variables, within-subject variables, or a combination thereof. The general procedure to run those contrasts is the following (see Examples for a full example): + + \enumerate{ + \item Estimate an \code{afex_aov} object with the function returned here. For example: \code{x <- aov_car(dv ~ a*b + (id/c), d)} + \item Obtain a \code{\link[lsmeans]{ref.grid}} object by running \code{\link[lsmeans]{lsmeans}} on the \code{afex_aov} object from step 1 using the factors involved in the contrast. For example: \code{r <- lsmeans(x, ~a:c)} + \item Create a list containing the desired contrasts on the reference grid object from step 2. For example: \code{con1 <- list(a_x = c(-1, 1, 0, 0, 0, 0), b_x = c(0, 0, -0.5, -0.5, 0, 1))} + \item Test the contrast on the reference grid using \code{\link[lsmeans]{contrast}}. For example: \code{contrast(r, con1)} + \item To control for multiple testing p-value adjustments can be specified. For example the Bonferroni-Holm correction: \code{contrast(r, con1, adjust = "holm")} + } + + Note that \pkg{lsmeans} allows for a variety of advanced settings and simplifiations, for example: all pairwise comparison of a single factor using one command (e.g., \code{lsmeans(x, "a", contr = "pairwise")}) or advanced control for multiple testing by passing objects to \pkg{multcomp}. A comprehensive overview of the functionality is provided in the accompanying vignettes (see \href{http://cran.r-project.org/package=lsmeans}{here}). + + A caveat regarding the use of \pkg{lsmeans} concerns the assumption of sphericity for ANOVAs including within-subjects/repeated-measures factors (with more than two levels). While the ANOVA tables per default report results using the Greenhousse-Geisser correction, no such correction is available when using \pkg{lsmeans}. This may result in anti-conservative tests. + + \pkg{lsmeans} is loaded/attached automatically when loading \pkg{afex} via \code{library} or \code{require}. +} + +\subsection{Methods for \code{afex_aov} Objects}{ +A full overview over the methods provided for \code{afex_aov} objects is provided in the corresponding help page: \code{\link{afex_aov-methods}}. The probably most important ones for end-users are \code{summary} and \code{anova}. + +The \code{summary} method returns, for ANOVAs containing within-subject (repeated-measures) factors with more than two levels, the complete univariate analysis: Results without df-correction, the Greenhouse-Geisser corrected results, the Hyunh-Feldt corrected results, and the results of the Mauchly test for sphericity. + +The \code{anova} method returns a \code{data.frame} of class \code{"anova"} containing the ANOVA table in numeric form (i.e., the one in slot \code{anova_table} of a \code{afex_aov}). This method has arguments such as \code{correction} and \code{es} and can be used to obtain an ANOVA table with different correction than the one initially specified. +} +} +\note{ +Calculation of ANOVA models via \code{aov} (which is done per default) can be comparatively slow and produce comparatively large objects for ANOVAs with many within-subjects factors or levels. To avoid this calculation set the return argument to \code{"nice"}. This can also be done globally via \code{afex_options(return_aov = "nice")}. \code{return = "nice"} also produces the default output of previous versions of afex (versions 0.13 and earlier). + +The id variable and variables entered as within-subjects (i.e., repeated-measures) factors are silently converted to factors. Levels of within-subject factors are converted to valid variable names using \code{\link{make.names}(...,unique=TRUE)}. Unused factor levels are silently dropped on all variables. + +Contrasts attached to a factor as an attribute are probably not preserved and not supported. + +The workhorse is \code{aov_car}. \code{aov_4} and \code{aov_ez} only construe and pass an appropriate formula to \code{aov_car}. Use \code{print.formula = TRUE} to view this formula. + +In contrast to \code{\link{aov}} \code{aov_car} assumes that all factors to the right of \code{/} in the \code{Error} term are belonging together. Consequently, \code{Error(id/(a*b))} and \code{Error(id/a*b)} are identical (which is not true for \code{\link{aov}}). +} +\examples{ + +########################## +## 1: Specifying ANOVAs ## +########################## + +# Example using a purely within-subjects design +# (Maxwell & Delaney, 2004, Chapter 12, Table 12.5, p. 578): +data(md_12.1) +aov_ez("id", "rt", md_12.1, within = c("angle", "noise"), + anova_table=list(correction = "none", es = "none")) + +# Default output +aov_ez("id", "rt", md_12.1, within = c("angle", "noise")) + + +# examples using obk.long (see ?obk.long), a long version of the OBrienKaiser dataset (car package). +# Data is a split-plot or mixed design: contains both within- and between-subjects factors. +data(obk.long, package = "afex") + +# estimate mixed ANOVA on the full design: +aov_car(value ~ treatment * gender + Error(id/(phase*hour)), + data = obk.long, observed = "gender") + +aov_4(value ~ treatment * gender + (phase*hour|id), + data = obk.long, observed = "gender") + +aov_ez("id", "value", obk.long, between = c("treatment", "gender"), + within = c("phase", "hour"), observed = "gender") + +# the three calls return the same ANOVA table: +## Effect df MSE F ges p.value +## 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 + + +# "numeric" variables are per default converted to factors (as long as factorize = TRUE): +obk.long$hour2 <- as.numeric(as.character(obk.long$hour)) + +# gives same results as calls before +aov_car(value ~ treatment * gender + Error(id/hour2*phase), + data = obk.long, observed = c("gender")) + + +# 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) + +aov_4(value ~ treatment * gender + age + (phase*hour|id), + data = obk.long, observed = c("gender", "age"), factorize = FALSE) + +aov_ez("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") + +aov_ez("id", "value", obk.long, c("treatment", "gender"), "hour", observed = "gender") + +# aggregating over both within-subjects factors (again with warning), +# only between-subjects factors: +aov_car(value ~ treatment * gender + Error(id), data = obk.long, observed = c("gender")) +aov_4(value ~ treatment * gender + (1|id), data = obk.long, observed = c("gender")) +aov_ez("id", "value", obk.long, between = c("treatment", "gender"), observed = "gender") + +# only within-subject factors (ignoring between-subjects factors) +aov_car(value ~ Error(id/(phase*hour)), data = obk.long) +aov_4(value ~ (phase*hour|id), data = obk.long) +aov_ez("id", "value", obk.long, within = c("phase", "hour")) + +### changing defaults of ANOVA table: + +# no df-correction & partial eta-squared: +aov_car(value ~ treatment * gender + Error(id/(phase*hour)), + data = obk.long, anova_table = list(correction = "none", es = "pes")) + +# no df-correction and no MSE +aov_car(value ~ treatment * gender + Error(id/(phase*hour)), + data = obk.long,observed = "gender", + anova_table = list(correction = "none", MSE = FALSE)) + + +########################### +## 2: Follow-up Analysis ## +########################### + +# use data as above +data(obk.long, package = "afex") + +# 1. obtain afex_aov object: +a1 <- aov_ez("id", "value", obk.long, between = c("treatment", "gender"), + within = c("phase", "hour"), observed = "gender") + +# 1b. plot data: +lsmip(a1, gender ~ hour | treatment+phase) + +# 2. obtain reference grid object: +r1 <- lsmeans(a1, ~treatment +phase) +r1 + +# 3. create list of contrasts on the reference grid: +c1 <- list( + A_B_pre = c(0, -1, 1, rep(0, 6)), # A versus B for pretest + A_B_comb = c(0, 0, 0, 0, -0.5, 0.5, 0, -0.5, 0.5), # A vs. B for post and follow-up combined + effect_post = c(0, 0, 0, -1, 0.5, 0.5, 0, 0, 0), # control versus A&B post + effect_fup = c(0, 0, 0, 0, 0, 0, -1, 0.5, 0.5), # control versus A&B follow-up + effect_comb = c(0, 0, 0, -0.5, 0.25, 0.25, -0.5, 0.25, 0.25) # control versus A&B combined +) + +# 4. test contrasts on reference grid: +contrast(r1, c1) + +# same as before, but using Bonferroni-Holm correction for multiple testing: +contrast(r1, c1, adjust = "holm") + +# 2. (alternative): all pairwise comparisons of treatment: +lsmeans(a1, "treatment", contr = "pairwise") + +####################### +## 3: Other examples ## +####################### +data(obk.long, package = "afex") + +# replicating ?Anova using aov_car: +obk_anova <- aov_car(value ~ treatment * gender + Error(id/(phase*hour)), + data = obk.long, type = 2) +# in contrast to aov you do not need the within-subject factors outside Error() + +str(obk_anova, 1, give.attr = FALSE) +## List of 6 +## $ anova_table:Classes 'anova' and 'data.frame': 15 obs. of 6 variables: +## $ aov :List of 5 +## $ Anova :List of 14 +## $ lm :List of 13 +## $ data :List of 3 +## $ information:List of 5 + +obk_anova$Anova +## 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 + +} +\author{ +Henrik Singmann + +The design of these functions was influenced by \code{\link[ez]{ezANOVA}} from package \pkg{ez}. +} +\references{ +Maxwell, S. E., & Delaney, H. D. (2004). \emph{Designing Experiments and Analyzing Data: A Model-Comparisons Perspective}. Mahwah, N.J.: Lawrence Erlbaum Associates. + +Venables, W.N. (2000). \emph{Exegeses on linear models}. Paper presented to the S-Plus User's Conference, Washington DC, 8-9 October 1998, Washington, DC. Available from: \url{http://www.stats.ox.ac.uk/pub/MASS3/Exegeses.pdf} +} +\seealso{ +Various methods for objects of class \code{afex_aov} are available: \code{\link{afex_aov-methods}} + +\code{\link{nice}} creates the nice ANOVA tables which is by default printed. See also there for a slightly longer discussion of the available effect sizes. + +\code{\link{mixed}} provides a (formula) interface for obtaining p-values for mixed-models via \pkg{lme4}. +} + diff --git a/man/compare.2.vectors.Rd b/man/compare.2.vectors.Rd index 63d82ee..24c34ed 100644 --- a/man/compare.2.vectors.Rd +++ b/man/compare.2.vectors.Rd @@ -1,82 +1,82 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/compare.2.vectors.R -\encoding{UTF-8} -\name{compare.2.vectors} -\alias{compare.2.vectors} -\title{Compare two vectors using various tests.} -\usage{ -compare.2.vectors(x, y, paired = FALSE, na.rm = FALSE, - tests = c("parametric", "nonparametric"), coin = TRUE, - alternative = "two.sided", - perm.distribution = approximate(100000), - wilcox.exact = NULL, wilcox.correct = TRUE) -} -\arguments{ -\item{x}{a (non-empty) numeric vector of data values.} - -\item{y}{a (non-empty) numeric vector of data values.} - -\item{paired}{a logical whether the data is paired. Default is \code{FALSE}.} - -\item{na.rm}{logical. Should \code{NA} be removed? Default is \code{FALSE}.} - -\item{tests}{Which tests to report, parametric or nonparamteric? The default \code{c("parametric", "nonparametric")} reports both. See details. (Arguments may be abbreviated).} - -\item{coin}{logical or character. Should (permutation) tests from the \pkg{coin} package be reported? Default is \code{TRUE} corresponding to all implemented tests. \code{FALSE} calculates no tests from \pkg{coin}. A character vector may include any of the following (potentially abbreviated) implemented tests (see also Details): \code{c("permutation", "Wilcoxon", "median")}} - -\item{alternative}{a character, the alternative hypothesis must be one of \code{"two.sided"} (default), \code{"greater"} or \code{"less"}. You can specify just the initial letter, will be passed to all functions.} - -\item{perm.distribution}{\code{distribution} argument to \pkg{coin}, see \code{\link[coin]{NullDistribution}} or , \code{\link[coin]{IndependenceTest}}. Defaults to \code{approximate(100000)} indicating an approximation of the excat conditional distribution with 100.000 Monte Carlo samples. One can use \code{"exact"} for small samples and if \code{paired = FALSE}.} - -\item{wilcox.exact}{\code{exact} argument to \code{\link{wilcox.test}}.} - -\item{wilcox.correct}{\code{correct} argument to \code{\link{wilcox.test}}.} -} -\value{ -a list with up to two elements (i.e., \code{paramteric} and/or \code{nonparamteric}) each containing a \code{data.frame} with the following columns: \code{test}, \code{test.statistic}, \code{test.value}, \code{test.df}, \code{p}. -} -\description{ -Compares two vectors \code{x} and \code{y} using t-test, Welch-test (also known as Satterthwaite), Wilcoxon-test, and a permutation test implemented in \pkg{coin}. -} -\details{ -The \code{parametric} tests (currently) only contain the \emph{t}-test and Welch/Statterwaithe/Smith/unequal variance \emph{t}-test implemented in \code{\link{t.test}}. The latter one is only displayed if \code{paired = FALSE}. - -The \code{nonparametric} tests (currently) contain the Wilcoxon test implemented in \code{\link{wilcox.test}} (\code{stats::Wilcoxon}) and (if \code{coin = TRUE}) the following tests implemented in \pkg{coin}: - -\itemize{ -\item a \code{permutation} test \code{\link{oneway_test}} (the only test in this selction not using a rank transformation), -\item the \code{Wilcoxon} test \code{\link{wilcox_test}} (\code{coin::Wilcoxon}), and -\item the \code{median} test \code{median_test}. -} -Note that the two implementations of the Wilcoxon test probably differ. This is due to differences in the calculation of the Null distributions. -} -\examples{ - -with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2])) - -# gives: -## $parametric -## test test.statistic test.value test.df p -## 1 t t -1.861 18.00 0.07919 -## 2 Welch t -1.861 17.78 0.07939 -## -## $nonparametric -## test test.statistic test.value test.df p -## 1 stats::Wilcoxon W 25.500 NA 0.06933 -## 2 permutation Z -1.751 NA 0.08154 -## 3 coin::Wilcoxon Z -1.854 NA 0.06487 -## 4 median Z -1.744 NA 0.17867 - -# compare with: -with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], alternative = "less")) - -with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], alternative = "greater")) - -# doesn't make much sense as the data is not paired, but whatever: -with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], paired = TRUE)) - -# from ?t.test: -compare.2.vectors(1:10,y=c(7:20, 200)) - -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/compare.2.vectors.R +\encoding{UTF-8} +\name{compare.2.vectors} +\alias{compare.2.vectors} +\title{Compare two vectors using various tests.} +\usage{ +compare.2.vectors(x, y, paired = FALSE, na.rm = FALSE, + tests = c("parametric", "nonparametric"), coin = TRUE, + alternative = "two.sided", + perm.distribution = approximate(100000), + wilcox.exact = NULL, wilcox.correct = TRUE) +} +\arguments{ +\item{x}{a (non-empty) numeric vector of data values.} + +\item{y}{a (non-empty) numeric vector of data values.} + +\item{paired}{a logical whether the data is paired. Default is \code{FALSE}.} + +\item{na.rm}{logical. Should \code{NA} be removed? Default is \code{FALSE}.} + +\item{tests}{Which tests to report, parametric or nonparamteric? The default \code{c("parametric", "nonparametric")} reports both. See details. (Arguments may be abbreviated).} + +\item{coin}{logical or character. Should (permutation) tests from the \pkg{coin} package be reported? Default is \code{TRUE} corresponding to all implemented tests. \code{FALSE} calculates no tests from \pkg{coin}. A character vector may include any of the following (potentially abbreviated) implemented tests (see also Details): \code{c("permutation", "Wilcoxon", "median")}} + +\item{alternative}{a character, the alternative hypothesis must be one of \code{"two.sided"} (default), \code{"greater"} or \code{"less"}. You can specify just the initial letter, will be passed to all functions.} + +\item{perm.distribution}{\code{distribution} argument to \pkg{coin}, see \code{\link[coin]{NullDistribution}} or , \code{\link[coin]{IndependenceTest}}. Defaults to \code{approximate(100000)} indicating an approximation of the excat conditional distribution with 100.000 Monte Carlo samples. One can use \code{"exact"} for small samples and if \code{paired = FALSE}.} + +\item{wilcox.exact}{\code{exact} argument to \code{\link{wilcox.test}}.} + +\item{wilcox.correct}{\code{correct} argument to \code{\link{wilcox.test}}.} +} +\value{ +a list with up to two elements (i.e., \code{paramteric} and/or \code{nonparamteric}) each containing a \code{data.frame} with the following columns: \code{test}, \code{test.statistic}, \code{test.value}, \code{test.df}, \code{p}. +} +\description{ +Compares two vectors \code{x} and \code{y} using t-test, Welch-test (also known as Satterthwaite), Wilcoxon-test, and a permutation test implemented in \pkg{coin}. +} +\details{ +The \code{parametric} tests (currently) only contain the \emph{t}-test and Welch/Statterwaithe/Smith/unequal variance \emph{t}-test implemented in \code{\link{t.test}}. The latter one is only displayed if \code{paired = FALSE}. + +The \code{nonparametric} tests (currently) contain the Wilcoxon test implemented in \code{\link{wilcox.test}} (\code{stats::Wilcoxon}) and (if \code{coin = TRUE}) the following tests implemented in \pkg{coin}: + +\itemize{ +\item a \code{permutation} test \code{\link{oneway_test}} (the only test in this selction not using a rank transformation), +\item the \code{Wilcoxon} test \code{\link{wilcox_test}} (\code{coin::Wilcoxon}), and +\item the \code{median} test \code{median_test}. +} +Note that the two implementations of the Wilcoxon test probably differ. This is due to differences in the calculation of the Null distributions. +} +\examples{ + +with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2])) + +# gives: +## $parametric +## test test.statistic test.value test.df p +## 1 t t -1.861 18.00 0.07919 +## 2 Welch t -1.861 17.78 0.07939 +## +## $nonparametric +## test test.statistic test.value test.df p +## 1 stats::Wilcoxon W 25.500 NA 0.06933 +## 2 permutation Z -1.751 NA 0.08154 +## 3 coin::Wilcoxon Z -1.854 NA 0.06487 +## 4 median Z -1.744 NA 0.17867 + +# compare with: +with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], alternative = "less")) + +with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], alternative = "greater")) + +# doesn't make much sense as the data is not paired, but whatever: +with(sleep, compare.2.vectors(extra[group == 1], extra[group == 2], paired = TRUE)) + +# from ?t.test: +compare.2.vectors(1:10,y=c(7:20, 200)) + +} + diff --git a/man/deprecated.Rd b/man/deprecated.Rd index cb44998..9e4d747 100644 --- a/man/deprecated.Rd +++ b/man/deprecated.Rd @@ -1,27 +1,27 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/deprecated.R -\name{aov.car} -\alias{afex-deprecated} -\alias{aov.car} -\alias{aov4} -\alias{ez.glm} -\title{Deprecated functions} -\usage{ -aov.car(...) - -ez.glm(...) - -aov4(...) -} -\arguments{ -\item{...}{arguments passed from the old functions of the style -\code{foo.bar()} to the new functions \code{foo_bar()}} -} -\description{ -These functions have been renamed and deprecated in \pkg{afex}: -\code{aov.car()} (use \code{\link{aov_car}()}), -\code{ez.glm()} (use \code{\link{aov_ez}()}), -\code{aov4()} (use \code{\link{aov_4}()}). -} -\keyword{internal} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/deprecated.R +\name{aov.car} +\alias{afex-deprecated} +\alias{aov.car} +\alias{aov4} +\alias{ez.glm} +\title{Deprecated functions} +\usage{ +aov.car(...) + +ez.glm(...) + +aov4(...) +} +\arguments{ +\item{...}{arguments passed from the old functions of the style +\code{foo.bar()} to the new functions \code{foo_bar()}} +} +\description{ +These functions have been renamed and deprecated in \pkg{afex}: +\code{aov.car()} (use \code{\link{aov_car}()}), +\code{ez.glm()} (use \code{\link{aov_ez}()}), +\code{aov4()} (use \code{\link{aov_4}()}). +} +\keyword{internal} + diff --git a/man/ems.Rd b/man/ems.Rd index 011a532..373876c 100644 --- a/man/ems.Rd +++ b/man/ems.Rd @@ -1,46 +1,46 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/ems.R -\name{ems} -\alias{ems} -\title{Expected values of mean squares for factorial designs} -\usage{ -ems(design, nested = NULL, random = NULL) -} -\arguments{ -\item{design}{A \code{formula} object specifying the factors in the design (except residual error, which is always implicitly included). The left hand side of the \code{~} is the symbol that will be used to denote the number of replications per lowest-level factor combination (I usually use "r" or "n"). The right hand side should include all fixed and random factors separated by \code{*}. Factor names should be single letters.} - -\item{nested}{A \code{character} vector, where each element is of the form \code{"A/B"}, indicating that the levels of factor B are nested under the levels of factor A.} - -\item{random}{A \code{character} string indicating, without spaces or any separating characters, which of the factors specified in the design are random.} -} -\value{ -The returned value is a formatted table where the rows represent the mean squares, the columns represent the variance components that comprise the various mean squares, and the entries in each cell represent the terms that are multiplied and summed to form the expectation of the mean square for that row. Each term is either the lower-case version of one of the experimental factors, which indicates the number of levels for that factor, or a "1", which means the variance component for that column is contributes to the mean square but is not multiplied by anything else. -} -\description{ -Implements the Cornfield-Tukey algorithm for deriving the expected values of the mean squares for factorial designs. -} -\note{ -Names for factors or parameters should only be of length 1 as they are simply concatenated in the returned table. -} -\examples{ -# 2x2 mixed anova -# A varies between-subjects, B varies within-subjects -ems(r ~ A*B*S, nested="A/S", random="S") - -# Clark (1973) example -# random Subjects, random Words, fixed Treatments -ems(r ~ S*W*T, nested="T/W", random="SW") - -# EMSs for Clark design if Words are fixed -ems(r ~ S*W*T, nested="T/W", random="S") - -} -\author{ -Jake Westfall -} -\seealso{ -A detailed description with explanation of the example can be found \href{http://www.talkstats.com/showthread.php/18603-Share-your-functions-amp-code?p=82050&viewfull=1\#post82050}{elsewhere} (note that the \code{design} argument of the function described at the link behaves slightly different). - -Example applications of this function can be found here: \url{http://stats.stackexchange.com/a/122662/442}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/ems.R +\name{ems} +\alias{ems} +\title{Expected values of mean squares for factorial designs} +\usage{ +ems(design, nested = NULL, random = NULL) +} +\arguments{ +\item{design}{A \code{formula} object specifying the factors in the design (except residual error, which is always implicitly included). The left hand side of the \code{~} is the symbol that will be used to denote the number of replications per lowest-level factor combination (I usually use "r" or "n"). The right hand side should include all fixed and random factors separated by \code{*}. Factor names should be single letters.} + +\item{nested}{A \code{character} vector, where each element is of the form \code{"A/B"}, indicating that the levels of factor B are nested under the levels of factor A.} + +\item{random}{A \code{character} string indicating, without spaces or any separating characters, which of the factors specified in the design are random.} +} +\value{ +The returned value is a formatted table where the rows represent the mean squares, the columns represent the variance components that comprise the various mean squares, and the entries in each cell represent the terms that are multiplied and summed to form the expectation of the mean square for that row. Each term is either the lower-case version of one of the experimental factors, which indicates the number of levels for that factor, or a "1", which means the variance component for that column is contributes to the mean square but is not multiplied by anything else. +} +\description{ +Implements the Cornfield-Tukey algorithm for deriving the expected values of the mean squares for factorial designs. +} +\note{ +Names for factors or parameters should only be of length 1 as they are simply concatenated in the returned table. +} +\examples{ +# 2x2 mixed anova +# A varies between-subjects, B varies within-subjects +ems(r ~ A*B*S, nested="A/S", random="S") + +# Clark (1973) example +# random Subjects, random Words, fixed Treatments +ems(r ~ S*W*T, nested="T/W", random="SW") + +# EMSs for Clark design if Words are fixed +ems(r ~ S*W*T, nested="T/W", random="S") + +} +\author{ +Jake Westfall +} +\seealso{ +A detailed description with explanation of the example can be found \href{http://www.talkstats.com/showthread.php/18603-Share-your-functions-amp-code?p=82050&viewfull=1\#post82050}{elsewhere} (note that the \code{design} argument of the function described at the link behaves slightly different). + +Example applications of this function can be found here: \url{http://stats.stackexchange.com/a/122662/442}. +} + diff --git a/man/ks2013.3.Rd b/man/ks2013.3.Rd index 78b00cf..04f93e5 100644 --- a/man/ks2013.3.Rd +++ b/man/ks2013.3.Rd @@ -1,40 +1,40 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/ks2013.3-data.R -\docType{data} -\encoding{UTF-8} -\name{ks2013.3} -\alias{ks2013.3} -\title{Data from Klauer & Singmann (2013, Experiment 3)} -\format{A data.frame with 1440 rows and 6 variables.} -\source{ -Klauer, K. C., & Singmann, H. (2013). Does logic feel good? Testing for intuitive detection of logicality in syllogistic reasoning. Journal of Experimental Psychology: Learning, Memory, and Cognition, 39(4), 1265-1273. http://doi.org/10.1037/a0030530 - -Morsanyi, K., & Handley, S. J. (2012). Logic feels so good-I like it! Evidence for intuitive detection of logicality in syllogistic reasoning. Journal of Experimental Psychology: Learning, Memory, and Cognition, 38(3), 596-616. http://doi.org/10.1037/a0026099 -} -\usage{ -ks2013.3 -} -\description{ -Klauer and Singmann (2013) attempted to replicate an hypothesis of Morsanyi and Handley (2012) according to which individuals have an intuitive sense of logicality. Specifically, Morsanyi and Handley apparently provided evidence that the logical status of syllogisms (i.e., valid or invalid) affects participants liking ratings of the conclusion of syllogisms. Conclusions from valid syllogisms (e.g., Some snakes are poisonous. No poisonous animals are obbs. Some snakes are not obbs.) received higher liking ratings than conclusions from invalid syllogisms (e.g., No ice creams are vons. Some vons are hot. Some ice creams are not hot.). It is important to noted that in the experiments participants were simply shown the premises and conclusion in succession, they were not asked whether or not the conclusion follows or to generate their own conclusion. Their task was simply to judge how much they liked the "final" statement (i.e., the conclusion). -} -\details{ -In their Experiment 3 Klauer and Singmann (2013) tested the idea that this finding was a consequence of the materials used and not an effect intuitive logic. More specifically, they observed that in the original study by Morsanyi and Handley (2012) a specific content always appeared with the same logical status. For example, the "ice-cream" content only ever appeared as an invalid syllogism as in the example above but never in a valid syllogism. In other words, content was perfectly confounded with logical status in the original study. To test this they compared a condition in which the logical status was confounded with the content (the "fixed" condition) with a condition in which the contents were randomly assigned to a logical status across participants (the "random" condition). For example, the ice-cream content was, across participants, equally like to appear in the invalid form as given above or in the following valid form: No hot things are vons. Some vons are ice creams. Conclusion Some ice creams are not hot. - -The data.frame contains the raw responses of all 60 participants (30 per condition) reported in Klauer & Singmann (2013). Each participants provided 24 responses, 12 to valid and 12 to invalid syllogisms. Furthermore, 8 syllogisms had a believable conclusion (e.g., Some ice creams are not hot.), 8 had an abstract conclusion (e.g., Some snakes are not obbs.), and 8 had an unbelievable conclusion (e.g., Some animals are not monkeys.). The number of the contents corresponds to the numbering given in Morsanyi and Handley (2012, p. 616). -} -\examples{ -data("ks2013.3") - -# replicate results reported in Klauer & Singmann (2013, p. 1270) - -aov_ez("id", "response", ks2013.3, between = "condition", - within = c("believability", "validity")) - -aov_ez("id", "response", subset(ks2013.3, condition == "fixed"), - within = c("believability", "validity")) - -aov_ez("id", "response", subset(ks2013.3, condition == "random"), - within = c("believability", "validity")) -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/ks2013.3-data.R +\docType{data} +\encoding{UTF-8} +\name{ks2013.3} +\alias{ks2013.3} +\title{Data from Klauer & Singmann (2013, Experiment 3)} +\format{A data.frame with 1440 rows and 6 variables.} +\source{ +Klauer, K. C., & Singmann, H. (2013). Does logic feel good? Testing for intuitive detection of logicality in syllogistic reasoning. Journal of Experimental Psychology: Learning, Memory, and Cognition, 39(4), 1265-1273. http://doi.org/10.1037/a0030530 + +Morsanyi, K., & Handley, S. J. (2012). Logic feels so good-I like it! Evidence for intuitive detection of logicality in syllogistic reasoning. Journal of Experimental Psychology: Learning, Memory, and Cognition, 38(3), 596-616. http://doi.org/10.1037/a0026099 +} +\usage{ +ks2013.3 +} +\description{ +Klauer and Singmann (2013) attempted to replicate an hypothesis of Morsanyi and Handley (2012) according to which individuals have an intuitive sense of logicality. Specifically, Morsanyi and Handley apparently provided evidence that the logical status of syllogisms (i.e., valid or invalid) affects participants liking ratings of the conclusion of syllogisms. Conclusions from valid syllogisms (e.g., Some snakes are poisonous. No poisonous animals are obbs. Some snakes are not obbs.) received higher liking ratings than conclusions from invalid syllogisms (e.g., No ice creams are vons. Some vons are hot. Some ice creams are not hot.). It is important to noted that in the experiments participants were simply shown the premises and conclusion in succession, they were not asked whether or not the conclusion follows or to generate their own conclusion. Their task was simply to judge how much they liked the "final" statement (i.e., the conclusion). +} +\details{ +In their Experiment 3 Klauer and Singmann (2013) tested the idea that this finding was a consequence of the materials used and not an effect intuitive logic. More specifically, they observed that in the original study by Morsanyi and Handley (2012) a specific content always appeared with the same logical status. For example, the "ice-cream" content only ever appeared as an invalid syllogism as in the example above but never in a valid syllogism. In other words, content was perfectly confounded with logical status in the original study. To test this they compared a condition in which the logical status was confounded with the content (the "fixed" condition) with a condition in which the contents were randomly assigned to a logical status across participants (the "random" condition). For example, the ice-cream content was, across participants, equally like to appear in the invalid form as given above or in the following valid form: No hot things are vons. Some vons are ice creams. Conclusion Some ice creams are not hot. + +The data.frame contains the raw responses of all 60 participants (30 per condition) reported in Klauer & Singmann (2013). Each participants provided 24 responses, 12 to valid and 12 to invalid syllogisms. Furthermore, 8 syllogisms had a believable conclusion (e.g., Some ice creams are not hot.), 8 had an abstract conclusion (e.g., Some snakes are not obbs.), and 8 had an unbelievable conclusion (e.g., Some animals are not monkeys.). The number of the contents corresponds to the numbering given in Morsanyi and Handley (2012, p. 616). +} +\examples{ +data("ks2013.3") + +# replicate results reported in Klauer & Singmann (2013, p. 1270) + +aov_ez("id", "response", ks2013.3, between = "condition", + within = c("believability", "validity")) + +aov_ez("id", "response", subset(ks2013.3, condition == "fixed"), + within = c("believability", "validity")) + +aov_ez("id", "response", subset(ks2013.3, condition == "random"), + within = c("believability", "validity")) +} +\keyword{dataset} + diff --git a/man/md_12.1.Rd b/man/md_12.1.Rd index ebc3e16..cb328da 100644 --- a/man/md_12.1.Rd +++ b/man/md_12.1.Rd @@ -1,49 +1,49 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/md_12.1-data.R -\docType{data} -\encoding{UTF-8} -\name{md_12.1} -\alias{md_12.1} -\title{Data 12.1 from Maxwell & Delaney} -\format{A data.frame with 60 rows and 4 variables.} -\source{ -Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 -} -\usage{ -md_12.1 -} -\description{ -Hypothetical Reaction Time Data for 2 x 3 Perceptual Experiment: Example data for chapter 12 of Maaxwell and Delaney (2004, Table 12.1, p. 574) in long format. Has two within.subjects factors: angle and noise. -} -\details{ -Description from pp. 573: - -Suppose that a perceptual psychologist studying the visual system was interested in determining the -extent to which interfering visual stimuli slow the ability to recognize letters. Subjects are -brought into a laboratory and seated in front of a tachistoscope. Subjects are told that they will -see either the letter T or the letter I displayed on the screen. In some trials, the letter appears -by itself, but in other trials, the target letter is embedded in a group of other letters. This -variation in the display constitutes the first factor, which is referred to as noise. The noise -factor has two levels?absent and present. The other factor varied by the experimenter is where in -the display the target letter appears. This factor, which is called angle, has three levels. The -target letter is either shown at the center of the screen (i.e., 0° off-center, where the subject -has been instructed to fixate), 4° off-center or 8° off-center (in each case, the deviation from the -center varies randomly between left and right). Table 12.1 presents hypothetical data for 10 -subjects. As usual, the sample size is kept small to make the calculations easier to follow. The -dependent measure is reaction time (latency), measured in milliseconds (ms), required by a subject -to identify the correct target letter. Notice that each subject has six scores, one for each -combination of the 2 x 3 design. In an actual perceptual experiment, each of these six scores would -itself be the mean score for that subject across a number of trials in the particular condition. -Although "trials" could be used as a third within-subjects factor in such a situation, more -typically trials are simply averaged over to obtain a more stable measure of the individual's -performance in each condition. -} -\examples{ -data(md_12.1) - -# Table 12.5 (p. 578): -aov_ez("id", "rt", md_12.1, within = c("angle", "noise"), - args.return=list(correction = "none", es = "none")) -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/md_12.1-data.R +\docType{data} +\encoding{UTF-8} +\name{md_12.1} +\alias{md_12.1} +\title{Data 12.1 from Maxwell & Delaney} +\format{A data.frame with 60 rows and 4 variables.} +\source{ +Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 +} +\usage{ +md_12.1 +} +\description{ +Hypothetical Reaction Time Data for 2 x 3 Perceptual Experiment: Example data for chapter 12 of Maaxwell and Delaney (2004, Table 12.1, p. 574) in long format. Has two within.subjects factors: angle and noise. +} +\details{ +Description from pp. 573: + +Suppose that a perceptual psychologist studying the visual system was interested in determining the +extent to which interfering visual stimuli slow the ability to recognize letters. Subjects are +brought into a laboratory and seated in front of a tachistoscope. Subjects are told that they will +see either the letter T or the letter I displayed on the screen. In some trials, the letter appears +by itself, but in other trials, the target letter is embedded in a group of other letters. This +variation in the display constitutes the first factor, which is referred to as noise. The noise +factor has two levels?absent and present. The other factor varied by the experimenter is where in +the display the target letter appears. This factor, which is called angle, has three levels. The +target letter is either shown at the center of the screen (i.e., 0° off-center, where the subject +has been instructed to fixate), 4° off-center or 8° off-center (in each case, the deviation from the +center varies randomly between left and right). Table 12.1 presents hypothetical data for 10 +subjects. As usual, the sample size is kept small to make the calculations easier to follow. The +dependent measure is reaction time (latency), measured in milliseconds (ms), required by a subject +to identify the correct target letter. Notice that each subject has six scores, one for each +combination of the 2 x 3 design. In an actual perceptual experiment, each of these six scores would +itself be the mean score for that subject across a number of trials in the particular condition. +Although "trials" could be used as a third within-subjects factor in such a situation, more +typically trials are simply averaged over to obtain a more stable measure of the individual's +performance in each condition. +} +\examples{ +data(md_12.1) + +# Table 12.5 (p. 578): +aov_ez("id", "rt", md_12.1, within = c("angle", "noise"), + args.return=list(correction = "none", es = "none")) +} +\keyword{dataset} + diff --git a/man/md_15.1.Rd b/man/md_15.1.Rd index 5952222..fc414c5 100644 --- a/man/md_15.1.Rd +++ b/man/md_15.1.Rd @@ -1,69 +1,69 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/md_15.1-data.R -\docType{data} -\encoding{UTF-8} -\name{md_15.1} -\alias{md_15.1} -\title{Data 15.1 / 11.5 from Maxwell & Delaney} -\format{A data.frame with 48 rows and 4 variables.} -\source{ -Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 766 -} -\usage{ -md_15.1 -} -\description{ -Hypothetical IQ Data from 12 children at 4 time points: Example data for chapter 11/15 of Maxwell and Delaney (2004, Table 15.1, p. 766) in long format. Has two one within-subjects factor: time. -} -\details{ -Description from pp. 534: - -The data show that 12 subjects have been observed in each of 4 conditions. To make the example easier to discuss, let's suppose that the 12 subjects are children who have been observed at 30, 36, 42, and 48 months of age. In each case, the dependent variable is the child's age-normed general cognitive score on the McCarthy Scales of Children's Abilities. Although the test is normed so that the mean score is independent of age for the general population, our 12 children may come from a population in which cognitive abilities are either growing more rapidly or less rapidly than average. Indeed, this is the hypothesis our data allow us to address. In other words, although the sample means suggest that the children's cognitive abilities are growing, a significance test is needed if we want to rule out sampling error as a likely explanation for the observed differences. - -To replicate the results in chapter 15 several different contrasts need to be applied, see Examples. - -\code{time} is time in months (centered at 0) and \code{timecat} is the same as a categorical variable. -} -\examples{ -### replicate results from Table 15.2 to 15.6 (Maxwell & Delaney, 2004, pp. 774) -data(md_15.1) - -### ANOVA results (Table 15.2) -aov_4(iq ~ timecat + (timecat|id),data=md_15.1, anova_table=list(correction = "none")) - -### Table 15.3 (random intercept only) -# we need to set the base level on the last level: -contrasts(md_15.1$timecat) <- contr.treatment(4, base = 4) -# "Type 3 Tests of Fixed Effects" -(t15.3 <- mixed(iq ~ timecat + (1|id),data=md_15.1, check.contrasts=FALSE)) -# "Solution for Fixed Effects" and "Covariance Parameter Estimates" -summary(t15.3$full.model) - -### make Figure 15.2 -plot(NULL, NULL, ylim = c(80, 140), xlim = c(30, 48), ylab = "iq", xlab = "time") -plyr::d_ply(md_15.1, plyr::.(id), function(x) lines(as.numeric(as.character(x$timecat)), x$iq)) - -### Table 15.4, page 789 -# random intercept plus slope -(t15.4 <- mixed(iq ~ timecat + (1+time|id),data=md_15.1, check.contrasts=FALSE)) -summary(t15.4$full.model) - -### Table 15.5, page 795 -# set up polynomial contrasts for timecat -contrasts(md_15.1$timecat) <- contr.poly -# fit all parameters separately -(t15.5 <- mixed(iq ~ timecat + (1+time|id), data=md_15.1, check.contrasts=FALSE, - per.parameter="timecat")) -# quadratic trend is considerably off, conclusions stay the same. - - -### Table 15.6, page 797 -# growth curve model -(t15.6 <- mixed(iq ~ time + (1+time|id),data=md_15.1)) -summary(t15.6$full.model) -} -\author{ -R code for examples written by Ulf Mertens and Henrik Singmann -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/md_15.1-data.R +\docType{data} +\encoding{UTF-8} +\name{md_15.1} +\alias{md_15.1} +\title{Data 15.1 / 11.5 from Maxwell & Delaney} +\format{A data.frame with 48 rows and 4 variables.} +\source{ +Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 766 +} +\usage{ +md_15.1 +} +\description{ +Hypothetical IQ Data from 12 children at 4 time points: Example data for chapter 11/15 of Maxwell and Delaney (2004, Table 15.1, p. 766) in long format. Has two one within-subjects factor: time. +} +\details{ +Description from pp. 534: + +The data show that 12 subjects have been observed in each of 4 conditions. To make the example easier to discuss, let's suppose that the 12 subjects are children who have been observed at 30, 36, 42, and 48 months of age. In each case, the dependent variable is the child's age-normed general cognitive score on the McCarthy Scales of Children's Abilities. Although the test is normed so that the mean score is independent of age for the general population, our 12 children may come from a population in which cognitive abilities are either growing more rapidly or less rapidly than average. Indeed, this is the hypothesis our data allow us to address. In other words, although the sample means suggest that the children's cognitive abilities are growing, a significance test is needed if we want to rule out sampling error as a likely explanation for the observed differences. + +To replicate the results in chapter 15 several different contrasts need to be applied, see Examples. + +\code{time} is time in months (centered at 0) and \code{timecat} is the same as a categorical variable. +} +\examples{ +### replicate results from Table 15.2 to 15.6 (Maxwell & Delaney, 2004, pp. 774) +data(md_15.1) + +### ANOVA results (Table 15.2) +aov_4(iq ~ timecat + (timecat|id),data=md_15.1, anova_table=list(correction = "none")) + +### Table 15.3 (random intercept only) +# we need to set the base level on the last level: +contrasts(md_15.1$timecat) <- contr.treatment(4, base = 4) +# "Type 3 Tests of Fixed Effects" +(t15.3 <- mixed(iq ~ timecat + (1|id),data=md_15.1, check.contrasts=FALSE)) +# "Solution for Fixed Effects" and "Covariance Parameter Estimates" +summary(t15.3$full.model) + +### make Figure 15.2 +plot(NULL, NULL, ylim = c(80, 140), xlim = c(30, 48), ylab = "iq", xlab = "time") +plyr::d_ply(md_15.1, plyr::.(id), function(x) lines(as.numeric(as.character(x$timecat)), x$iq)) + +### Table 15.4, page 789 +# random intercept plus slope +(t15.4 <- mixed(iq ~ timecat + (1+time|id),data=md_15.1, check.contrasts=FALSE)) +summary(t15.4$full.model) + +### Table 15.5, page 795 +# set up polynomial contrasts for timecat +contrasts(md_15.1$timecat) <- contr.poly +# fit all parameters separately +(t15.5 <- mixed(iq ~ timecat + (1+time|id), data=md_15.1, check.contrasts=FALSE, + per.parameter="timecat")) +# quadratic trend is considerably off, conclusions stay the same. + + +### Table 15.6, page 797 +# growth curve model +(t15.6 <- mixed(iq ~ time + (1+time|id),data=md_15.1)) +summary(t15.6$full.model) +} +\author{ +R code for examples written by Ulf Mertens and Henrik Singmann +} +\keyword{dataset} + diff --git a/man/md_16.1.Rd b/man/md_16.1.Rd index 6e9d528..41bdf2c 100644 --- a/man/md_16.1.Rd +++ b/man/md_16.1.Rd @@ -1,39 +1,39 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/md_16.1-data.R -\docType{data} -\encoding{UTF-8} -\name{md_16.1} -\alias{md_16.1} -\title{Data 16.1 / 10.9 from Maxwell & Delaney} -\format{A data.frame with 24 rows and 3 variables.} -\source{ -Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 -} -\usage{ -md_16.1 -} -\description{ -Hypothetical Reaction Time Data for 2 x 3 Perceptual Experiment: Example data for chapter 12 of Maaxwell and Delaney (2004, Table 12.1, p. 574) in long format. Has two within.subjects factors: angle and noise. -} -\details{ -Description from pp. 829: - -As brief background, the goal of the study here is to examine the extent to which female and male clinical psychology graduate student trainees may assign different severity ratings to clients at initial intake. Three female and 3 male graduate students are randomly selected to participate and each is randomly assigned four clients with whom to do an intake interview, after which each clinical trainee assigns a severity rating to each client, producing the data shown in Table 16.1. - -Note that I changed the labeling of the id slightly, so that they are now labeled from 1 to 6. Furthermore, I changed the contrasts of sex to \code{contr.treatment} to replicate the exact results of Table 16.3 (p. 837). -} -\examples{ -### 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-values stay 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) -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/md_16.1-data.R +\docType{data} +\encoding{UTF-8} +\name{md_16.1} +\alias{md_16.1} +\title{Data 16.1 / 10.9 from Maxwell & Delaney} +\format{A data.frame with 24 rows and 3 variables.} +\source{ +Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 +} +\usage{ +md_16.1 +} +\description{ +Hypothetical Reaction Time Data for 2 x 3 Perceptual Experiment: Example data for chapter 12 of Maaxwell and Delaney (2004, Table 12.1, p. 574) in long format. Has two within.subjects factors: angle and noise. +} +\details{ +Description from pp. 829: + +As brief background, the goal of the study here is to examine the extent to which female and male clinical psychology graduate student trainees may assign different severity ratings to clients at initial intake. Three female and 3 male graduate students are randomly selected to participate and each is randomly assigned four clients with whom to do an intake interview, after which each clinical trainee assigns a severity rating to each client, producing the data shown in Table 16.1. + +Note that I changed the labeling of the id slightly, so that they are now labeled from 1 to 6. Furthermore, I changed the contrasts of sex to \code{contr.treatment} to replicate the exact results of Table 16.3 (p. 837). +} +\examples{ +### 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-values stay 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) +} +\keyword{dataset} + diff --git a/man/md_16.4.Rd b/man/md_16.4.Rd index 6a3837b..783e30c 100644 --- a/man/md_16.4.Rd +++ b/man/md_16.4.Rd @@ -1,38 +1,38 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/md_16.4-data.R -\docType{data} -\encoding{UTF-8} -\name{md_16.4} -\alias{md_16.4} -\title{Data 16.4 from Maxwell & Delaney} -\format{A data.frame with 24 rows and 3 variables.} -\source{ -Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 -} -\usage{ -md_16.4 -} -\description{ -Data from a hypothetical inductive reasoning study. -} -\details{ -Description from pp. 841: - -Suppose an educational psychologist has developed an intervention to teach inductive reasoning skills to school children. She decides to test the efficacy of her intervention by conducting a randomized design. Three classrooms of students are randomly assigned to the treatment condition, and 3 other classrooms are assigned to the control. - -Table 16.4 shows hypothetical data collected from 29 children who participated in the study assessing the effectiveness of the intervention to increase inductive reasoning skills. We want to call your attention to several aspects of the data. First, the 15 children with condition values of 0 received the control, whereas the 14 children with condition values of 1 received the treatment. Second, 4 of the children in the control condition were students in control Classroom 1, 6 of them were students in control Classroom 2, and 5 were students in control Classroom 3. Along similar lines, 3 of the children in the treatment condition were students in treatment Classroom 1, 5 were students in treatment Classroom 2, and 6 were students in treatment Classroom 3. It is essential to understand that there are a total of six classrooms here; we have coded classroom from 1 to 3 for control as well as treatment, because we will indicate to PROC MIXED that classroom is nested under treatment. Third, scores on the dependent variable appear in the rightmost column under the variable label "induct." - -Note that it would make a lot more sense to change the labeling of room from 1 to 3 nested within cond to 1 to 6. However, I keep this in line with the original. The random effects term in the call to mixed is therefore a little bit uncommon.#' -} -\examples{ -# 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) -# p-values (almost) hold: -(mixed2 <- mixed(induct ~ cond + (1|room:cond), md_16.4)) -# (1|room:cond) is needed because room is nested within cond. -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/md_16.4-data.R +\docType{data} +\encoding{UTF-8} +\name{md_16.4} +\alias{md_16.4} +\title{Data 16.4 from Maxwell & Delaney} +\format{A data.frame with 24 rows and 3 variables.} +\source{ +Maxwell, S. E., & Delaney, H. D. (2004). Designing experiments and analyzing data: a model-comparisons perspective. Mahwah, N.J.: Lawrence Erlbaum Associates. p. 574 +} +\usage{ +md_16.4 +} +\description{ +Data from a hypothetical inductive reasoning study. +} +\details{ +Description from pp. 841: + +Suppose an educational psychologist has developed an intervention to teach inductive reasoning skills to school children. She decides to test the efficacy of her intervention by conducting a randomized design. Three classrooms of students are randomly assigned to the treatment condition, and 3 other classrooms are assigned to the control. + +Table 16.4 shows hypothetical data collected from 29 children who participated in the study assessing the effectiveness of the intervention to increase inductive reasoning skills. We want to call your attention to several aspects of the data. First, the 15 children with condition values of 0 received the control, whereas the 14 children with condition values of 1 received the treatment. Second, 4 of the children in the control condition were students in control Classroom 1, 6 of them were students in control Classroom 2, and 5 were students in control Classroom 3. Along similar lines, 3 of the children in the treatment condition were students in treatment Classroom 1, 5 were students in treatment Classroom 2, and 6 were students in treatment Classroom 3. It is essential to understand that there are a total of six classrooms here; we have coded classroom from 1 to 3 for control as well as treatment, because we will indicate to PROC MIXED that classroom is nested under treatment. Third, scores on the dependent variable appear in the rightmost column under the variable label "induct." + +Note that it would make a lot more sense to change the labeling of room from 1 to 3 nested within cond to 1 to 6. However, I keep this in line with the original. The random effects term in the call to mixed is therefore a little bit uncommon.#' +} +\examples{ +# 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) +# p-values (almost) hold: +(mixed2 <- mixed(induct ~ cond + (1|room:cond), md_16.4)) +# (1|room:cond) is needed because room is nested within cond. +} +\keyword{dataset} + diff --git a/man/mixed.Rd b/man/mixed.Rd index 733cec7..a42d06d 100644 --- a/man/mixed.Rd +++ b/man/mixed.Rd @@ -1,333 +1,333 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/mixed.R -\encoding{UTF-8} -\name{mixed} -\alias{mixed} -\title{p-values for fixed effects of mixed-model via lme4::lmer()} -\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"), set.data.arg = TRUE, - progress = TRUE, cl = NULL, ...) -} -\arguments{ -\item{formula}{a formula describing the full mixed-model to be fitted. As this formula is passed to \code{lmer}, it needs at least one random term.} - -\item{data}{data.frame containing the data. Should have all the variables present in \code{fixed}, \code{random}, and \code{dv} as columns.} - -\item{type}{type of test on which effects are based. Default is to use type 3 tests, taken from \code{\link{afex_options}}.} - -\item{method}{character vector indicating which methods for obtaining p-values should be used: \code{"KR"} corresponds to the Kenward-Roger approximation for degrees of freedom (only working with linear mixed models), \code{"PB"} calculates p-values based on parametric bootstrap, \code{"LRT"} calculates p-values via the likelihood ratio tests implemented in the \code{anova} method for \code{merMod} objects (only recommended for models with many [i.e., > 50] levels for the random factors). The default (currently \code{"KR"}) is taken from \code{\link{afex_options}}.} - -\item{per.parameter}{\code{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. Relatively untested so results should be compared with a second run without setting this argument. Uses \code{\link{grep}} for selecting parameters among the fixed effects so regular expressions (\code{\link{regex}}) are possible. See Examples.} - -\item{args.test}{\code{list} of arguments passed to the function calculating the p-values. See Details.} - -\item{test.intercept}{logical. Whether or not the intercept should also be fitted and tested for significance. Default is \code{FALSE}. Only relevant if \code{type = 3}.} - -\item{check.contrasts}{\code{logical}. Should contrasts be checked and (if necessary) changed to \code{"contr.sum"}? See Details. The default (\code{"TRUE"}) is taken from \code{\link{afex_options}}.} - -\item{set.data.arg}{\code{logical}. Should the data argument in the slot \code{call} of the \code{merMod} object returned from \code{lmer} be set to the passed data argument? Otherwise the name will be \code{data}. Helpful if fitted objects are used afterwards (e.g., using \pkg{lsmeans}). Default is \code{TRUE}.} - -\item{progress}{if \code{TRUE}, shows progress with a text progress bar and other status messages during fitting.} - -\item{cl}{A vector identifying a cluster; used for distributing the estimation of the different models using several cores. See examples. If \code{ckeck.contrasts}, mixed sets the current contrasts (\code{getOption("contrasts")}) at the nodes. Note this does \emph{not} distribute calculation of p-values (e.g., when using \code{method = "PB"}) across the cluster. Use \code{args.test} for this.} - -\item{...}{further arguments (such as \code{weights}) passed to \code{\link{lmer}}.} -} -\value{ -An object of class \code{"mixed"} (i.e., a list) with the following elements: - -\enumerate{ -\item \code{anova_table} a data.frame containing the statistics returned from \code{\link[pbkrtest]{KRmodcomp}}. The \code{stat} column in this data.frame gives the value of the test statistic, an F-value for \code{method = "KR"} and a chi-square value for the other two methods. -\item \code{full.model} the \code{"lmerMod"} object returned from fitting the full mixed model. -\item \code{restricted.models} a list of \code{"lmerMod"} objects from fitting the restricted models (i.e., each model lacks the corresponding effect) -\item \code{tests} a list of objects returned by the function for obtaining the p-values. -\item \code{type} The \code{type} argument used when calling this function. -\item \code{method} The \code{method} argument used when calling this function. -} - -Two similar methods exist for objects of class \code{"mixed"}: \code{print} and \code{anova}. They print a nice version of the \code{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: -\enumerate{ -\item \code{Effect} name of effect -\item \code{p.value} estimated p-value for the effect -} - -For LMMs with \code{method="KR"} 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 \url{http://stackoverflow.com/a/25612960/289572}): -\enumerate{ -\item \code{F} computed F statistic -\item \code{ndf} numerator degrees of freedom (number of parameters used for the effect) -\item \code{ddf} denominator degrees of freedom (effective residual degrees of freedom for testing the effect), computed from the Kenward-Roger correction using \code{pbkrtest::KRmodcomp} -\item \code{F.scaling} scaling of F-statistic computing from Kenward-Roger approximation. -} - -For models with \code{method="LRT"} the following further columns are returned: -\enumerate{ -\item \code{df.large} degrees of freedom (i.e., estimated paramaters) for full model (i.e., model containing the corresponding effect) -\item \code{df.small} degrees of freedom (i.e., estimated paramaters) for restricted model (i.e., model without the corresponding effect) -\item \code{chisq} 2 times the difference in likelihood (obtained with \code{logLik}) between full and restricted model -\item \code{df} difference in degrees of freedom between full and restricted model (p-value is based on these df). -} - -For models with \code{method="PB"} the following further column is returned: -\enumerate{ -\item \code{stat} 2 times the difference in likelihood (obtained with \code{logLik}) between full and restricted model (i.e., a chi-square value). -} - -The \code{summary} method for objects of class \code{mixed} simply calls \code{\link{summary.merMod}} on the full model. -} -\description{ -Calculates p-values for all fixed effects in a mixed model. This is done by first fitting (with \code{\link[lme4]{lmer}}) the full model and then versions thereof in which a single effect is removed and comparing the reduced model to the full model. The default behavior is to calculate type 3 like p-values using the Kenward-Roger approximation for degrees-of-freedom implemented using \code{\link[pbkrtest]{KRmodcomp}} (available for LMMs only). Other methods for obtaining p-values are parametric bootstrap (\code{method = "PB"}) or likelihood ratio tests (\code{method = "LRT"}), both of which are available for both LMMs and GLMMs. \code{print}, \code{summary}, and \code{anova} methods for the returned object of class \code{"mixed"} are available (the last two return the same data.frame). -} -\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). - -p-values are per default calculated via methods from \pkg{pbkrtest}. When \code{method = "KR"} (the default), the Kenward-Roger approximation for degrees-of-freedom is calculated using \code{\link[pbkrtest]{KRmodcomp}}, which is only applicable to linear-mixed models. The test statistic in the output is a F-value (\code{F}). - -\code{method = "PB"} calculates p-values using parametric bootstrap using \code{\link[pbkrtest]{PBmodcomp}}. This can be used for linear and also generalized linear mixed models (GLMM) by specifying a \code{\link[stats]{family}} argument to \code{mixed}. Note that you should specify further arguments to \code{PBmodcomp} via \code{args.test}, especially \code{nsim} (the number of simulations to form the reference distribution) or \code{cl} (for using multiple cores). For other arguments see \code{\link[pbkrtest]{PBmodcomp}}. Note that \code{REML} (argument to \code{[g]lmer}) will be set to \code{FALSE} if method is \code{PB}. - -\code{method = "LRT"} calculates p-values via likelihood ratio tests implemented in the \code{anova} method for \code{"merMod"} objects. This is 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 \href{http://glmm.wikidot.com/faq}{lme4 faq} also recommends the other methods over likelihood ratio tests. - -Type 3 tests are obtained by comparing a model in which only the tested effect is excluded with the full model (containing all effects). This corresponds to the (type 3) Wald tests given by \code{car::Anova} for \code{"lmerMod"} models. The submodels in which the tested effect is excluded are obtained by manually creating a model matrix which si then fitted in \code{"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 \href{https://stat.ethz.ch/pipermail/r-sig-mixed-models/2012q3/018992.html}{I didn't find a better way} of implementing the Type 2 tests). This \strong{does not} correspond to the (type 2) Wald test reported by \code{car::Anova}. If you want type 2 Wald tests instead of truly sequential typde 2 tests, use \code{car::Anova} with \code{test = "F"}. Note that the order in which the effects are entered into the formula does not matter (in contrast to type 1 tests). - - -If \code{check.contrasts = TRUE}, contrasts will be set to \code{"contr.sum"} for all factors in the formula if default contrasts are not equal to \code{"contr.sum"} or \code{attrib(factor, "contrasts") != "contr.sum"}. Furthermore, the current contrasts (obtained via \code{getOption("contrasts")}) will be set at the cluster nodes if \code{cl} is not \code{NULL}. -} -\note{ -When \code{method = "KR"}, obtaining p-values is known to crash due too insufficient memory or other computational limitations (especially with complex random effects structures). In these cases, the other methods should be used. The RAM demand is a problem especially on 32 bit Windows which only supports up to 2 or 3GB RAM (see \href{http://cran.r-project.org/bin/windows/base/rw-FAQ.html}{R Windows FAQ}). Then it is probably a good idea to use methods "LRT" or "PB". - -\code{"mixed"} will throw a message if numerical variables are not centered on 0, as main effects (of other variables then the numeric one) can be hard to interpret if numerical variables appear in interactions. See Dalal & Zickar (2012). - -Please report bugs or unexpected behavior to maintainer via email! -} -\examples{ - -########################### -## Full Analysis Example ## -########################### - -\dontrun{ -### 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 random slopes for participant random effect -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 - - -## 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(disable.pbkrtest = TRUE) -(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. -} - -################################################### -## Replicating Maxwell & Delaney (2004) Examples ## -################################################### - -### replicate results from Table 15.4 (Maxwell & Delaney, 2004, p. 789) -data(md_15.1) -# random intercept plus 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 ## -#################### - -\dontrun{ - -# 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 -## Effect stat ndf ddf F.scaling p.value -## 1 Correct 8.15 1 1627.73 1.00 .004 -## 2 Trial 7.57 1 1592.43 1.00 .006 -## 3 PrevType 0.17 1 1605.39 1.00 .68 -## 4 meanWeight 14.85 1 75.39 1.00 .0002 -## 5 Frequency 56.53 1 76.08 1.00 <.0001 -## 6 NativeLanguage 0.70 1 27.11 1.00 .41 -## 7 Length 8.70 1 75.83 1.00 .004 -## 8 PrevType:meanWeight 6.18 1 1601.18 1.00 .01 -## 9 NativeLanguage:Length 14.24 1 1555.49 1.00 .0002 - -# 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)) - -####################### -### 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) - -stopCluster(cl) - -} -} -\author{ -Henrik Singmann with contributions from \href{http://stackoverflow.com/q/11335923/289572}{Ben Bolker and Joshua Wiley}. -} -\references{ -Baayen, R. H. (2008). \emph{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. \emph{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. \emph{International Journal of Psychological Research}, 3(2), 12-28. - -Barr, D. J. (2013). Random effects structure for testing interactions in linear mixed-effects models. \emph{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. \emph{Journal of Memory and Language}, 68(3), 255-278. doi:10.1016/j.jml.2012.11.001 - -Dalal, D. K., & Zickar, M. J. (2012). Some Common Myths About Centering Predictor Variables in Moderated Multiple Regression and Polynomial Regression. \emph{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. \emph{Journal of Personality and Social Psychology}, 103(1), 54-69. doi:10.1037/a0028347 - -Maxwell, S. E., & Delaney, H. D. (2004). \emph{Designing experiments and analyzing data: a model-comparisons perspective.} Mahwah, N.J.: Lawrence Erlbaum Associates. -} -\seealso{ -\code{\link{aov_ez}} and \code{\link{aov_car}} for convenience functions to analyze experimental deisgns with classical ANOVA or ANCOVA wrapping \code{\link[car]{Anova}}. - -see the following for the data sets from Maxwell and Delaney (2004) used and more examples: \code{\link{md_15.1}}, \code{\link{md_16.1}}, and \code{\link{md_16.4}}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/mixed.R +\encoding{UTF-8} +\name{mixed} +\alias{mixed} +\title{p-values for fixed effects of mixed-model via lme4::lmer()} +\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"), set.data.arg = TRUE, + progress = TRUE, cl = NULL, ...) +} +\arguments{ +\item{formula}{a formula describing the full mixed-model to be fitted. As this formula is passed to \code{lmer}, it needs at least one random term.} + +\item{data}{data.frame containing the data. Should have all the variables present in \code{fixed}, \code{random}, and \code{dv} as columns.} + +\item{type}{type of test on which effects are based. Default is to use type 3 tests, taken from \code{\link{afex_options}}.} + +\item{method}{character vector indicating which methods for obtaining p-values should be used: \code{"KR"} corresponds to the Kenward-Roger approximation for degrees of freedom (only working with linear mixed models), \code{"PB"} calculates p-values based on parametric bootstrap, \code{"LRT"} calculates p-values via the likelihood ratio tests implemented in the \code{anova} method for \code{merMod} objects (only recommended for models with many [i.e., > 50] levels for the random factors). The default (currently \code{"KR"}) is taken from \code{\link{afex_options}}.} + +\item{per.parameter}{\code{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. Relatively untested so results should be compared with a second run without setting this argument. Uses \code{\link{grep}} for selecting parameters among the fixed effects so regular expressions (\code{\link{regex}}) are possible. See Examples.} + +\item{args.test}{\code{list} of arguments passed to the function calculating the p-values. See Details.} + +\item{test.intercept}{logical. Whether or not the intercept should also be fitted and tested for significance. Default is \code{FALSE}. Only relevant if \code{type = 3}.} + +\item{check.contrasts}{\code{logical}. Should contrasts be checked and (if necessary) changed to \code{"contr.sum"}? See Details. The default (\code{"TRUE"}) is taken from \code{\link{afex_options}}.} + +\item{set.data.arg}{\code{logical}. Should the data argument in the slot \code{call} of the \code{merMod} object returned from \code{lmer} be set to the passed data argument? Otherwise the name will be \code{data}. Helpful if fitted objects are used afterwards (e.g., using \pkg{lsmeans}). Default is \code{TRUE}.} + +\item{progress}{if \code{TRUE}, shows progress with a text progress bar and other status messages during fitting.} + +\item{cl}{A vector identifying a cluster; used for distributing the estimation of the different models using several cores. See examples. If \code{ckeck.contrasts}, mixed sets the current contrasts (\code{getOption("contrasts")}) at the nodes. Note this does \emph{not} distribute calculation of p-values (e.g., when using \code{method = "PB"}) across the cluster. Use \code{args.test} for this.} + +\item{...}{further arguments (such as \code{weights}) passed to \code{\link{lmer}}.} +} +\value{ +An object of class \code{"mixed"} (i.e., a list) with the following elements: + +\enumerate{ +\item \code{anova_table} a data.frame containing the statistics returned from \code{\link[pbkrtest]{KRmodcomp}}. The \code{stat} column in this data.frame gives the value of the test statistic, an F-value for \code{method = "KR"} and a chi-square value for the other two methods. +\item \code{full.model} the \code{"lmerMod"} object returned from fitting the full mixed model. +\item \code{restricted.models} a list of \code{"lmerMod"} objects from fitting the restricted models (i.e., each model lacks the corresponding effect) +\item \code{tests} a list of objects returned by the function for obtaining the p-values. +\item \code{type} The \code{type} argument used when calling this function. +\item \code{method} The \code{method} argument used when calling this function. +} + +Two similar methods exist for objects of class \code{"mixed"}: \code{print} and \code{anova}. They print a nice version of the \code{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: +\enumerate{ +\item \code{Effect} name of effect +\item \code{p.value} estimated p-value for the effect +} + +For LMMs with \code{method="KR"} 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 \url{http://stackoverflow.com/a/25612960/289572}): +\enumerate{ +\item \code{F} computed F statistic +\item \code{ndf} numerator degrees of freedom (number of parameters used for the effect) +\item \code{ddf} denominator degrees of freedom (effective residual degrees of freedom for testing the effect), computed from the Kenward-Roger correction using \code{pbkrtest::KRmodcomp} +\item \code{F.scaling} scaling of F-statistic computing from Kenward-Roger approximation. +} + +For models with \code{method="LRT"} the following further columns are returned: +\enumerate{ +\item \code{df.large} degrees of freedom (i.e., estimated paramaters) for full model (i.e., model containing the corresponding effect) +\item \code{df.small} degrees of freedom (i.e., estimated paramaters) for restricted model (i.e., model without the corresponding effect) +\item \code{chisq} 2 times the difference in likelihood (obtained with \code{logLik}) between full and restricted model +\item \code{df} difference in degrees of freedom between full and restricted model (p-value is based on these df). +} + +For models with \code{method="PB"} the following further column is returned: +\enumerate{ +\item \code{stat} 2 times the difference in likelihood (obtained with \code{logLik}) between full and restricted model (i.e., a chi-square value). +} + +The \code{summary} method for objects of class \code{mixed} simply calls \code{\link{summary.merMod}} on the full model. +} +\description{ +Calculates p-values for all fixed effects in a mixed model. This is done by first fitting (with \code{\link[lme4]{lmer}}) the full model and then versions thereof in which a single effect is removed and comparing the reduced model to the full model. The default behavior is to calculate type 3 like p-values using the Kenward-Roger approximation for degrees-of-freedom implemented using \code{\link[pbkrtest]{KRmodcomp}} (available for LMMs only). Other methods for obtaining p-values are parametric bootstrap (\code{method = "PB"}) or likelihood ratio tests (\code{method = "LRT"}), both of which are available for both LMMs and GLMMs. \code{print}, \code{summary}, and \code{anova} methods for the returned object of class \code{"mixed"} are available (the last two return the same data.frame). +} +\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). + +p-values are per default calculated via methods from \pkg{pbkrtest}. When \code{method = "KR"} (the default), the Kenward-Roger approximation for degrees-of-freedom is calculated using \code{\link[pbkrtest]{KRmodcomp}}, which is only applicable to linear-mixed models. The test statistic in the output is a F-value (\code{F}). + +\code{method = "PB"} calculates p-values using parametric bootstrap using \code{\link[pbkrtest]{PBmodcomp}}. This can be used for linear and also generalized linear mixed models (GLMM) by specifying a \code{\link[stats]{family}} argument to \code{mixed}. Note that you should specify further arguments to \code{PBmodcomp} via \code{args.test}, especially \code{nsim} (the number of simulations to form the reference distribution) or \code{cl} (for using multiple cores). For other arguments see \code{\link[pbkrtest]{PBmodcomp}}. Note that \code{REML} (argument to \code{[g]lmer}) will be set to \code{FALSE} if method is \code{PB}. + +\code{method = "LRT"} calculates p-values via likelihood ratio tests implemented in the \code{anova} method for \code{"merMod"} objects. This is 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 \href{http://glmm.wikidot.com/faq}{lme4 faq} also recommends the other methods over likelihood ratio tests. + +Type 3 tests are obtained by comparing a model in which only the tested effect is excluded with the full model (containing all effects). This corresponds to the (type 3) Wald tests given by \code{car::Anova} for \code{"lmerMod"} models. The submodels in which the tested effect is excluded are obtained by manually creating a model matrix which si then fitted in \code{"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 \href{https://stat.ethz.ch/pipermail/r-sig-mixed-models/2012q3/018992.html}{I didn't find a better way} of implementing the Type 2 tests). This \strong{does not} correspond to the (type 2) Wald test reported by \code{car::Anova}. If you want type 2 Wald tests instead of truly sequential typde 2 tests, use \code{car::Anova} with \code{test = "F"}. Note that the order in which the effects are entered into the formula does not matter (in contrast to type 1 tests). + + +If \code{check.contrasts = TRUE}, contrasts will be set to \code{"contr.sum"} for all factors in the formula if default contrasts are not equal to \code{"contr.sum"} or \code{attrib(factor, "contrasts") != "contr.sum"}. Furthermore, the current contrasts (obtained via \code{getOption("contrasts")}) will be set at the cluster nodes if \code{cl} is not \code{NULL}. +} +\note{ +When \code{method = "KR"}, obtaining p-values is known to crash due too insufficient memory or other computational limitations (especially with complex random effects structures). In these cases, the other methods should be used. The RAM demand is a problem especially on 32 bit Windows which only supports up to 2 or 3GB RAM (see \href{http://cran.r-project.org/bin/windows/base/rw-FAQ.html}{R Windows FAQ}). Then it is probably a good idea to use methods "LRT" or "PB". + +\code{"mixed"} will throw a message if numerical variables are not centered on 0, as main effects (of other variables then the numeric one) can be hard to interpret if numerical variables appear in interactions. See Dalal & Zickar (2012). + +Please report bugs or unexpected behavior to maintainer via email! +} +\examples{ + +########################### +## Full Analysis Example ## +########################### + +\dontrun{ +### 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 random slopes for participant random effect +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 + + +## 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(disable.pbkrtest = TRUE) +(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. +} + +################################################### +## Replicating Maxwell & Delaney (2004) Examples ## +################################################### + +### replicate results from Table 15.4 (Maxwell & Delaney, 2004, p. 789) +data(md_15.1) +# random intercept plus 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 ## +#################### + +\dontrun{ + +# 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 +## Effect stat ndf ddf F.scaling p.value +## 1 Correct 8.15 1 1627.73 1.00 .004 +## 2 Trial 7.57 1 1592.43 1.00 .006 +## 3 PrevType 0.17 1 1605.39 1.00 .68 +## 4 meanWeight 14.85 1 75.39 1.00 .0002 +## 5 Frequency 56.53 1 76.08 1.00 <.0001 +## 6 NativeLanguage 0.70 1 27.11 1.00 .41 +## 7 Length 8.70 1 75.83 1.00 .004 +## 8 PrevType:meanWeight 6.18 1 1601.18 1.00 .01 +## 9 NativeLanguage:Length 14.24 1 1555.49 1.00 .0002 + +# 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)) + +####################### +### 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) + +stopCluster(cl) + +} +} +\author{ +Henrik Singmann with contributions from \href{http://stackoverflow.com/q/11335923/289572}{Ben Bolker and Joshua Wiley}. +} +\references{ +Baayen, R. H. (2008). \emph{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. \emph{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. \emph{International Journal of Psychological Research}, 3(2), 12-28. + +Barr, D. J. (2013). Random effects structure for testing interactions in linear mixed-effects models. \emph{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. \emph{Journal of Memory and Language}, 68(3), 255-278. doi:10.1016/j.jml.2012.11.001 + +Dalal, D. K., & Zickar, M. J. (2012). Some Common Myths About Centering Predictor Variables in Moderated Multiple Regression and Polynomial Regression. \emph{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. \emph{Journal of Personality and Social Psychology}, 103(1), 54-69. doi:10.1037/a0028347 + +Maxwell, S. E., & Delaney, H. D. (2004). \emph{Designing experiments and analyzing data: a model-comparisons perspective.} Mahwah, N.J.: Lawrence Erlbaum Associates. +} +\seealso{ +\code{\link{aov_ez}} and \code{\link{aov_car}} for convenience functions to analyze experimental deisgns with classical ANOVA or ANCOVA wrapping \code{\link[car]{Anova}}. + +see the following for the data sets from Maxwell and Delaney (2004) used and more examples: \code{\link{md_15.1}}, \code{\link{md_16.1}}, and \code{\link{md_16.4}}. +} + diff --git a/man/nice.Rd b/man/nice.Rd index 99a4483..f765cf0 100644 --- a/man/nice.Rd +++ b/man/nice.Rd @@ -1,97 +1,97 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/nice.R -\encoding{UTF-8} -\name{nice} -\alias{nice} -\alias{nice.afex_aov} -\alias{nice.anova} -\alias{nice.mixed} -\title{Make nice ANOVA table for printing.} -\usage{ -nice(object, ...) - -\method{nice}{afex_aov}(object, es = afex_options("es_aov"), - observed = NULL, correction = afex_options("correction_aov"), - MSE = TRUE, intercept = FALSE, sig.symbols = c(" +", " *", " **", - " ***"), ...) - -\method{nice}{anova}(object, MSE = TRUE, intercept = FALSE, - sig.symbols = c(" +", " *", " **", " ***"), ...) - -\method{nice}{mixed}(object, sig.symbols = c(" +", " *", " **", " ***"), ...) -} -\arguments{ -\item{object}{An object of class \code{"Anova.mlm"} or \code{"anova"} as returned from \code{\link[car]{Anova}} or the \pkg{afex} ANOVA functions (see \code{\link{aov_car}}).} - -\item{...}{currently ignored.} - -\item{es}{Effect Size to be reported. The default is given by \code{afex_options("es_aov")}, which is initially set to \code{"ges"} (i.e., reporting generalized eta-squared, see details). Also supported is partial eta-squared (\code{"pes"}) or \code{"none"}.} - -\item{observed}{character vector referring to the observed (i.e., non manipulated) variables/effects in the design. Important for calculation of generalized eta-squared (ignored if \code{es} is not \code{"ges"}), see details.} - -\item{correction}{Character. Which sphericity correction of the degrees of freedom should be reported for the within-subject factors. The default is given by \code{afex_options("correction_aov")}, which is initially set to \code{"GG"} corresponding to the Greenhouse-Geisser correction. Possible values are \code{"GG"}, \code{"HF"} (i.e., Hyunh-Feldt correction), and \code{"none"} (i.e., no correction).} - -\item{MSE}{logical. Should the column containing the Mean Sqaured Error (MSE) be displayed? Default is \code{TRUE}.} - -\item{intercept}{logical. Should intercept (if present) be included in the ANOVA table? Default is \code{FALSE} which hides the intercept.} - -\item{sig.symbols}{Character. What should be the symbols designating significance? When entering an vector with \code{length(sig.symbol) < 4} only those elements of the default (\code{c(" +", " *", " **", " ***")}) will be replaced. \code{sig.symbols = ""} will display the stars but not the \code{+}, \code{sig.symbols = rep("", 4)} will display no symbols.} -} -\value{ -A \code{data.frame} with the ANOVA table consisting of characters. The columns that are always present are: \code{Effect}, \code{df} (degrees of freedom), \code{F}, and \code{p}. - -\code{ges} contains the generalized eta-squared effect size measure (Bakeman, 2005), \code{pes} contains partial eta-squared (if requested). -} -\description{ -This generic function produces a nice ANOVA table for printin for objects of class. \code{nice_anova} takes an object from \code{\link[car]{Anova}} possible created by the convenience functions \code{\link{aov_ez}} or \code{\link{aov_car}}. When within-subject factors are present, either sphericity corrected or uncorrected degrees of freedom can be reported. -} -\details{ -The returned \code{data.frame} is print-ready when adding to a document with proper methods. I recommend \pkg{ascii} and \pkg{xtable}. \pkg{ascii} provides conversion to \href{http://www.methods.co.nz/asciidoc/}{AsciiDoc} but most notably to \href{http://orgmode.org/}{org-mode} (see \code{\link[ascii]{ascii}} and \code{\link[ascii]{print-ascii}}). \pkg{xtable} converts a \code{data.frame} into LaTeX code with many possible options (e.g., allowing for \code{"longtable"} or \code{"sidewaystable"}), see \code{\link[xtable]{xtable}} and \code{\link[xtable]{print.xtable}}. See Examples. - -Conversion functions to other formats (such as HTML, ODF, or Word) can be found at the \href{http://cran.r-project.org/web/views/ReproducibleResearch.html}{Reproducible Research Task View}. - -The default reports generalized eta squared (Olejnik & Algina, 2003), the "recommended effect size for repeated measured designs" (Bakeman, 2005). Note that it is important that all measured variables (as opposed to experimentally manipulated variables), such as e.g., age, gender, weight, ..., must be declared via \code{observed} to obtain the correct effect size estimate. Partial eta squared (\code{"pes"}) does not require this. -} -\examples{ -## example from Olejnik & Algina (2003) -# "Repeated Measures Design" (pp. 439): -data(md_12.1) -# create object of class afex_aov: -rmd <- aov_ez("id", "rt", md_12.1, within = c("angle", "noise")) -# use different es: -nice(rmd, es = "pes") # noise: .82 -nice(rmd, es = "ges") # noise: .39 - -# exampel using obk.long (see ?obk.long), a long version of the OBrienKaiser dataset from car. -data(obk.long) -# create object of class afex_aov: -tmp.aov <- aov_car(value ~ treatment * gender + Error(id/phase*hour), data = obk.long) - -nice(tmp.aov, observed = "gender") - -nice(tmp.aov, observed = "gender", sig.symbol = rep("", 4)) - -\dontrun{ -# use package ascii or xtable for formatting of tables ready for printing. - -full <- nice(tmp.aov, observed = "gender") - -require(ascii) -print(ascii(full, include.rownames = FALSE, caption = "ANOVA 1"), type = "org") - -require(xtable) -print.xtable(xtable(full, caption = "ANOVA 2"), include.rownames = FALSE) -} -} -\author{ -The code for calculating generalized eta-squared was written by Mike Lawrence.\cr Everything else was written by Henrik Singmann. -} -\references{ -Bakeman, R. (2005). Recommended effect size statistics for repeated measures designs. \emph{Behavior Research Methods}, 37(3), 379-384. doi:10.3758/BF03192707 - -Olejnik, S., & Algina, J. (2003). Generalized Eta and Omega Squared Statistics: Measures of Effect Size for Some Common Research Designs. \emph{Psychological Methods}, 8(4), 434-447. doi:10.1037/1082-989X.8.4.434 -} -\seealso{ -\code{\link{aov_ez}} and \code{\link{aov_car}} are the convenience functions to create the object appropriate for \code{nice_anova}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/nice.R +\encoding{UTF-8} +\name{nice} +\alias{nice} +\alias{nice.afex_aov} +\alias{nice.anova} +\alias{nice.mixed} +\title{Make nice ANOVA table for printing.} +\usage{ +nice(object, ...) + +\method{nice}{afex_aov}(object, es = afex_options("es_aov"), + observed = NULL, correction = afex_options("correction_aov"), + MSE = TRUE, intercept = FALSE, sig.symbols = c(" +", " *", " **", + " ***"), ...) + +\method{nice}{anova}(object, MSE = TRUE, intercept = FALSE, + sig.symbols = c(" +", " *", " **", " ***"), ...) + +\method{nice}{mixed}(object, sig.symbols = c(" +", " *", " **", " ***"), ...) +} +\arguments{ +\item{object}{An object of class \code{"Anova.mlm"} or \code{"anova"} as returned from \code{\link[car]{Anova}} or the \pkg{afex} ANOVA functions (see \code{\link{aov_car}}).} + +\item{...}{currently ignored.} + +\item{es}{Effect Size to be reported. The default is given by \code{afex_options("es_aov")}, which is initially set to \code{"ges"} (i.e., reporting generalized eta-squared, see details). Also supported is partial eta-squared (\code{"pes"}) or \code{"none"}.} + +\item{observed}{character vector referring to the observed (i.e., non manipulated) variables/effects in the design. Important for calculation of generalized eta-squared (ignored if \code{es} is not \code{"ges"}), see details.} + +\item{correction}{Character. Which sphericity correction of the degrees of freedom should be reported for the within-subject factors. The default is given by \code{afex_options("correction_aov")}, which is initially set to \code{"GG"} corresponding to the Greenhouse-Geisser correction. Possible values are \code{"GG"}, \code{"HF"} (i.e., Hyunh-Feldt correction), and \code{"none"} (i.e., no correction).} + +\item{MSE}{logical. Should the column containing the Mean Sqaured Error (MSE) be displayed? Default is \code{TRUE}.} + +\item{intercept}{logical. Should intercept (if present) be included in the ANOVA table? Default is \code{FALSE} which hides the intercept.} + +\item{sig.symbols}{Character. What should be the symbols designating significance? When entering an vector with \code{length(sig.symbol) < 4} only those elements of the default (\code{c(" +", " *", " **", " ***")}) will be replaced. \code{sig.symbols = ""} will display the stars but not the \code{+}, \code{sig.symbols = rep("", 4)} will display no symbols.} +} +\value{ +A \code{data.frame} with the ANOVA table consisting of characters. The columns that are always present are: \code{Effect}, \code{df} (degrees of freedom), \code{F}, and \code{p}. + +\code{ges} contains the generalized eta-squared effect size measure (Bakeman, 2005), \code{pes} contains partial eta-squared (if requested). +} +\description{ +This generic function produces a nice ANOVA table for printin for objects of class. \code{nice_anova} takes an object from \code{\link[car]{Anova}} possible created by the convenience functions \code{\link{aov_ez}} or \code{\link{aov_car}}. When within-subject factors are present, either sphericity corrected or uncorrected degrees of freedom can be reported. +} +\details{ +The returned \code{data.frame} is print-ready when adding to a document with proper methods. I recommend \pkg{ascii} and \pkg{xtable}. \pkg{ascii} provides conversion to \href{http://www.methods.co.nz/asciidoc/}{AsciiDoc} but most notably to \href{http://orgmode.org/}{org-mode} (see \code{\link[ascii]{ascii}} and \code{\link[ascii]{print-ascii}}). \pkg{xtable} converts a \code{data.frame} into LaTeX code with many possible options (e.g., allowing for \code{"longtable"} or \code{"sidewaystable"}), see \code{\link[xtable]{xtable}} and \code{\link[xtable]{print.xtable}}. See Examples. + +Conversion functions to other formats (such as HTML, ODF, or Word) can be found at the \href{http://cran.r-project.org/web/views/ReproducibleResearch.html}{Reproducible Research Task View}. + +The default reports generalized eta squared (Olejnik & Algina, 2003), the "recommended effect size for repeated measured designs" (Bakeman, 2005). Note that it is important that all measured variables (as opposed to experimentally manipulated variables), such as e.g., age, gender, weight, ..., must be declared via \code{observed} to obtain the correct effect size estimate. Partial eta squared (\code{"pes"}) does not require this. +} +\examples{ +## example from Olejnik & Algina (2003) +# "Repeated Measures Design" (pp. 439): +data(md_12.1) +# create object of class afex_aov: +rmd <- aov_ez("id", "rt", md_12.1, within = c("angle", "noise")) +# use different es: +nice(rmd, es = "pes") # noise: .82 +nice(rmd, es = "ges") # noise: .39 + +# exampel using obk.long (see ?obk.long), a long version of the OBrienKaiser dataset from car. +data(obk.long) +# create object of class afex_aov: +tmp.aov <- aov_car(value ~ treatment * gender + Error(id/phase*hour), data = obk.long) + +nice(tmp.aov, observed = "gender") + +nice(tmp.aov, observed = "gender", sig.symbol = rep("", 4)) + +\dontrun{ +# use package ascii or xtable for formatting of tables ready for printing. + +full <- nice(tmp.aov, observed = "gender") + +require(ascii) +print(ascii(full, include.rownames = FALSE, caption = "ANOVA 1"), type = "org") + +require(xtable) +print.xtable(xtable(full, caption = "ANOVA 2"), include.rownames = FALSE) +} +} +\author{ +The code for calculating generalized eta-squared was written by Mike Lawrence.\cr Everything else was written by Henrik Singmann. +} +\references{ +Bakeman, R. (2005). Recommended effect size statistics for repeated measures designs. \emph{Behavior Research Methods}, 37(3), 379-384. doi:10.3758/BF03192707 + +Olejnik, S., & Algina, J. (2003). Generalized Eta and Omega Squared Statistics: Measures of Effect Size for Some Common Research Designs. \emph{Psychological Methods}, 8(4), 434-447. doi:10.1037/1082-989X.8.4.434 +} +\seealso{ +\code{\link{aov_ez}} and \code{\link{aov_car}} are the convenience functions to create the object appropriate for \code{nice_anova}. +} + diff --git a/man/obk.long.Rd b/man/obk.long.Rd index 4251424..19478be 100644 --- a/man/obk.long.Rd +++ b/man/obk.long.Rd @@ -1,52 +1,52 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/obk.long-data.R -\docType{data} -\encoding{UTF-8} -\name{obk.long} -\alias{obk.long} -\title{O'Brien Kaiser's Repeated-Measures Dataset with Covariate} -\format{A data frame with 240 rows and 7 variables.} -\source{ -O'Brien, R. G., & Kaiser, M. K. (1985). MANOVA method for analyzing repeated measures designs: An extensive primer. \emph{Psychological Bulletin}, 97, 316-333. doi:10.1037/0033-2909.97.2.316 -} -\usage{ -obk.long -} -\description{ -This is the long version of the \code{OBrienKaiser} dataset from the \pkg{car} pakage adding a random covariate \code{age}. Originally the dataset ist taken from O'Brien and Kaiser (1985). The description from \code{\link[car]{OBrienKaiser}} says: "These contrived repeated-measures data are taken from O'Brien and Kaiser (1985). The data are from an imaginary study in which 16 female and male subjects, who are divided into three treatments, are measured at a pretest, postest, and a follow-up session; during each session, they are measured at five occasions at intervals of one hour. The design, therefore, has two between-subject and two within-subject factors." -} -\examples{ -# The dataset is constructed as follows: -data("OBrienKaiser", package = "car") -set.seed(1) -OBrienKaiser2 <- within(OBrienKaiser, { - id <- factor(1:nrow(OBrienKaiser)) - age <- scale(sample(18:35, nrow(OBrienKaiser), replace = TRUE), scale = FALSE)}) -attributes(OBrienKaiser2$age) <- NULL # needed or resahpe2::melt throws an error. -OBrienKaiser2$age <- as.numeric(OBrienKaiser2$age) -obk.long <- reshape2::melt(OBrienKaiser2, id.vars = c("id", "treatment", "gender", "age")) -obk.long[,c("phase", "hour")] <- lapply(as.data.frame(do.call(rbind, - strsplit(as.character(obk.long$variable), "\\\\."),)), factor) -obk.long <- obk.long[,c("id", "treatment", "gender", "age", "phase", "hour", "value")] -obk.long <- obk.long[order(obk.long$id),] -rownames(obk.long) <- NULL -str(obk.long) -## 'data.frame': 240 obs. of 7 variables: -## $ id : Factor w/ 16 levels "1","2","3","4",..: 1 1 1 1 1 1 1 1 1 1 ... -## $ treatment: Factor w/ 3 levels "control","A",..: 1 1 1 1 1 1 1 1 1 1 ... -## $ gender : Factor w/ 2 levels "F","M": 2 2 2 2 2 2 2 2 2 2 ... -## $ age : num -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 ... -## $ phase : Factor w/ 3 levels "fup","post","pre": 3 3 3 3 3 2 2 2 2 2 ... -## $ hour : Factor w/ 5 levels "1","2","3","4",..: 1 2 3 4 5 1 2 3 4 5 ... -## $ value : num 1 2 4 2 1 3 2 5 3 2 ... -head(obk.long) -## id treatment gender age phase hour value -## 1 1 control M -4.75 pre 1 1 -## 2 1 control M -4.75 pre 2 2 -## 3 1 control M -4.75 pre 3 4 -## 4 1 control M -4.75 pre 4 2 -## 5 1 control M -4.75 pre 5 1 -## 6 1 control M -4.75 post 1 3 -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/obk.long-data.R +\docType{data} +\encoding{UTF-8} +\name{obk.long} +\alias{obk.long} +\title{O'Brien Kaiser's Repeated-Measures Dataset with Covariate} +\format{A data frame with 240 rows and 7 variables.} +\source{ +O'Brien, R. G., & Kaiser, M. K. (1985). MANOVA method for analyzing repeated measures designs: An extensive primer. \emph{Psychological Bulletin}, 97, 316-333. doi:10.1037/0033-2909.97.2.316 +} +\usage{ +obk.long +} +\description{ +This is the long version of the \code{OBrienKaiser} dataset from the \pkg{car} pakage adding a random covariate \code{age}. Originally the dataset ist taken from O'Brien and Kaiser (1985). The description from \code{\link[car]{OBrienKaiser}} says: "These contrived repeated-measures data are taken from O'Brien and Kaiser (1985). The data are from an imaginary study in which 16 female and male subjects, who are divided into three treatments, are measured at a pretest, postest, and a follow-up session; during each session, they are measured at five occasions at intervals of one hour. The design, therefore, has two between-subject and two within-subject factors." +} +\examples{ +# The dataset is constructed as follows: +data("OBrienKaiser", package = "car") +set.seed(1) +OBrienKaiser2 <- within(OBrienKaiser, { + id <- factor(1:nrow(OBrienKaiser)) + age <- scale(sample(18:35, nrow(OBrienKaiser), replace = TRUE), scale = FALSE)}) +attributes(OBrienKaiser2$age) <- NULL # needed or resahpe2::melt throws an error. +OBrienKaiser2$age <- as.numeric(OBrienKaiser2$age) +obk.long <- reshape2::melt(OBrienKaiser2, id.vars = c("id", "treatment", "gender", "age")) +obk.long[,c("phase", "hour")] <- lapply(as.data.frame(do.call(rbind, + strsplit(as.character(obk.long$variable), "\\\\."),)), factor) +obk.long <- obk.long[,c("id", "treatment", "gender", "age", "phase", "hour", "value")] +obk.long <- obk.long[order(obk.long$id),] +rownames(obk.long) <- NULL +str(obk.long) +## 'data.frame': 240 obs. of 7 variables: +## $ id : Factor w/ 16 levels "1","2","3","4",..: 1 1 1 1 1 1 1 1 1 1 ... +## $ treatment: Factor w/ 3 levels "control","A",..: 1 1 1 1 1 1 1 1 1 1 ... +## $ gender : Factor w/ 2 levels "F","M": 2 2 2 2 2 2 2 2 2 2 ... +## $ age : num -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 -4.75 ... +## $ phase : Factor w/ 3 levels "fup","post","pre": 3 3 3 3 3 2 2 2 2 2 ... +## $ hour : Factor w/ 5 levels "1","2","3","4",..: 1 2 3 4 5 1 2 3 4 5 ... +## $ value : num 1 2 4 2 1 3 2 5 3 2 ... +head(obk.long) +## id treatment gender age phase hour value +## 1 1 control M -4.75 pre 1 1 +## 2 1 control M -4.75 pre 2 2 +## 3 1 control M -4.75 pre 3 4 +## 4 1 control M -4.75 pre 4 2 +## 5 1 control M -4.75 pre 5 1 +## 6 1 control M -4.75 post 1 3 +} +\keyword{dataset} + diff --git a/man/round_ps.Rd b/man/round_ps.Rd index 82384db..38441e6 100644 --- a/man/round_ps.Rd +++ b/man/round_ps.Rd @@ -1,31 +1,31 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/round_ps.R -\encoding{UTF-8} -\name{round_ps} -\alias{round_ps} -\title{Helper function which rounds p-values} -\usage{ -round_ps(x) -} -\arguments{ -\item{x}{a numeric vector} -} -\value{ -A character vector with the same length of x. -} -\description{ -p-values are rounded in a sane way: .99 - .01 to two digits, < .01 to three digits, < .001 to four digits. -} -\examples{ -round_ps(runif(10)) - -round_ps(runif(10, 0, .01)) - -round_ps(runif(10, 0, .001)) - -round_ps(0.0000000099) -} -\author{ -Henrik Singmann -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/round_ps.R +\encoding{UTF-8} +\name{round_ps} +\alias{round_ps} +\title{Helper function which rounds p-values} +\usage{ +round_ps(x) +} +\arguments{ +\item{x}{a numeric vector} +} +\value{ +A character vector with the same length of x. +} +\description{ +p-values are rounded in a sane way: .99 - .01 to two digits, < .01 to three digits, < .001 to four digits. +} +\examples{ +round_ps(runif(10)) + +round_ps(runif(10, 0, .01)) + +round_ps(runif(10, 0, .001)) + +round_ps(0.0000000099) +} +\author{ +Henrik Singmann +} + diff --git a/man/set_sum_contrasts.Rd b/man/set_sum_contrasts.Rd index be45edb..c10e670 100644 --- a/man/set_sum_contrasts.Rd +++ b/man/set_sum_contrasts.Rd @@ -1,30 +1,30 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/set_contrasts.R -\name{set_sum_contrasts} -\alias{set_default_contrasts} -\alias{set_deviation_contrasts} -\alias{set_effects_contrasts} -\alias{set_sum_contrasts} -\alias{set_treatment_contrasts} -\title{Set global contrasts} -\usage{ -set_sum_contrasts() - -set_deviation_contrasts() - -set_effects_contrasts() - -set_default_contrasts() - -set_treatment_contrasts() -} -\value{ -nothing. These functions are called for their side effects to change the global options. -} -\description{ -These functions are simple wrappers to set contrasts globally via \code{options(contrasts = ...)}. -} -\details{ -\code{set_deviation_contrasts} and \code{set_effects_contrasts} are wrappers for \code{set_sum_contrasts}. Likewise, \code{set_default_contrasts} is a wrapper to \code{set_treatment_contrasts()}. -} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/set_contrasts.R +\name{set_sum_contrasts} +\alias{set_default_contrasts} +\alias{set_deviation_contrasts} +\alias{set_effects_contrasts} +\alias{set_sum_contrasts} +\alias{set_treatment_contrasts} +\title{Set global contrasts} +\usage{ +set_sum_contrasts() + +set_deviation_contrasts() + +set_effects_contrasts() + +set_default_contrasts() + +set_treatment_contrasts() +} +\value{ +nothing. These functions are called for their side effects to change the global options. +} +\description{ +These functions are simple wrappers to set contrasts globally via \code{options(contrasts = ...)}. +} +\details{ +\code{set_deviation_contrasts} and \code{set_effects_contrasts} are wrappers for \code{set_sum_contrasts}. Likewise, \code{set_default_contrasts} is a wrapper to \code{set_treatment_contrasts()}. +} + diff --git a/man/sk2011.1.Rd b/man/sk2011.1.Rd index bda8110..306b850 100644 --- a/man/sk2011.1.Rd +++ b/man/sk2011.1.Rd @@ -1,45 +1,45 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/sk2011.1-data.R -\docType{data} -\encoding{UTF-8} -\name{sk2011.1} -\alias{sk2011.1} -\title{Data from Singmann & Klauer (2011, Experiment 1)} -\format{A data.frame with 640 rows and 9 variables.} -\source{ -Singmann, H., & Klauer, K. C. (2011). Deductive and inductive conditional inferences: Two modes of reasoning. Thinking & Reasoning, 17(3), 247-281. doi:10.1080/13546783.2011.572718 -} -\usage{ -sk2011.1 -} -\description{ -Singmann and Klauer (2011) were interested in whether or not conditional reasoning can be explained by a single process or whether multiple processes are necessary to explain it. To provide evidence for multiple processes we aimed to establish a double dissociation of two variables: instruction type and problem type. Instruction type was manipulated between-subjects, one group of participants received deductive instructions (i.e., to treat the premises as given and only draw necessary conclusions) and a second group of participants received probabilistic instructions (i.e., to reason as in an everyday situation; we called this "inductive instruction" in the manuscript). Problem type consisted of two different orthogonally crossed variables that were manipulated within-subjects, validity of the problem (formally valid or formally invalid) and plausibility of the problem (inferences which were consisted with the background knowledge versus problems that were inconsistent with the background knowledge). The critical comparison across the two conditions was among problems which were valid and implausible with problems that were invalid and plausible. For example, the next problem was invalid and plausible: -} -\details{ -If a person is wet, then the person fell into a swimming pool. \cr -A person fell into a swimming pool. \cr -How valid is the conclusion/How likely is it that the person is wet? - -For those problems we predicted that under deductive instructions responses should be lower (as the conclusion does not necessarily follow from the premises) as under probabilistic instructions. For the valid but implausible problem, an example is presented next, we predicted the opposite pattern: - -If a person is wet, then the person fell into a swimming pool. \cr -A person is wet. \cr -How valid is the conclusion/How likely is it that the person fell into a swimming pool? - -Our study also included valid and plausible and invalid and implausible problems. - -Note that the factor `plausibility` is not present in the original manuscript, there it is a results of a combination of other factors. -} -\examples{ -data(sk2011.1) - -# Table 1 (p. 264): -aov_ez("id", "response", sk2011.1[ sk2011.1$what == "affirmation",], - within = c("inference", "type"), between = "instruction", - args.return=(es = "pes")) -aov_ez("id", "response", sk2011.1[ sk2011.1$what == "denial",], - within = c("inference", "type"), between = "instruction", - args.return=(es = "pes")) -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/sk2011.1-data.R +\docType{data} +\encoding{UTF-8} +\name{sk2011.1} +\alias{sk2011.1} +\title{Data from Singmann & Klauer (2011, Experiment 1)} +\format{A data.frame with 640 rows and 9 variables.} +\source{ +Singmann, H., & Klauer, K. C. (2011). Deductive and inductive conditional inferences: Two modes of reasoning. Thinking & Reasoning, 17(3), 247-281. doi:10.1080/13546783.2011.572718 +} +\usage{ +sk2011.1 +} +\description{ +Singmann and Klauer (2011) were interested in whether or not conditional reasoning can be explained by a single process or whether multiple processes are necessary to explain it. To provide evidence for multiple processes we aimed to establish a double dissociation of two variables: instruction type and problem type. Instruction type was manipulated between-subjects, one group of participants received deductive instructions (i.e., to treat the premises as given and only draw necessary conclusions) and a second group of participants received probabilistic instructions (i.e., to reason as in an everyday situation; we called this "inductive instruction" in the manuscript). Problem type consisted of two different orthogonally crossed variables that were manipulated within-subjects, validity of the problem (formally valid or formally invalid) and plausibility of the problem (inferences which were consisted with the background knowledge versus problems that were inconsistent with the background knowledge). The critical comparison across the two conditions was among problems which were valid and implausible with problems that were invalid and plausible. For example, the next problem was invalid and plausible: +} +\details{ +If a person is wet, then the person fell into a swimming pool. \cr +A person fell into a swimming pool. \cr +How valid is the conclusion/How likely is it that the person is wet? + +For those problems we predicted that under deductive instructions responses should be lower (as the conclusion does not necessarily follow from the premises) as under probabilistic instructions. For the valid but implausible problem, an example is presented next, we predicted the opposite pattern: + +If a person is wet, then the person fell into a swimming pool. \cr +A person is wet. \cr +How valid is the conclusion/How likely is it that the person fell into a swimming pool? + +Our study also included valid and plausible and invalid and implausible problems. + +Note that the factor `plausibility` is not present in the original manuscript, there it is a results of a combination of other factors. +} +\examples{ +data(sk2011.1) + +# Table 1 (p. 264): +aov_ez("id", "response", sk2011.1[ sk2011.1$what == "affirmation",], + within = c("inference", "type"), between = "instruction", + args.return=(es = "pes")) +aov_ez("id", "response", sk2011.1[ sk2011.1$what == "denial",], + within = c("inference", "type"), between = "instruction", + args.return=(es = "pes")) +} +\keyword{dataset} + diff --git a/man/sk2011.2.Rd b/man/sk2011.2.Rd index 37edd09..66ddc62 100644 --- a/man/sk2011.2.Rd +++ b/man/sk2011.2.Rd @@ -1,50 +1,50 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/sk2011.2-data.R -\docType{data} -\encoding{UTF-8} -\name{sk2011.2} -\alias{sk2011.2} -\title{Data from Singmann & Klauer (2011, Experiment 2)} -\format{A data.frame with 2268 rows and 9 variables.} -\source{ -Singmann, H., & Klauer, K. C. (2011). Deductive and inductive conditional inferences: Two modes of reasoning. Thinking & Reasoning, 17(3), 247-281. doi:10.1080/13546783.2011.572718 -} -\usage{ -sk2011.2 -} -\description{ -Singmann and Klauer (2011) were interested in whether or not conditional reasoning can be explained by a single process or whether multiple processes are necessary to explain it. To provide evidence for multiple processes we aimed to establish a double dissociation of two variables: instruction type and problem type. Instruction type was manipulated between-subjects, one group of participants received deductive instructions (i.e., to treat the premises as given and only draw necessary conclusions) and a second group of participants received probabilistic instructions (i.e., to reason as in an everyday situation; we called this "inductive instruction" in the manuscript). Problem type consisted of two different orthogonally crossed variables that were manipulated within-subjects, validity of the problem (formally valid or formally invalid) and type of the problem. Problem type consistent of three levels: prological problems (i.e., problems in which background knowledge suggested to accept valid but reject invalid conclusions), neutral problems (i.e., in which background knowledge suggested to reject all problems), and counterlogical problems (i.e., problems in which background knowledge suggested to reject valid but accept invalid conclusions). -} -\details{ -This data set contains 63 participants in contrast to the originally reported 56 participants. The additional participants were not included in the original studies as they did not meet the inclusion criteria (i.e., no students, prior education in logic, or participated in a similar experiment). The IDs of those additional participants are: 7, 8, 9, 12, 17, 24, 30. The excluded participant reported in the paper has ID 16. - -content has the following levels (C = content/conditional):\cr - 1 = Wenn eine Person in ein Schwimmbecken gefallen ist, dann ist sie nass.\cr - 2 = Wenn ein Hund Flöhe hat, dann kratzt er sich hin und wieder.\cr - 3 = Wenn eine Seifenblase mit einer Nadel gestochen wurde, dann platzt sie.\cr - 4 = Wenn ein Mädchen Geschlechtsverkehr vollzogen hat, dann ist es schwanger.\cr - 5 = Wenn eine Pflanze ausreichend gegossen wird, dann bleibt sie grün.\cr - 6 = Wenn sich eine Person die Zähne putzt, dann bekommt sie KEIN Karies.\cr - 7 = Wenn eine Person viel Cola trinkt, dann nimmt sie an Gewicht zu.\cr - 8 = Wenn eine Person die Klimaanlage angeschaltet hat, dann fröstelt sie.\cr - 9 = Wenn eine Person viel lernt, dann wird sie in der Klausur eine gute Note erhalten. -} -\examples{ -data("sk2011.2") - -## remove excluded participants: - -sk2_final <- droplevels(sk2011.2[!(sk2011.2$id \%in\% c(7, 8, 9, 12, 16, 17, 24, 30)),]) -str(sk2_final) - -## Table 2 (inference = problem): -aov_ez("id", "response", sk2_final[sk2_final$what == "affirmation",], - between = "instruction", within = c("inference", "type"), - anova_table=list(es = "pes")) - -aov_ez("id", "response", sk2_final[sk2_final$what == "denial",], - between = "instruction", within = c("inference", "type"), - anova_table=list(es = "pes")) -} -\keyword{dataset} - +% Generated by roxygen2 (4.1.1): do not edit by hand +% Please edit documentation in R/sk2011.2-data.R +\docType{data} +\encoding{UTF-8} +\name{sk2011.2} +\alias{sk2011.2} +\title{Data from Singmann & Klauer (2011, Experiment 2)} +\format{A data.frame with 2268 rows and 9 variables.} +\source{ +Singmann, H., & Klauer, K. C. (2011). Deductive and inductive conditional inferences: Two modes of reasoning. Thinking & Reasoning, 17(3), 247-281. doi:10.1080/13546783.2011.572718 +} +\usage{ +sk2011.2 +} +\description{ +Singmann and Klauer (2011) were interested in whether or not conditional reasoning can be explained by a single process or whether multiple processes are necessary to explain it. To provide evidence for multiple processes we aimed to establish a double dissociation of two variables: instruction type and problem type. Instruction type was manipulated between-subjects, one group of participants received deductive instructions (i.e., to treat the premises as given and only draw necessary conclusions) and a second group of participants received probabilistic instructions (i.e., to reason as in an everyday situation; we called this "inductive instruction" in the manuscript). Problem type consisted of two different orthogonally crossed variables that were manipulated within-subjects, validity of the problem (formally valid or formally invalid) and type of the problem. Problem type consistent of three levels: prological problems (i.e., problems in which background knowledge suggested to accept valid but reject invalid conclusions), neutral problems (i.e., in which background knowledge suggested to reject all problems), and counterlogical problems (i.e., problems in which background knowledge suggested to reject valid but accept invalid conclusions). +} +\details{ +This data set contains 63 participants in contrast to the originally reported 56 participants. The additional participants were not included in the original studies as they did not meet the inclusion criteria (i.e., no students, prior education in logic, or participated in a similar experiment). The IDs of those additional participants are: 7, 8, 9, 12, 17, 24, 30. The excluded participant reported in the paper has ID 16. + +content has the following levels (C = content/conditional):\cr + 1 = Wenn eine Person in ein Schwimmbecken gefallen ist, dann ist sie nass.\cr + 2 = Wenn ein Hund Flöhe hat, dann kratzt er sich hin und wieder.\cr + 3 = Wenn eine Seifenblase mit einer Nadel gestochen wurde, dann platzt sie.\cr + 4 = Wenn ein Mädchen Geschlechtsverkehr vollzogen hat, dann ist es schwanger.\cr + 5 = Wenn eine Pflanze ausreichend gegossen wird, dann bleibt sie grün.\cr + 6 = Wenn sich eine Person die Zähne putzt, dann bekommt sie KEIN Karies.\cr + 7 = Wenn eine Person viel Cola trinkt, dann nimmt sie an Gewicht zu.\cr + 8 = Wenn eine Person die Klimaanlage angeschaltet hat, dann fröstelt sie.\cr + 9 = Wenn eine Person viel lernt, dann wird sie in der Klausur eine gute Note erhalten. +} +\examples{ +data("sk2011.2") + +## remove excluded participants: + +sk2_final <- droplevels(sk2011.2[!(sk2011.2$id \%in\% c(7, 8, 9, 12, 16, 17, 24, 30)),]) +str(sk2_final) + +## Table 2 (inference = problem): +aov_ez("id", "response", sk2_final[sk2_final$what == "affirmation",], + between = "instruction", within = c("inference", "type"), + anova_table=list(es = "pes")) + +aov_ez("id", "response", sk2_final[sk2_final$what == "denial",], + between = "instruction", within = c("inference", "type"), + anova_table=list(es = "pes")) +} +\keyword{dataset} +