ARTool

R Package for Aligned Rank Transform for Nonparametric Factorial ANOVAs

https://github.com/mjskay/artool

Repository

R Package for Aligned Rank Transform for Nonparametric Factorial ANOVAs

README.Rmd

---
output: github_document
---

# ARTool: R Package for the Aligned Rank Transform for Nonparametric Factorial ANOVAs 

[![R build status](https://github.com/mjskay/ARTool/workflows/R-CMD-check/badge.svg)](https://github.com/mjskay/ARTool/actions)
[![Coverage status](https://codecov.io/gh/mjskay/ARTool/branch/master/graph/badge.svg)](https://app.codecov.io/github/mjskay/ARTool?branch=master)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/ARTool)](https://CRAN.R-project.org/package=ARTool)
[![GPL >= 2](https://img.shields.io/badge/GPL-%E2%89%A52-brightgreen.svg)](https://cran.r-project.org/web/licenses/GPL-3)
[![DOI](https://zenodo.org/badge/19809/mjskay/ARTool.svg)](https://zenodo.org/badge/latestdoi/19809/mjskay/ARTool)
[![DOI](https://img.shields.io/badge/DOI-10.1145%2F1978942.1978963-blue.svg)](https://dx.doi.org/10.1145/1978942.1978963)

_Matthew Kay, Northwestern University _

_Lisa A. Elkin, University of Washington, _

_James J. Higgins, Kansas State University, _

_Jacob O. Wobbrock, University of Washington _

ARTool is an R package implementing the Aligned Rank Transform for conducting
nonparametric analyses of variance on factorial models. This implementation is
based on the ART procedure as used in the original implementation of 
[ARTool](https://depts.washington.edu/acelab/proj/art/) by Wobbrock et al.

The package automates the Aligning-and-Ranking process using the `art` function.
It also automates the process of running a series of ANOVAs on the transformed
data and extracting the results of interest. It supports traditional ANOVA
models (fit using `lm`), repeated measures ANOVAs (fit using `aov`), and 
mixed effects models (fit using `lmer`); the model used is determined by the
formula passed to `art`.

__Note__: The documentation of this package assumes some level of familiarity
with when and why you may want to use the aligned rank transform; the 
[ARTool page](https://depts.washington.edu/acelab/proj/art/) provides a more in-depth (and
highly approachable) introduction to the aligned rank transform and the
motivation for its use.

## Installation

You can install the latest released version from CRAN with this R command:

```{r, eval=FALSE}
install.packages("ARTool")
```

__Or__, you can install the latest development version from GitHub with these R
commands:

```{r, eval=FALSE}
install.packages("devtools")
devtools::install_github("mjskay/ARTool")
```

## Example

The general approach to using ART is to transform your data using `art` , verify
the ART procedure is appropriate to the dataset using `summary` , and then run an
ANOVA on the transformed data using `anova` .

First, let us load some example data:

```{r, message=FALSE}
library(ARTool)
data(Higgins1990Table5, package = "ARTool")
```

`Higgins1990Table5`  is a data frame from an experiment in which the effects of `Moisture`
and `Fertilizer` on `DryMatter` in peat pots was tested. Four pots were placed on
each `Tray` , with `Moisture` varied between `Tray` s and `Fertilizer` varied
within `Tray` s. We can see the basic structure of the data:

```{r}
str(Higgins1990Table5)
head(Higgins1990Table5, n=8)
```

### Step 1: Transform the data

To analyze this data using the aligned rank transform, we first transform the
data using `art` . We specify the response variable (`DryMatter` ), the fixed
effects and all of their interactions (`Moisture*Fertilizer`, or equivalently 
`Moisture + Fertilizer + Moisture:Fertilizer`), and any grouping terms if 
present (here, `(1|Tray)` ). 

While `(1|Tray)` has no effect on the results of 
the aligned rank transformation, it will be used by `anova` to determine the 
type of model to run: when grouping terms are present, mixed effects models
are run using `lmer`. If you wish to use a repeated measures ANOVA instead of
a mixed effects model, you can use an `Error` term instead (see below for an
example of this). If you do not having repeated measures, do not include
any grouping terms or error terms. 

```{r}
m <- art(DryMatter ~ Moisture*Fertilizer + (1|Tray), data=Higgins1990Table5)
```

### Step 2: Verify appropriateness of ART

To verify that the ART procedure was correctly applied and is appropriate for
this dataset, we can look at the output of `summary` :

```{r}
summary(m)
```

We see that the columns sums of aligned responses and the F values of ANOVAs on
aligned responses not of interest are all ~0, indicating that the alignment
correctly "stripped out" effects not of interest. Thus, we can apply the ANOVA
on the transformed data. 

### Step 3: Run the ANOVA

ARTool automatically selects the model to be used
for the ANOVA. Because we have included a grouping term, `(1|Tray)`, ARTool
will fit mixed effects models using `lmer` and run the ANOVAs on them:

```{r}
anova(m)
```

### Alternative model: Repeated Measures ANOVA

This particular study could also be analyzed using a repeated measures ANOVA, 
yielding the same results (note that repeated measures ANOVAs and mixed
effects models will not always yield the same results). To instead run
a repeated measures ANOVA, add an `Error` term to the model as you
might for a call to `aov`:

```{r}
m <- art(DryMatter ~ Moisture*Fertilizer + Error(Tray), data=Higgins1990Table5)
anova(m)
```

## Contrast tests

For an example of how to run contrast tests on an `art` model, see `vignette("art-contrasts")`.

## Problems

Should you encounter any bugs in this package, please file it 
[here](https://github.com/mjskay/ARTool/issues/new) with minimal code to 
reproduce the issue.

## Citations

Kay, M., Elkin, L. A., Higgins, J. J., and Wobbrock, J. O. (`r format(Sys.Date(), "%Y")`).
_ARTool: Aligned Rank Transform for Nonparametric Factorial ANOVAs_.
R package version `r getNamespaceVersion("ARTool")`, .
DOI: [10.5281/zenodo.594511](https://dx.doi.org/10.5281/zenodo.594511).

For the *ART* procedure used by `art()` and `anova.art()`, cite:

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 2011)_. Vancouver, British Columbia (May 7-12, 2011). 
New York: ACM Press, pp. 143-146. .
DOI: [10.1145/1978942.1978963](https://dx.doi.org/10.1145/1978942.1978963).

For the *ART-C* contrast testing procedure used by `art.con()` and `artlm.con()`, cite:

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 2021)_. Virtual Event
(October 10-14, 2021). New York: ACM Press, pp. 754-768. DOI: 
[10.1145/3472749.3474784](https://dx.doi.org/10.1145/3472749.3474784)

Owner

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: over 1 year ago

Packages