```{r, include = FALSE}
library(mmrm)
```

This package supports estimation of one- and multi-dimensional contrasts
(t-test and F-test calculation) with the [`df_1d()`](https://openpharma.github.io/mmrm/main/reference/df_1d.html) and
[`df_md()`](https://openpharma.github.io/mmrm/main/reference/df_md.html) functions.
Both functions utilize the chosen adjustment method from the initial `mmrm` call
for the calculation of degrees of freedom and (for Kenward-Roger methods) the
variance estimates for the test-statistics.

## One-dimensional contrasts

Compute the test of a one-dimensional (vector) contrast for a `mmrm` object with
Satterthwaite degrees of freedom.

```{r 1d_satterthwaite}
fit <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data
)

contrast <- numeric(length(component(fit, "beta_est")))
contrast[3] <- 1

df_1d(fit, contrast)
```

This works similarly when choosing a Kenward-Roger adjustment:

```{r 1d_kr}
fit_kr <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data,
  method = "Kenward-Roger"
)

df_1d(fit_kr, contrast)
```

We see that because this is a one-dimensional contrast, the degrees of freedoms
are identical for Satterthwaite and Kenward-Roger. However, the standard errors
are different and therefore the p-values are different.

Additional options for the degrees of freedom `method` are Residual and Between-Within.

## Multi-dimensional contrasts

Compute the test of a multi-dimensional (matrix) contrast for the above defined
`mmrm` object with Satterthwaite degrees of freedom:

```{r md_satterthwaite}
contrast <- matrix(data = 0, nrow = 2, ncol = length(component(fit, "beta_est")))
contrast[1, 2] <- contrast[2, 3] <- 1

df_md(fit, contrast)
```

And for the Kenward-Roger adjustment:

```{r md_kr}
df_md(fit_kr, contrast)
```

We see that for the multi-dimensional contrast we get slightly different
denominator degrees of freedom for the two adjustment methods.

Also the simpler Residual and Between-Within `method` choices can be used of
course together with multidimensional contrasts.

## Support for emmeans

This package includes methods that allow `mmrm` objects to be used with the
`emmeans` package. `emmeans` computes estimated marginal means (also called
least-square means) for the coefficients of the MMRM. For example, in order
to see the least-square means by visit and by treatment arm:

```{r emmeans}
library(emmeans)
lsmeans_by_visit <- emmeans(fit, ~ ARMCD | AVISIT)
lsmeans_by_visit
```

Note that the degrees of freedom choice is inherited here from the initial `mmrm`
fit.
Furthermore, we can also obtain the differences between the treatment arms for each visit
by applying `pairs()` on the object returned by `emmeans()` earlier:

```{r pdiff}
pairs(lsmeans_by_visit, reverse = TRUE)
```

(This is similar like the `pdiff` option in SAS `PROC MIXED`.)
Note that we use here the `reverse` argument to obtain treatment minus
placebo results, instead of placebo minus treatment results.

To further obtain the confidence interval of the least square mean differences, we can apply
`confint()` on the result returned by `pairs()` .

This is similar to the `LSMEANS` in SAS, with `CL` and `DIFF` options.

```{r pdiffci}
confint(pairs(lsmeans_by_visit, reverse = TRUE))
```

## Support for car

This package includes methods that allow `mmrm` objects to be used with
`car::Anova()`. This function conducts type II/III hypothesis testing for
the effects in `mmrm` models, using either F-tests (default) or Chi-squared tests. 

### Mathematical basis

For each effect, the Chi-squared test statistic is calculated using:
$$
\chi^2=[\mathbf{L}\cdot b]^T\cdot [\mathbf{L}\cdot\mathbf{V}\cdot\mathbf{L}^T]^{-1}\cdot\mathbf{L}\cdot b
$$
where $\mathbf{L}$ is the desired contrast matrix, $b$ is a one-column matrix containing the coefficients of the non-aliased terms in the model, and $\mathbf{V}$ is the variance-covariance matrix of the coefficients.

The F-test statistic is calculated by dividing the Chi-squared test statistic by the numerator degrees of freedom $\text{df}_\text{num}$, which is equal to the number of parameters associated with the effect and therefore the number of rows in the contrast matrix $\mathbf{L}$. It is also multiplied by a scaling factor $\lambda$ (e.g., when utilizing the adjusted Kenward-Roger degrees of freedom), which can be set to 1 if not needed:

$$
F = \lambda\frac{\chi^2}{\text{df}_\text{num}}
$$

### Examples

In order to see if the used covariates are related to the response using a type II test:

```{r car_type2}
library(car)
Anova(fit, type = "II")
```

Note that for the F-test, the denominator degrees of freedom choice is inherited here from the initial `mmrm` fit.
In addition, please note that if you see results that are slightly different from SAS, it could be because the reference level is set differently for categorical covariates.

We can also use type III hypothesis testing, this time choosing a Chi-squared test statistic:

```{r car_type3}
Anova(fit, type = "III", test.statistic = "Chisq")
```
