`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.

The `hypr()`

function accepts any set of null hypothesis
equations as comma-separated arguments. An empty `hypr`

object can be created by calling the function without arguments,
i.e. empty parantheses.

`<- hypr(mu1~0, mu2~mu1, mu3~mu1, mu4~mu1) trtC `

If you want to provide names for contrasts, you can name the function arguments as follows but this is optional:

`<- hypr(base = mu0~0, trt1 = mu1~mu0, trt2 = mu2~mu0, trt3 = mu3~mu0) trtC `

When calling this function, a `hypr`

object named
`trtC`

is generated which contains all four hypotheses from
above as well as the hypothesis and contrast matrices derived from
those. We can display a summary like any other object in R:

` trtC`

```
## hypr object containing 4 null hypotheses:
## H0.base: 0 = mu0 (Intercept)
## H0.trt1: 0 = mu1 - mu0
## H0.trt2: 0 = mu2 - mu0
## H0.trt3: 0 = mu3 - mu0
##
## Call:
## hypr(base = ~mu0, trt1 = ~mu1 - mu0, trt2 = ~mu2 - mu0, trt3 = ~mu3 -
## mu0, levels = c("mu0", "mu1", "mu2", "mu3"))
##
## Hypothesis matrix (transposed):
## base trt1 trt2 trt3
## mu0 1 -1 -1 -1
## mu1 0 1 0 0
## mu2 0 0 1 0
## mu3 0 0 0 1
##
## Contrast matrix:
## base trt1 trt2 trt3
## mu0 1 0 0 0
## mu1 1 1 0 0
## mu2 1 0 1 0
## mu3 1 0 0 1
```

As you can see, the level names in `hypr`

objects are
automatically derived from the hypotheses and sorted alphabetically. You
may also provide a different sorting by explicitly providing level names
for the `levels`

argument:

`hypr(one~0, two~one, three~one, four~one, levels = c("one", "two", "three", "four"))`

```
## hypr object containing 4 null hypotheses:
## H0.1: 0 = one (Intercept)
## H0.2: 0 = two - one
## H0.3: 0 = three - one
## H0.4: 0 = four - one
##
## Call:
## hypr(~one, ~two - one, ~three - one, ~four - one, levels = c("one",
## "two", "three", "four"))
##
## Hypothesis matrix (transposed):
## [,1] [,2] [,3] [,4]
## one 1 -1 -1 -1
## two 0 1 0 0
## three 0 0 1 0
## four 0 0 0 1
##
## Contrast matrix:
## [,1] [,2] [,3] [,4]
## one 1 0 0 0
## two 1 1 0 0
## three 1 0 1 0
## four 1 0 0 1
```

In the example above, a `hypr`

object is created in which
the hypothesis and contrast matrices are ordered `one`

,
`two`

, `three`

, `four`

. If
`levels`

was not provided, the matrices in the resulting
object would be ordered alphabetically, i.e. `four`

,
`one`

, `three`

, `two`

.

The character vector passed as the `levels`

argument must
contain all levels named in the hypotheses. If it does not, an error
will be thrown. However, it *may* contain level names that are
not named in any of the null hypotheses. This will expand the hypothesis
and contrast matrices by that level but not affect the coding of the
other levels:

`hypr(one~0, two~one, three~one, four~one, levels = c("one", "two", "three", "four", "five"))`

```
## hypr object containing 4 null hypotheses:
## H0.1: 0 = one
## H0.2: 0 = two - one
## H0.3: 0 = three - one
## H0.4: 0 = four - one
##
## Call:
## hypr(~one, ~two - one, ~three - one, ~four - one, levels = c("one",
## "two", "three", "four", "five"))
##
## Hypothesis matrix (transposed):
## [,1] [,2] [,3] [,4]
## one 1 -1 -1 -1
## two 0 1 0 0
## three 0 0 1 0
## four 0 0 0 1
## five 0 0 0 0
##
## Contrast matrix:
## [,1] [,2] [,3] [,4]
## one 1 0 0 0
## two 1 1 0 0
## three 1 0 1 0
## four 1 0 0 1
## five 0 0 0 0
```

These properties can also be directly accessed with the appropriate methods:

`formula(trtC) # a list of equations`

```
## $base
## ~mu0
##
## $trt1
## ~mu1 - mu0
##
## $trt2
## ~mu2 - mu0
##
## $trt3
## ~mu3 - mu0
```

`levels(trtC) # a vector of corresponding factor levels (variables in equations)`

`## [1] "mu0" "mu1" "mu2" "mu3"`

`names(trtC) # a vector of corresponding contrast names`

`## [1] "base" "trt1" "trt2" "trt3"`

`hmat(trtC) # the hypothesis matrix`

```
## mu0 mu1 mu2 mu3
## base 1 0 0 0
## trt1 -1 1 0 0
## trt2 -1 0 1 0
## trt3 -1 0 0 1
```

`thmat(trtC) # the transposed hypothesis matrix (as displayed in the summary)`

