Introduction to hypr

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.

Creating a hypr object

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.

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

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

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

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

Using and manipulating hypr objects

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:

otherC <- hypr()
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

Deriving contrasts

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:

helC <- hypr(m2~m1, m3~(m1+m2)/2, m4~(m1+m2+m3)/3)
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"