In tsostarics/contrastable: Consistent Contrast Coding for Factors

  knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
  )

Get started

This vignette provides a quick guide to start using this package for your analyses. Additional examples with more written detail are available in vignette("contrasts").

  # install.packages("contrastable")
library(contrastable)
library(dplyr)

Setting contrasts to data frame columns

There are three main functions which I'll discuss in order:

• set_contrasts: set contrasts directly to factor columns
• enlist_contrasts: get a list of contrast matrices
• glimpse_contrasts: get a summary table of contrast information

All three use a shared two-sided formula syntax, for example:

enlist_contrasts(my_dataframe, 
                 varname ~ contrast_scheme + reference * intercept - dropped | labels)

• varname: The variable name of the column whose contrasts you want to set.
• contrast_scheme: (most often) a function that creates contrast matrices, can also be a variable assigned a matrix (eg my_mat <- matrix(...), my_mat can be used) or a hypr object.
• reference: Use the + operator to set the reference level. This is usually the baseline to use for pairwise comparisons. If the levels of varname are c("High", "Mid", "Low"), you might set this to Low with + "Low"
• intercept: Use the * operator to set the intercept, overwriting whatever the default is for the given contrast scheme. For example, the intercept (and reference level) for treatment_code is usually the first level alphabetically, but could be changed. For example, * "Mid"
• dropped: Use the - operator to remove some comparisons from the contrast matrix. Cannot be used with set_contrasts(). Sometimes used with polynomial contrasts.
• labels: Use the | operator to set the comparison labels, overwriting the defaults for the contrast scheme. For example, if doing pairwise comparisons for varname using treatment_code for levels c("High", "Mid", "Low") with High as the default reference level, the default coefficient names will be varnameMid and varnameLow. We can use | c("Mid-High", "Low-High") to change these in the output to varnameMid-High and varnameLow-High.

The operators can be used in any order, but contrast_scheme always has to be the first thing after the ~.

set_contrasts

Use this to set contrasts directly to a column, coercing it to a factor as necessary. Often used as the last step in a wrangling pipeline. The result should be assigned to a variable. We can set print_contrasts = TRUE to print the contrasts that have been set. Below we set the contrasts for a binary gear_type variable to use scaled sum coding with odd as the reference level while setting the comparison label to be something informative, which is reflected in the model summary.

model_data <-
  mtcars |>
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |>
  set_contrasts(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                print_contrasts = TRUE)

summary(lm(mpg ~ gear_type, data = model_data))

We can set multiple columns at once by listing multiple columns on the left hand side, separated by +

model_data <-
  mtcars |>
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |>
  set_contrasts(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                print_contrasts = TRUE,
                carb + cyl ~ helmert_code)

summary(lm(mpg ~ gear_type + carb + cyl, data = model_data))

We can also use tidyselect functionality to target multiple columns. Note that when doing so, you cannot specify duplicated column names.

model_data <-
  mtcars |>
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |>
  set_contrasts(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                vs:carb ~ helmert_code,
                print_contrasts = TRUE)

enlist_contrasts

Used to get a named list of contrast matrices. Useful to pass to the contrasts argument of a modeling function if available.

