# Using hypr to understand contrasts

## Background

hypr is a package for easy translation between experimental (null) hypotheses, hypothesis matrices and contrast matrices, as used for coding factor contrasts in linear regression models. The package can be used to derive contrasts from hypotheses and vice versa. This vignette provides an example for understanding contrasts by deriving hypotheses from contrast matrices.

For a general introduction to hypr, see the hypr-intro vignette:

vignette("hypr-intro", package = "hypr")

For an introduction to using hypr for contrast coding in regression models, see the hypr-regression vignette:

vignette("hypr-regression", package = "hypr")

## Example: Treatment contrasts

Treatment contrasts are relatively easy to understand. The intercept tests the statistical significance of the baseline against zero while the contrasts test the significance of the treatments against the baseline.

Even though this is a simple coding scheme, it might not be immediately clear to everyone examining the contrast matrix:

contr.treatment(4) # a contrast matrix for one baseline and 3 treatments
##   2 3 4
## 1 0 0 0
## 2 1 0 0
## 3 0 1 0
## 4 0 0 1

To understand what this contrast is testing, we can create an empty hypr object and set its contrast matrix to the one above:

h <- hypr()
cmat(h) <- contr.treatment(4)
## Warning in cmat<-(*tmp*, value = structure(c(0, 1, 0, 0, 0, 0, 1, 0, : The
## contrast matrix you are assigning to this hypr object does not appear to have
## an intercept column. If this is intentional, you can ignore this warning or
## suppress it by explictly calling cmat(..., add_intercept=FALSE) <- x.
h
## hypr object containing 3 null hypotheses:
## H0.2: 0 = X2
## H0.3: 0 = X3
## H0.4: 0 = X4
##
## Hypothesis matrix (transposed):
##    2 3 4
## X1 0 0 0
## X2 1 0 0
## X3 0 1 0
## X4 0 0 1
##
## Contrast matrix:
##    2 3 4
## X1 0 0 0
## X2 1 0 0
## X3 0 1 0
## X4 0 0 1

When looking at the inferred equations, we can see that this contrast tests the significance of the treatments against zero. This is only appropriate if there is no baseline. However, we may want to consider a non-zero baseline. This is usually included in regression models. To let hypr know that we are including an intercept for the baseline, we can set the contrast matrix like this:

cmat(h, add_intercept = TRUE) <- contr.treatment(4)
h
## hypr object containing 4 null hypotheses:
## H0.Intercept: 0 = X1
##         H0.2: 0 = -X1 + X2
##         H0.3: 0 = -X1 + X3
##         H0.4: 0 = -X1 + X4
##
## Hypothesis matrix (transposed):
##    Intercept 2  3  4
## X1  1        -1 -1 -1
## X2  0         1  0  0
## X3  0         0  1  0
## X4  0         0  0  1
##
## Contrast matrix:
##    Intercept 2 3 4
## X1 1         0 0 0
## X2 1         1 0 0
## X3 1         0 1 0
## X4 1         0 0 1

Finally, the derived hypotheses can be formulated as:

\begin{align} H_{0_1}:& \; \mu_1 = 0 \\ H_{0_2}:& \; \mu_2 = \mu_1 \\ H_{0_3}:& \; \mu_3 = \mu_1 \\ H_{0_4}:& \; \mu_4 = \mu_1 \end{align}