```
## base trt1 trt2 trt3
## mu0 1 -1 -1 -1
## mu1 0 1 0 0
## mu2 0 0 1 0
## mu3 0 0 0 1
```

`cmat(trtC) # the contrast matrix`

```
## Warning in cmat(trtC): The contrast matrix you are retrieving appears to have
## an intercept column. If this is intentional, you can ignore this warning or
## suppress it by explictly calling cmat(..., remove_intercept=FALSE).
```

```
## base trt1 trt2 trt3
## mu0 1 0 0 0
## mu1 1 1 0 0
## mu2 1 0 1 0
## mu3 1 0 0 1
```

All of these methods can also be used to manipulate `hypr`

objects. For example, if you would like to create a `hypr`

object from a given contrast matrix, you could create an empty
`hypr`

object and then update its contrast matrix:

```
<- hypr()
otherC cmat(otherC) <- cbind(int = 1, contr.treatment(4)) # add intercept to treatment contrast
otherC
```

```
## hypr object containing 4 null hypotheses:
## H0.int: 0 = X1 (Intercept)
## H0.2: 0 = -X1 + X2
## H0.3: 0 = -X1 + X3
## H0.4: 0 = -X1 + X4
##
## Call:
## hypr(int = ~X1, `2` = ~-X1 + X2, `3` = ~-X1 + X3, `4` = ~-X1 +
## X4, levels = c("X1", "X2", "X3", "X4"))
##
## Hypothesis matrix (transposed):
## int 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:
## int 2 3 4
## X1 1 0 0 0
## X2 1 1 0 0
## X3 1 0 1 0
## X4 1 0 0 1
```

You can always use `cmat`

to derive the complete contrast
matrix from a `hypr`

object. Note, however, that depending on
the contrast scheme used, it might be necessary to remove the intercept
contrast from the matrix before assigning it to a factor for regression
analysis.

For example, the `trtC`

object from above contains such an
intercept:

`cmat(trtC)`

```
## Warning in cmat(trtC): The contrast matrix you are retrieving appears to have
## an intercept column. If this is intentional, you can ignore this warning or
## suppress it by explictly calling cmat(..., remove_intercept=FALSE).
```

```
## base trt1 trt2 trt3
## mu0 1 0 0 0
## mu1 1 1 0 0
## mu2 1 0 1 0
## mu3 1 0 0 1
```

You can set `remove_intercept=TRUE`

to drop the
intercept:

`cmat(trtC, remove_intercept = TRUE)`

```
## trt1 trt2 trt3
## mu0 0 0 0
## mu1 1 0 0
## mu2 0 1 0
## mu3 0 0 1
```

Other contrast coding schemes such as Helmert contrasts do not yield an intercept term:

```
<- hypr(m2~m1, m3~(m1+m2)/2, m4~(m1+m2+m3)/3)
helC cmat(helC)
```

```
## [,1] [,2] [,3]
## m1 -1/2 -1/3 -1/4
## m2 1/2 -1/3 -1/4
## m3 0 2/3 -1/4
## m4 0 0 3/4
```

Setting `remove_intercept=TRUE`

would throw an error
because the function cannot find the intercept column.

`cmat(helC, remove_intercept = TRUE) # throws an error`

Therefore, when you are unsure whether to set
`remove_intercept`

to `TRUE`

or `FALSE`

(default) but would like to use the sensible default of removing an
intercept when there is one, you can set
`remove_intercept=NULL`

. A useful wrapper function which uses
this as a default is `contr.hypothesis`

:

`contr.hypothesis(trtC) # removes `base` column`

```
## trt1 trt2 trt3
## mu0 0 0 0
## mu1 1 0 0
## mu2 0 1 0
## mu3 0 0 1
## attr(,"class")
## [1] "hypr_cmat" "matrix" "array"
```

`contr.hypothesis(helC) # removes nothing`

```
## [,1] [,2] [,3]
## m1 -0.5 -0.3333333 -0.25
## m2 0.5 -0.3333333 -0.25
## m3 0.0 0.6666667 -0.25
## m4 0.0 0.0000000 0.75
## attr(,"class")
## [1] "hypr_cmat" "matrix" "array"
```

`contr.hypothesis`

can also come in handy if you don’t
really need the `hypr`

object but would only like to specify
the hypotheses and return the contrast matrix. In that case, you can
just use `contr.hypothesis`

like the `hypr`

function:

`contr.hypothesis(m1~0, m2~m1, m3~m1)`

```
## [,1] [,2]
## m1 0 0
## m2 1 0
## m3 0 1
## attr(,"class")
## [1] "hypr_cmat" "matrix" "array"
```

`contr.hypothesis(m2~m1, m3~(m1+m2)/2, m4~(m1+m2+m3)/3)`

```
## [,1] [,2] [,3]
## m1 -0.5 -0.3333333 -0.25
## m2 0.5 -0.3333333 -0.25
## m3 0.0 0.6666667 -0.25
## m4 0.0 0.0000000 0.75
## attr(,"class")
## [1] "hypr_cmat" "matrix" "array"
```