# art.con function for both "normal" contrasts and interaction contrasts
#
# Author: lelkin
###############################################################################
#' Aligned Ranked Transform Contrasts
#'
#' Conduct contrast tests following an Aligned Ranked Transform (ART) ANOVA
#' (\code{\link{anova.art}}). Conducts contrasts on \code{\link{art}} models
#' using aligned-and-ranked linear models using the ART (Wobbrock et al. 2011)
#' or ART-C (Elkin et al. 2021) alignment procedure, as appropriate to the requested contrast.
#'
#' An \code{\link{art}} model \code{m} stores the \code{formula} and \code{data}
#' that were passed to \code{\link{art}} when \code{m} was created. Depending on the
#' requested contrast type, this function either extracts the linear model from \code{m}
#' needed to perform that contrast or creates a new linear model on data
#' aligned-and-ranked using the ART-C
#' procedure, then conducts the contrasts specified in parameter \code{formula}.
#'
#' Internally, this function uses \code{\link{artlm.con}} (when \code{interaction = FALSE})
#' or \code{\link{artlm}} (when \code{interaction = TRUE}) to get the linear
#' model necessary for the requested contrast, computes estimated marginal
#' means on the linear model using \code{\link{emmeans}}, and conducts contrasts
#' using \code{\link{contrast}}.
#'
#' @param m An object of class \code{\link{art}}.
#' @param formula Either a character vector or a formula specifying the fixed
#' effects whose levels will be compared. See "Formula" section below.
#' @param response Which response to use: the aligned response
#' (\code{"aligned"}) or the aligned-and-ranked response
#' (\code{"art"}). Default is "art". This argument is passed to \code{\link{artlm.con}}
#' (when \code{interaction = FALSE}) or \code{\link{artlm}} (when \code{interaction = TRUE}).
#' @param factor.contrasts The name of the contrast-generating function to be
#' applied by default to fixed effect factors. Sets the the first element of
#' \code{\link{options}("contrasts")} for the duration of this function. The
#' default is to use \code{"contr.sum"}, i.e. sum-to-zero contrasts, which is
#' appropriate for Type III ANOVAs (the default ANOVA type for
#' \code{\link{anova.art}}). This argument is passed to \code{\link{artlm.con}} /
#' \code{\link{artlm}}.
#' @param method Contrast method argument passed to \code{\link{contrast}}.
#' Note: the default is \code{"pairwise"} even though the default for the
#' \code{\link{contrast}} function is \code{"eff"}.
#' @param interaction Logical value. If \code{FALSE} (the default), conducts contrasts using
#' the ART-C procedure and \code{\link{artlm.con}}. If \code{TRUE}, conducts
#' difference-of-difference contrasts using a model returned by \code{\link{artlm}}.
#' See the "Interaction Contrasts" section in \code{\link{contrast}}.
#' @param adjust Character: adjustment method (e.g., "bonferroni") passed to
#' \code{\link{contrast}}. If not provided, \code{\link{contrast}} will use
#' its default ("tukey" at the time of publication). All available options are listed
#' in \code{\link{summary.emmGrid}} in the "P-value adjustments" section.
#' @param \dots Additional arguments passed to \code{\link{lm}} or
#' \code{\link{lmer}}.
#' @return An object of class \code{emmGrid}. See \code{\link{contrast}}
#' for details.
#' @author Lisa A. Elkin, Matthew Kay, Jacob O. Wobbrock
#'
#' @section Formula: Contrasts compare combinations of levels from multiple
#' factors. The \code{formula} parameter indicates which factors are involved. Two
#' formats are accepted: (1) a character vector as used in
#' \code{\link{artlm}} and \code{\link{artlm.con}}, with factors separated by \code{":"};
#' or (2) a formula as used in \code{\link{emmeans}}, with factors separated by \code{*}.
#' For example, contrasts comparing
#' combinations of levels of factors \emph{X1} and \emph{X2} can be expressed
#' as \code{"X1:X2"} (character vector) or as \code{~ X1*X2} (formula).
#'
#' @references Elkin, L. A., Kay, M, Higgins, J. J., and Wobbrock, J. O.
#' (2021). An aligned rank transform procedure for multifactor contrast tests.
#' \emph{Proceedings of the ACM Symposium on User Interface Software and
#' Technology (UIST '21)}. Virtual Event (October 10--14, 2021). New York:
#' ACM Press, pp. 754--768. \doi{10.1145/3472749.3474784}
#'
#' Wobbrock, J. O., Findlater, L., Gergle, D., and Higgins, J. J.
#' (2011). The aligned rank transform for nonparametric factorial analyses
#' using only ANOVA procedures. \emph{Proceedings of the ACM Conference on
#' Human Factors in Computing Systems (CHI '11)}. Vancouver, British Columbia
#' (May 7--12, 2011). New York: ACM Press, pp. 143--146. \doi{10.1145/1978942.1978963}
#'
#' @export
#'
#' @examples
#' \donttest{
#' data(Higgins1990Table5, package = "ARTool")
#'
#' library(dplyr)
#'
#' ## Perform aligned rank transform
#' m <- art(DryMatter ~ Moisture*Fertilizer + (1|Tray), data=Higgins1990Table5)
#'
#' ## In a some workflows, contrast tests using ART-C would follow a
#' ## significant omnibus effect found by running an anova on the ART responses
#' ## (equivalent to anova(m, response="art")).
#' ## If conducting planned contrasts, this step can be skipped.
#' anova(m)
#'
#' ## We can conduct contrasts comparing levels of Moisture using the ART-C procedure.
#' ## If conducting contrasts as a post hoc test, this would follow a significant effect
#' ## of Moisture on DryMatter.
#'
#' ## Using a character vector
#' art.con(m, "Moisture")
#' ## Or using a formula
#' art.con(m, ~ Moisture)
#'
#' ## Note: Since the ART-C procedure is mathematically equivalent to the ART procedure
#' ## in the single-factor case, this is the same as
#' ## emmeans(artlm(m, "Moisture"), pairwise ~ Moisture)
#'
#' ## art.con() returns an emmGrid object, which does not print asterisks
#' ## beside "significant" tests (p < 0.05). If you wish to add stars beside
#' ## tests of a particular significant level, you can always do that to the
#' ## data frame returned by the summary() method of emmGrid. For example:
#' art.con(m, ~ Moisture) %>%
#' summary() %>%
#' mutate(sig = ifelse(p.value < 0.05, "*", ""))
#'
#' ## Or a more complex example:
#' art.con(m, ~ Moisture) %>%
#' summary() %>%
#' mutate(sig = symnum(p.value, corr = FALSE, na = FALSE,
#' cutpoints = c(0, 0.001, 0.01, 0.05, 0.1, 1),
#' symbols = c("***", "**", "*", ".", " ")
#' ))
#'
#' ## We can conduct contrasts comparing combinations of levels
#' ## of Moisture and Fertilizer using the ART-C procedure.
#' ## If conducting contrasts as a post hoc test, this would follow
#' ## a significant Moisture:Fertlizer interaction effect on Drymatter.
#'
#' ## Using a character vector for formula
#' art.con(m, "Moisture:Fertilizer")
#' ## Using a formula
#' art.con(m, ~ Moisture*Fertilizer)
#'
#' ## We can also conduct interaction contrasts (comparing differences of differences)
#' art.con(m, "Moisture:Fertilizer", interaction = TRUE)
#'
#' ## For more examples, see vignette("art-contrasts")
#'
#' }
art.con = function(
m, formula, response = "art", factor.contrasts="contr.sum", method = "pairwise",
interaction = FALSE, adjust, ...
) {
f.parsed = parse.art.con.formula(formula)
# syntax handled differently for interaction contrasts.
if (interaction) {
art.interaction.contrast = do.art.interaction.contrast(m, f.parsed, response, factor.contrasts, method, adjust, ...)
art.interaction.contrast
}
else {
artlm.con = artlm.con.internal(m, f.parsed, response, factor.contrasts, ...)
art.contrast = do.art.contrast(f.parsed, artlm.con, method, adjust)
art.contrast
}
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.