---
title: "Using the MVLM Package"
author: "Daniel McArtor"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the MVLM Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Many research questions involve the collection of multivariate outcome data. A common goal in these scenarios is the identification of predictors $\left(\mathbf{X}_{n \times p}\right)$ that are associated with the multivariate outcome $\left(\mathbf{Y}_{n \times q}\right)$. Methods such as multivariate multiple regression (MMR) and multivariate analysis of variance (MANOVA) are typical approaches to accomplishing this goal.

This package allows users to conduct MMR and MANOVA in conjunction with the the analytic p-values proposed by McArtor et al. (under review), in lieu of classical $p$-values based on statistics such as Wilks' Lambda and Pillai's Trace.

The remainder of this vignette is designed to illustrate the use of the *MVLM* package, which is straight-forward to use. For further technical details of the methods being implemented, please refer to McArtor et al. (under review).

## 1. Fitting the Model
To illustrate this package, we include the toy dataset *mvlmdata*, which is comprised of five continuous outcome variables $\mathbf{Y}$ and three predictors $\mathbf{X}$ measured on 200 subjects. All outcome variables are standardized to have unit variance.

The first predictors is continuous, the second is an unordered categorical variable (variable type *factor*) with three factors, and the third is an ordered categorical variable with four factors (variable type *ordered*). By default, *mvlm()* uses contrast ("sum") coding to test the effects of unordered categorical variables and polynomial contrasts to test ordered categorical variables. 

The function *mvlm()* can be used to test the association of $\mathbf{X}$ and $\mathbf{Y}$. Consider the main-effects only model and the model containing all two-way interaction terms:
```{r, message = F}
library(MVLM)
data(mvlmdata)
Y <- as.matrix(Y.mvlm)

# Main effects
mvlm.res <- mvlm(Y ~ Cont + Cat + Ord, data = X.mvlm)
summary(mvlm.res)

# Two-Way Interactions
mvlm.res.int <- mvlm(Y ~ .^2, data = X.mvlm)
summary(mvlm.res.int)
```
The results of the second model illustrate that the ordered categorical variable has a small but significant conditional main effect on the outcome variables. Perhaps more interestingly, the continuous and categorical variable are shown to have a strong two-way interaction effect that influences the outcome variables.

Note that the tests involving the main effect of the categorical predictors utilize two and three degrees of freedom, reflecting the fact that there are four levels of the factor.  Similarly, the interaction terms utilize the same number of numerator degrees of freedom that are used in the standard linear model. 

If a user is interested in testing the effect of specific dummy/contrast codes of a categorical predictor separately, the following approach could be used. First, compute a design matrix that includes the specific contrasts of interest. Second, transform that contrast matrix into a data frame where all entries are numeric. Third, regress $\mathbf{Y}$ onto that matrix directly. This approach is illustrated in the following code which uses the R defaults of dummy-codes for *Cat* and polynomial coding for *Ord*.
```{r, message = F}
# --- Main Effects Only --- #

# Get dummy-codes for the categorical predictor using the first group as a
# reference category, and then remove the leading column of 1's
X.dum <- model.matrix(~., data = X.mvlm)[,-1]
X.dum <- as.data.frame(X.dum)

# Use these reformatted data in MMR
mvlm.res.dum <- mvlm(Y ~ ., data = X.dum)
summary(mvlm.res.dum)

# --- Interaction Model --- #

# Get dummy-codes for the categorical predictor using the first group as a
# reference category, and then remove the leading column of 1's
X.dum.int <- model.matrix(~.^2, data = X.mvlm)[,-1]
X.dum.int <- as.data.frame(X.dum.int)

# Use these reformatted data in MMR
mvlm.res.dum.int <- mvlm(Y ~ ., data = X.dum.int)
summary(mvlm.res.dum.int)
```
Note that, appropriately, the overall fit (i.e. omnibus effect) of these models mirror the fit of the models originally fit to the data. This is because the original multiple-DF tests were simultaneously testing the set of contrasts that combined to form the corresponding omnibus effect. For example, in the main effects models, the original three-DF effect of the ordered predictor amounts to a simultaneous test of the linear, quadratic, and cubic effects.

### 2. Fitted values, residuals, and predictions
This package also provides means for computing fitted values, residuals, and predictions for new data. Fitted values and residuals are straight-forward:

```{r, message = F}
Y.hat <- fitted(mvlm.res)
Y.resid <- residuals(mvlm.res)
```
```{r, message = F}
round(cor(X.dum, Y.hat), 4)
round(cor(X.dum, Y.resid), 4)
```

Predictions can also be made on new data:
```{r, message = F, fig.width = 6.5, fig.height = 4.333}
# Split the data  - one part to build the model, the other to predict
X.train <- X.mvlm[1:150,]
Y.train <- as.matrix(Y.mvlm[1:150,])
X.test <- X.mvlm[151:200,]
Y.test <- as.matrix(Y.mvlm[151:200,])

# Fit the model to the training set
mvlm.res.pred <- mvlm(Y.train ~ ., data = X.train)

# Get predictions
Y.test.pred <- predict(mvlm.res.pred, newdata = X.test)

# Plot the predicted values vs. the true values in the test set
par(mfrow = c(2,3))
for(k in 1:5){
  plot(Y.test.pred[,k], Y.test[,k], main = paste("Outcome Variable", k),
       xlab = 'Predicted Value', ylab = 'Observed Value')
}
```

## 3. References
Davies, R. B. (1980). The Distribution of a Linear Combination of chi-square Random Variables. *Journal of the Royal Statistical Society. Series C (Applied Statistics), 29*(3), 323–333.

Duchesne, P., & De Micheaux, P.L. (2010). Computing the distribution of quadratic forms: Further comparisons between the Liu-Tang-Zhang approximation and exact methods. *Computational Statistics and Data Analysis, 54*(4), 858–862.

McArtor, D. B., Grasman, R. P. P. P., Lubke, G. H., & Bergeman, C. S. (submitted). A new approach to conducting linear model hypothesis tests with a multivariate outcome.
