In mattansb/marginC: Create a multi-factor vector of weights

This package is no longer under development - it is recommended instead to use emmeans's custom contrast fucntions instead.

knitr::opts_chunk$set(echo = TRUE, message = FALSE, fig.path = "man/")

marginC

This (mini) R package allows for the definition of interaction contrasts by way of defining marginal contrasts. Mainly, this package allows:

Given marginal weights, will provide a vector of weights that can be passed along to emmeans::contrast.
If a reference-grid object (created by emmeans::emmeans) is provided, the following tests will be conducted before returning the vector of weights:
1. Re-order the marginal weights to match those in the reference-grid object.
2. Test that the provided marginal weights match those in the reference-grid object.
3. Test that the marginal weights are of the correct length (as those)tested against the reference-grid object).

Download and Install

You can install marginC from github with:

# install.packages("devtools")
devtools::install_github("mattansb/marginC")

These functions are meant for use alongside emmeans's functions (as seen bellow).

You will also need:
- magrittr
- purrr
(Both part of the tidyverse.)

Example using `afex`

Some sample anova with afex:

library(afex)

data(md_12.1)
fit <- aov_ez("id", "rt", md_12.1,
              within = c("angle", "noise"))

knitr::kable(nice(fit, es = "pes", correction = "none"))

Using emmeans it is easy to see this pattern:

Lets break down that interaction using emmeans:

library(emmeans)

# Define the interactions's refeerence grid:
rg <- emmeans(fit, ~angle*noise)

# plot it:
emmip(rg, noise~angle, CIs = T)

For this example we will focus on the difference in the effect of noise between angle-4 and angle-8. We can define this interaction-contrast using marginal weights:
- noise = c(-1,1) (the difference between the levels of noise)
- angle = c(0,1,-1) (the difference between the two of the levels of angle)

Lets see how marginC helps define this contrast.

Using `get_marginal_weights`

library(marginC)

get_marginal_weights(angle = c(0,-1,1), noise = c(-1,1))

If we include the reference grid (produced by emmeans), we get some additional functionality:
- The weights are named.
- The order in which we specify the marginal weights is dealt with internally.
- The lengths of the marginal weights is also tested internally for consistency with the reference grid object.

get_marginal_weights(angle = c(0,-1,1), noise = c(-1,1), .grid = rg)

Finally, we can feed this vector into emmeans's contrast:

my_weights <- list(my_contrast = get_marginal_weights(angle = c(0,-1,1),
                                                     noise = c(-1,1),
                                                     .grid = rg)) 
contrast(rg, my_weights)

Using `mw`

mw is a wraparound function for get_marginal_weights for ease of use:

mw(angle = c(0,-1,1), noise = c(-1,1))
mw(angle = c(0,-1,1), noise = c(-1,1), .grid = rg)

Updating the Grid

Instead of providing the grid directly to get_marginal_weights (or mw), we can apply is after-the fact by using update_grid:

my_weights <- list(first = mw(noise = c(-1,1),angle = c(0,-1,1)),
                   second = mw(noise = c(-1,1),angle = c(2,1,1)))
my_weights

my_weights <- update_grid(my_weights,grid = rg)
my_weights

Note that after calling update_grid, the returned weighs have changed, due to us providing the marginal weights in the incorrect order when we first called mw.

Using as a `contrast` method:

We can insert our custom weights as a method by following the emmeans guidlines. Here is an example:

my_method.emmc <- function(x){
  data.frame(my_contrast = mw(noise = c(-1,1), .grid = rg))
}

contrast(rg,interaction = c('poly','my_method'))
contrast(rg,interaction = c('consec','my_method'))