---
title: "mcvis: Multi-collinearity Visualization"
author: "Kevin Wang, Chen Lin and Samuel Mueller"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    fig_height: 6
    fig_width: 8
vignette: >
  %\VignetteIndexEntry{mcvis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```



# Introduction

The `mcvis` package provides functions for detecting multi-collinearity (also known as collinearity) in linear regression. In simple terms, the `mcvis` method investigates variables with strong influences on collinearity in a graphical manner. 


# Basic usage 

Suppose that we have a simple scenario that one predictor $X_1$ is almost linearly dependent on another two predictors $X_2$ and $X_3$, thus $X_1$ is strongly correlated with these two predictors. The dependence among these three variables is a sufficient cause for collinearity which can be shown through large variances of estimated model parameters in linear regression. We illustrate this with a simple example:

```{r setup, warning=FALSE, message=FALSE}
## Simulating some data
set.seed(1)
p = 6
n = 100

X = matrix(rnorm(n*p), ncol = p)
X[,1] = X[,2] + X[,3] + rnorm(n, 0, 0.01)

y = rnorm(n)
summary(lm(y ~ X))
```


The `mcvis` method highlights the major collinearity-causing variables on a bipartite graph. There are three major components of this graph:
 + the top row renders the "tau" statistics and by default, only one tau statistic is shown ($\tau_p$, where $p$ is the number of predictors). This tau statistic measures the extent of collinearity in the data and relates to the eigenvalues of the correlation matrix in $X$.
 + the bottom row renders all original predictors.
 + the two rows are linked through the MC-indices that we have developed, which are represented as lines of different shades and thickness. Darker lines implies larger values of the MC-index indicate what predictor contribute more to causing collinearity. 
 
 
If you are interested in how the tau statistics and the resampling-based MC-index are calculated, our paper is published as *Lin, C., Wang, K. Y. X., & Mueller, S. (2020). mcvis: A new framework for collinearity discovery, diagnostic and visualization. _Journal of Computational and Graphical Statistics_*

```{r}
library(mcvis)
mcvis_result = mcvis(X = X)

mcvis_result
```

This matrix of MC-indices is the main numeric output of `mcvis` and our visualisation techniques are focused on visualising this matrix. Below is a bipartite graph visualising the last row of this matrix, which is the main visualisation plot of `mcvis`. 

```{r}
plot(mcvis_result)
```

We also provide a igraph version of the mcvis bipartite graph. 

```{r}
plot(mcvis_result, type = "igraph")
```


# (Extension) why not just look at the correlation matrix?

In practice, high correlation between variables is not a necessary criterion for collinearity. In the `mplot` package (Tarr et. al. 2018), a simulated data was created with many of its columns being a linear combination of other columns plus noise. In this case, the cause of the collinearity is not clear from the correlation matrix. 

The `mcvis` visualisation plot identified that the 8th variable (x8) is the main cause of collinearity of this data. Upon consultation with the data generation in this simulation, we see that x8 is a linear combination of all other predictor variables (plus noise). This knowledge can provide important guidance to statistical interpretations of model selection results. 

```{r}
## Simulation taken from the `mplot` package.
## Generating a data with multi-collinearity. 
n=50
set.seed(8) # a seed of 2 also works
x1 = rnorm(n,0.22,2)
x7 = 0.5*x1 + rnorm(n,0,sd=2)
x6 = -0.75*x1 + rnorm(n,0,3)
x3 = -0.5-0.5*x6 + rnorm(n,0,2)
x9 = rnorm(n,0.6,3.5)
x4 = 0.5*x9 + rnorm(n,0,sd=3)
x2 = -0.5 + 0.5*x9 + rnorm(n,0,sd=2)
x5 = -0.5*x2+0.5*x3+0.5*x6-0.5*x9+rnorm(n,0,1.5)
x8 = x1 + x2 -2*x3 - 0.3*x4 + x5 - 1.6*x6 - 1*x7 + x9 +rnorm(n,0,0.5)
y = 0.6*x8 + rnorm(n,0,2)
artificialeg = round(data.frame(x1,x2,x3,x4,x5,x6,x7,x8,x9,y),1)
```

```{r}
X = artificialeg[,1:9]
round(cor(X), 2)

mcvis_result = mcvis(X)
mcvis_result
plot(mcvis_result)
```


# Shiny implementation

We also offer a shiny app implementation of `mcvis` in our package. Suppose that we have a `mcvis_result` object stored in the memory of `R`. You can simply call the function `shiny_mcvis` to load up a Shiny app. 

```{r}
class(mcvis_result)
```

```{r, eval = FALSE}
shiny_mcvis(mcvis_result)
```

# Reference

+ *Lin, C., Wang, K. Y. X., & Mueller, S. (2020). mcvis: A new framework for collinearity discovery, diagnostic and visualization. _Journal of Computational and Graphical Statistics_, In Press. URL: https://doi.org/10.1080/10618600.2020.1779729*

+ *Tarr G, Mueller S, Welsh AH (2018). mplot: An R Package for Graphical Model Stability and Variable
Selection Procedures. Journal of Statistical Software, 83(9), 1-28. URL: https://doi.org/10.18637/jss.v083.i09*



# Session Info

```{r}
sessionInfo()
```

