---
title: "contrastable"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{contrastable}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r, include = FALSE}
  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")`.
  
  
```{r setup}
  # 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:

```{r,eval = FALSE}
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.

```{r}
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 `+`

```{r}
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.

```{r}
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.


```{r}
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
```


```{r}
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:

```{r}
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`).

```{r}
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:

```{r}
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.

```{r}
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:

```{r}
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:

```{r}
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.

```{r}
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.
 
```{r}
enlist_contrasts(mtcars, carb ~ contr.helmert)
```

```{r, eval = FALSE}
enlist_contrasts(mtcars, carb ~ helmert_code())
```

```{r, echo = FALSE}
carb_contrasts <- enlist_contrasts(mtcars, carb ~ helmert_code())
carb_contrasts[["carb"]] <- MASS::fractions(carb_contrasts[[1]])
carb_contrasts
```
 
See `vignette("contrasts")` for more information.
