---
title: "Hierarchical Integrative Group LASSO"
author: "Alexander Rix"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Hierarchical Integrative Group LASSO}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
## Introduction
Environmental health studies are increasingly measuring multiple pollutants
to characterize the joint health effects attributable to exposure mixtures.
However, the underlying dose-response relationship between toxicants and
health outcomes of interest may be highly nonlinear, with possible nonlinear
interaction effects. Hierarchical integrative group least absolute shrinkage
and selection operator (HiGLASSO) is a general framework to identify
noteworthy nonlinear main and interaction effects in the presence of group
structures among a set of exposures.

The R package `higlasso` contains an efficient Rcpp implementation of HiGLASSO
and provides a cross validated variant, `cv.higlasso` to assist in proper
interaction detection. That being said, HiGLASSO is a time intensive algorithm
and hence there is a limit to how many variables can used at once. `higlasso`
is suitable to use on medium sized environmental health datasets.

## Installation
`higlasso` can be installed from CRAN

```{r, eval = F}
install.packages("higlasso")
```

`higlasso` can also be installed via Github using `devtools`

```{r, eval = F}
# install.packages("devtools")
devtools::install_github("umich-cphds/higlasso")
```
You'll need a working C++11 compiler, which can obtained by installing Xcode on
MacOS, and RTools on Windows. The Github version may have bug fixes or new
features than the CRAN version doesn't have, so it may be a good idea to take a
look.

## Example
`higlasso` comes with an example data.frame, `higlasso.df` that is based off the
first simulation case in the paper. It contains a numeric response and 10
covariates, X1 - X10.

```{r, eval = T}
library(higlasso)

set.seed(48109)

X <- as.matrix(higlasso.df[, paste0("V", 1:7)])
Y <- higlasso.df$Y
Z <- matrix(1, nrow(X))

# This can take a bit of time, so we run the example with nondefault
# parameters to speed up the process
fit <- cv.higlasso(Y, X, Z)

print(fit)
```

## References
A Hierarchical Integrative Group LASSO (HiGLASSO) Framework for Analyzing
Environmental Mixtures. Jonathan Boss, Alexander Rix, Yin-Hsiu Chen, Naveen N.
Narisetty, Zhenke Wu, Kelly K. Ferguson, Thomas F. McElrath, John D. Meeker,
Bhramar Mukherjee. 2020.
arXiv:2003.12844

##Contact information

If you would like to report a bug in the code, ask questions, or send
requests/suggestions e-mail Jonathan Boss at `bossjona@umich.edu` or Alexander
Rix at `alexrix@umich.edu`.