ARTool (version 0.11.2)

art: Aligned Rank Transform

Description

Apply the aligned rank transform to a factorial model (with optional grouping terms). Usually done in preparation for a nonparametric analyses of variance on models with numeric or ordinal responses, which can be done by following up with anova.art.

Usage

art(
  formula,
  data,
  rank.comparison.digits = -floor(log10(.Machine$double.eps^0.5)),
  check.errors.are.factors = TRUE
)

Value

An object of class "art":

call

The call used to generate the transformed data.

formula

The formula used to generate the transformed data.

cell.means

A data frame of cell means for each fixed term and interaction on the right-hand side of formula.

estimated.effects

A data frame of estimated effects for each fixed term and interaction on the right-hand side of formula.

residuals

A vector of residuals (response - cell mean of highest-order interaction).

aligned

A data frame of aligned responses for each fixed term and interaction on the right-hand side of formula.

aligned.ranks

A data frame of aligned and ranked responses for each fixed term and interaction on the right-hand side of formula.

data

The input data frame

n.grouping.terms

The number of grouping variables in the input formula.

For a complete description of cell means, estimated effects, aligned ranks, etc., in the above output, see Wobbrock et al. (2011).

Arguments

formula

A factorial formula with optional grouping terms or error terms (but not both). Should be a formula with a single response variable (left-hand side) and one or more terms with all interactions on the right-hand side, e.g. y ~ x or y ~ a*b*c or y ~ a + b + b:c. If you want to run a mixed effects ANOVA on the transformed data using lmer, you can include grouping terms, as in y ~ a*b*c + (1|d). If you want to run a repeated measures ANOVA using aov, you can include error terms, as in y ~ a*b*c + Error(d). See 'Details'.

data

An optional data frame containing the variables in the model.

rank.comparison.digits

The number of digits to round aligned responses to before ranking (to ensure ties are computed consistently). See the digits argument of round. The default value is based on the default tolerance used for fuzzy comparison in all.equal.

check.errors.are.factors

Should we check to ensure Error() terms are all factors? A common mistake involves coding a categorical variable as numeric and passing it to Error(), yielding incorrect results from aov. Disabling this check is not recommended unless you know what you are doing; the most common uses of Error() (e.g. in repeated measures designs) involve categorical variables (factors).

Author

Matthew Kay

Details

The aligned rank transform allows a nonparametric analysis of variance to be conducted on factorial models with fixed and random effects (or repeated measures) and numeric or ordinal responses. This is done by first aligning and ranking the fixed effects using this function, then conducting an analysis of variance on linear models built from the transformed data using anova.art (see 'Examples'). The model specified using this function must include all interactions of fixed effects.

The formula should contain a single response variable (left-hand side) that can be numeric, an ordered factor, or logical. The right-hand side of the formula should contain one or more fixed effect factors, zero or more grouping terms, and zero or more error terms. Error terms and grouping terms cannot be used simultaneously. All possible interactions of the fixed effect terms must be included. For example, y ~ x and y ~ a*b*c and y ~ a + b + b:c are legal, but y ~ a + b is not, as it omits the interaction a:b. Grouping terms are specified as in lmer, e.g. y ~ a*b*c + (1|d) includes the random intercept term (1|d). Error terms are specified as in aov, e.g. y ~ a*b*c + Error(d). Grouping terms and error terms are not involved in the transformation, but are included in the model when ANOVAs are conducted, see anova.art.

For details on the transformation itself, see Wobbrock et al. (2011) or the ARTool website: https://depts.washington.edu/acelab/proj/art/.

References

Wobbrock, J. O., Findlater, L., Gergle, D., and Higgins, J. J. ARTool. https://depts.washington.edu/acelab/proj/art/.

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

See Also

summary.art, anova.art, artlm, artlm.con, art.con.

Examples

# \donttest{
data(Higgins1990Table5, package = "ARTool")

## perform aligned rank transform
m <- art(DryMatter ~ Moisture*Fertilizer + (1|Tray), data=Higgins1990Table5)

## see summary data to ensure aligned rank transform is appropriate for this data
summary(m)
## looks good (aligned effects sum to 0 and F values on aligned responses
## not of interest are all ~0)

## we can always look at the anova of aligned data if we want more detail
## to assess the appropriateness of ART.  F values in this anova should all
## be approx 0.
anova(m, response="aligned")

## then we can run an anova on the ART responses (equivalent to anova(m, response="art"))
anova(m)


## if we want contrast tests, we can use art.con():
## Ex 1: pairwise contrasts on Moisture:
art.con(m, "Moisture")
## Ex 2: pairwise contrasts on Moisture:Fertilizer:
art.con(m, "Moisture:Fertilizer")
## Ex 3: difference-of-difference tests on the Moisture:Fertilizer interaction:
art.con(m, "Moisture:Fertilizer", interaction = TRUE)


## The above three examples with art.con() can be constructed manually as well.
## art.con() extracts the appropriate linear model and conducts contrasts
## using emmeans(). If we want to use a specific method for post-hoc tests
## other than emmeans(), artlm.con(m, term) returns the linear model for the
## specified term which we can then examine using our preferred method
## (emmeans, glht, etc). The equivalent calls for the above examples are:
library(emmeans)

## Ex 1: pairwise contrasts on Moisture:
contrast(emmeans(artlm.con(m, "Moisture"), ~ Moisture), method = "pairwise")

## Ex 2: pairwise contrasts on Moisture:Fertilizer:
## See artlm.con() documentation for more details on the syntax, specifically
## the formula passed to emmeans.
contrast(emmeans(artlm.con(m, "Moisture:Fertilizer"), ~ MoistureFertilizer), method = "pairwise")

## Ex 3: difference-of-difference tests on the Moisture:Fertilizer interaction:
## Note the use of artlm() instead of artlm.con()
contrast(
  emmeans(artlm(m, "Moisture:Fertilizer"), ~ Moisture:Fertilizer),
  method = "pairwise", interaction = TRUE
)


## For a more in-depth explanation and example of contrasts with art and
## differences between interaction types, see vignette("art-contrasts")

# }