ARTool (version 0.11.2)

art.con: Aligned Ranked Transform Contrasts

Description

Conduct contrast tests following an Aligned Ranked Transform (ART) ANOVA (anova.art). Conducts contrasts on 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.

Usage

art.con(
  m,
  formula,
  response = "art",
  factor.contrasts = "contr.sum",
  method = "pairwise",
  interaction = FALSE,
  adjust,
  ...
)

Value

An object of class emmGrid. See contrast

for details.

Arguments

m

An object of class art.

formula

Either a character vector or a formula specifying the fixed effects whose levels will be compared. See "Formula" section below.

response

Which response to use: the aligned response ("aligned") or the aligned-and-ranked response ("art"). Default is "art". This argument is passed to artlm.con (when interaction = FALSE) or artlm (when interaction = TRUE).

factor.contrasts

The name of the contrast-generating function to be applied by default to fixed effect factors. Sets the the first element of options("contrasts") for the duration of this function. The default is to use "contr.sum", i.e. sum-to-zero contrasts, which is appropriate for Type III ANOVAs (the default ANOVA type for anova.art). This argument is passed to artlm.con / artlm.

method

Contrast method argument passed to contrast. Note: the default is "pairwise" even though the default for the contrast function is "eff".

interaction

Logical value. If FALSE (the default), conducts contrasts using the ART-C procedure and artlm.con. If TRUE, conducts difference-of-difference contrasts using a model returned by artlm. See the "Interaction Contrasts" section in contrast.

adjust

Character: adjustment method (e.g., "bonferroni") passed to contrast. If not provided, contrast will use its default ("tukey" at the time of publication). All available options are listed in summary.emmGrid in the "P-value adjustments" section.

...

Additional arguments passed to lm or lmer.

Formula

Contrasts compare combinations of levels from multiple factors. The formula parameter indicates which factors are involved. Two formats are accepted: (1) a character vector as used in artlm and artlm.con, with factors separated by ":"; or (2) a formula as used in emmeans, with factors separated by *. For example, contrasts comparing combinations of levels of factors X1 and X2 can be expressed as "X1:X2" (character vector) or as ~ X1*X2 (formula).

Author

Lisa A. Elkin, Matthew Kay, Jacob O. Wobbrock

Details

An art model m stores the formula and data that were passed to art when m was created. Depending on the requested contrast type, this function either extracts the linear model from 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 formula.

Internally, this function uses artlm.con (when interaction = FALSE) or artlm (when interaction = TRUE) to get the linear model necessary for the requested contrast, computes estimated marginal means on the linear model using emmeans, and conducts contrasts using contrast.

References

Elkin, L. A., Kay, M, Higgins, J. J., and Wobbrock, J. O. (2021). An aligned rank transform procedure for multifactor contrast tests. 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. tools:::Rd_expr_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. 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. tools:::Rd_expr_doi("10.1145/1978942.1978963")

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")

# }