model_contrasts <-
  mtcars |>
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |>
  enlist_contrasts(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"))

model_contrasts

model_contrasts <-
  mtcars |>
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |>
  enlist_contrasts(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                   carb + cyl ~ sum_code)

model_contrasts

We can also use matrix objects when setting contrasts:

carb_contrasts <- scaled_sum_code(6)

enlist_contrasts(mtcars,
                 cyl ~ sum_code,
                 carb ~ carb_contrasts)

Note here that the reference level is always the first level in the factor, which is typically alphanumeric order. For example, contr.sum usually sets the last level as the reference, but we can see that when using this package's functions it's always the first level (for sum coding, this is the row with all -1).

contr.sum(3) # third row = reference level

enlist_contrasts(mtcars, cyl ~ contr.sum) # == sum_code

This behavior can be suppressed by wrapping the contrast scheme with I(), but will issue a warning:

enlist_contrasts(mtcars, cyl ~ I(contr.sum)) # == sum_code

glimpse_contrasts

Used to summarize information about the contrast schemes used. Note that this is usually used as a 2-step process, as it needs information about the contrast specifications and it expects that the same contrasts are set to the dataframe provided. For example, if I try to glimpse the contrasts for mtcars directly, I'll be warned that the dataframe columns aren't actually set to what I specified in the formulas, along with a code snippet of how to fix this.

mtcars2 <- 
  dplyr::mutate(mtcars, gear_type = ifelse(gear %% 2 == 0, "even", "odd"))

glimpse_contrasts(mtcars2,
                  gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                  carb + cyl ~ sum_code)

I can copy-paste this directly and try again:

mtcars2 <- set_contrasts(mtcars2, 
                         gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                         carb + cyl ~ sum_code) 

glimpse_contrasts(mtcars2,
                  gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                  carb + cyl ~ sum_code)

The observation here is that if I don't use set_contrasts() on my dataset used in my statistical model, the results won't match the information in the table from glimpse_contrasts(). However, this also requires changing the formulas in 2 places if I need to make any changes. We can make 1 list of contrast formulas that we pass around to different functions like so:

my_contrasts <- list(gear_type ~ scaled_sum_code + "odd" | c("Odd-Even"),
                     carb + cyl ~ sum_code)

mtcars2 <- 
  mtcars |> 
  dplyr::mutate(gear_type = ifelse(gear %% 2 == 0, "even", "odd")) |> 
  set_contrasts(my_contrasts)

glimpse_contrasts(mtcars2, my_contrasts)

decompose_contrasts

Use this function to extract the contrasts of one column into separate columns-- one for each comparison. This function is particularly helpful for pedagogical uses to show students how contrasts are represented from the model's perspective. Below we see that we've added 3 new columns from decomposing the gear_type and cyl columns into their respective comparisons.

mtcars2 |> 
  decompose_contrasts(~gear_type + cyl) |> 
  head()

Contrast functions

Below is a listing of the different contrast coding functions provided by this package. You would use these in the contrast_scheme part of the formulas. The intercept is described for the default case, but can be changed as described above using the * operator.

• treatment_code(): Pairwise comparisons from a reference level, intercept equals mean of the reference level.
• scaled_sum_code(): Pairwise comparisons from a reference level, intercept equals the grand mean
• sum_code(): Pairwise comparisons from the grand mean for all levels except the reference level, intercept equals the grand mean.
• backwards_difference_code(): Subtract adjacent levels. For levels A, B, C, D (in that order), returns the differences B-A, C-B, and D-C. Intercept equals the grand mean.
• forwards_difference_code(): Subtract adjacent levels. For levels A, B, C, D (in that order), returns the differences A-B, B-C, and C-D. Intercept equals the grand mean.
• helmert_code(): Nested comparisons starting from the first level. Intercept equals the grand mean.
• reverse_helmert_code(): Nested comparisons starting from the last level. Intercept equals the grand mean.
• cumulative_split_code(): Cumulative grouping of levels. For levels A, B, C, D (in that order), returns A-(B+C+D), (A+B)-(C+D), (A+B+C)-D. Intercept equals the grand mean.
• polynomial_code(): Orthogonal polynomial coding, intercept equals the grand mean.
• raw_polynomial_code(): Raw polynomial coding, intercept equals the grand mean.

You can use any function that returns contrast matrices. Below are some functions from the stats and MASS packages that can be used.

• stats::contr.treatment(): Equivalent to treatment coding (treatment_code())
• stats::contr.SAS(): Equivalent to treatment coding, but uses the last level as the reference level by default. Note that this difference is neutralized due to this package always setting the first level as the reference level.
• stats::contr.poly: Equivalent to polynomial coding (polynomial_code())
• MASS::contr.sdif: Equivalent to backwards difference coding (backwards_difference_code())
• stats::contr.sum: Equivalent to sum coding (sum_code())
• stats::contr.helmert: Provides nested comparisons like helmert coding (helmert_code()), but the matrix is not scaled. This means that the effect estimates are off by a scaling factor dependent on the number of levels. This is reflected in the default comparison labels this package provides. See below.

enlist_contrasts(mtcars, carb ~ contr.helmert)

enlist_contrasts(mtcars, carb ~ helmert_code())

carb_contrasts <- enlist_contrasts(mtcars, carb ~ helmert_code())
carb_contrasts[["carb"]] <- MASS::fractions(carb_contrasts[[1]])
carb_contrasts

See vignette("contrasts") for more information.

tsostarics/contrastable documentation built on Jan. 25, 2025, 1:33 p.m.