% \VignetteIndexEntry{Quick start guide}
% \VignettePackage{grpreg}
% \VignetteEngine{knitr::knitr}

\documentclass{article}

\usepackage{amsmath}
\usepackage{fullpage}
\usepackage[colorlinks=true, urlcolor=blue, pdfborder={0 0 0}]{hyperref}

\title{Quick start guide for the {\tt grpreg} package}
\author{Patrick Breheny}
\date{\today}

<<include=FALSE, purl=FALSE>>=
require(grpreg)
require(knitr)
opts_chunk$set(background = "gray90")
opts_chunk$set(prompt = TRUE)
opts_chunk$set(comment = NA)
opts_template$set(fig = list(fig.height=4, fig.width=5, out.width='.6\\linewidth', fig.align='center'))
@

\begin{document}
\maketitle

This guide is intended to briefly demonstrate the basic usage of {\tt grpreg}.  For more details, see the other vignettes, documentation for individual functions, and the references.

{\tt grpreg} comes with an example data set, {\tt Birthwt}.  The outcome, \verb|Birthwt$bwt|, records the birth weights (in kg) of 189 babies.  The following predictors are available:

<<>>=
data(Birthwt)
head(Birthwt$X, n=3)
@

This is a design matrix derived from the original data set, in which several terms have been expanded.  For example, there are multiple indicator functions for race (``other'' being the reference group) and several continuous factors such as age have been expanded using polynomial contrasts (splines would give a similar structure).  Hence, the columns of the design matrix are {\em grouped}; this is what grpreg is designed for.  The grouping information is encoded as follows:

<<>>=
Birthwt$group
@

Here, groups are given as a factor; unique integer codes (which are essentially unlabeled factors) and character vectors are also allowed\footnote{Character vectors are not an ideal choice, however, as the order of the groups is left unspecified, which can lead to ambiguity if you also try to set the {\tt group.multiplier} option.}.  To fit a group lasso model to this data:

<<>>=
X <- Birthwt$X
y <- Birthwt$bwt
group <- Birthwt$group
fit <- grpreg(X, y, group, penalty="grLasso")
@

We can then plot the coefficient paths with

<<opts.label='fig'>>=
plot(fit)
@

Notice that when a group enters the model (e.g., the green group), all of its coefficients become nonzero; this is what happens with group lasso models.  To see what the coefficients are, we could use the {\tt coef} function:

<<opts.label='fig'>>=
coef(fit, lambda=0.05)
@

Note that the number of physician's visits ({\tt ftv}) is not included in the model at $\lambda=0.05$.  Typically, one would carry out cross-validation for the purposes of carrying out inference on the predictive accuracy of the model at various values of $\lambda$.

<<opts.label='fig'>>=
cvfit <- cv.grpreg(X, y, group, penalty="grLasso")
plot(cvfit)
@

The coefficients corresponding to the value of $\lambda$ that minimizes the cross-validation error can be obtained via {\tt coef}:

<<>>=
coef(cvfit)
@

Predicted values can be obtained via {\tt predict}, which has a number of options:

<<>>=
predict(cvfit, X=head(X))
predict(cvfit, type="ngroups")
@

Note that the original fit (to the full data set) is returned as \verb|cvfit$fit|; it is not necessary to call both \verb|grpreg| and {\tt cv.grpreg} to analyze a data set.  Several other penalties are available, as are methods for logistic regression and Cox proportional hazards regression.

\end{document}
