% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/doc-rstanarm-package.R
\docType{package}
\name{rstanarm-package}
\alias{rstanarm}
\alias{rstanarm-package}
\title{Applied Regression Modeling via RStan}
\description{
\if{html}{
   \figure{stanlogo.png}{options: width="50" alt="https://mc-stan.org/about/logo/"}
   \emph{Stan Development Team}
}

The \pkg{rstanarm} package is an appendage to the \pkg{rstan} package that
enables many of the most common applied regression models to be estimated
using Markov Chain Monte Carlo, variational approximations to the posterior
distribution, or optimization. The \pkg{rstanarm} package allows these models
to be specified using the customary R modeling syntax (e.g., like that of
\code{\link[stats]{glm}} with a \code{formula} and a \code{data.frame}).

The sections below provide an overview of the modeling functions and
estimation algorithms used by \pkg{rstanarm}.
}
\details{
The set of models supported by \pkg{rstanarm} is large (and will continue to
grow), but also limited enough so that it is possible to integrate them
tightly with the \code{\link{pp_check}} function for graphical posterior
predictive checks with \pkg{\link[bayesplot:bayesplot-package]{bayesplot}} and the
\code{\link{posterior_predict}} function to easily estimate the effect of
specific manipulations of predictor variables or to predict the outcome in a
training set.

The objects returned by the \pkg{rstanarm} modeling functions are called
\code{\link[=stanreg-objects]{stanreg}} objects. In addition to all of the
typical \code{\link[=stanreg-methods]{methods}} defined for fitted model
objects, stanreg objects can be passed to the \code{\link[loo]{loo}} function
in the \pkg{loo} package for model comparison or to the
\code{\link[shinystan]{launch_shinystan}} function in the \pkg{shinystan}
package in order to visualize the posterior distribution using the ShinyStan
graphical user interface. See the \pkg{rstanarm} vignettes for more details
about the entire process.
}
\section{Prior distributions}{

See \link[=priors]{priors help page} and the vignette
\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior Distributions for rstanarm Models}}
for an overview of the various choices the user can make for prior
distributions. The package vignettes for the modeling functions also provide
examples of using many of the available priors as well as more detailed
descriptions of some of the novel priors used by \pkg{rstanarm}.
}

\section{Modeling functions}{

The model estimating functions are described in greater detail in their
individual help pages and vignettes. Here we provide a very brief
overview:

\describe{
 \item{\code{\link{stan_lm}}, \code{stan_aov}, \code{stan_biglm}}{
  Similar to \code{\link[stats]{lm}} or \code{\link[stats]{aov}} but with
  novel regularizing priors on the model parameters that are driven by prior
  beliefs about \eqn{R^2}, the proportion of variance in the outcome
  attributable to the predictors in a linear model.
 }
 \item{\code{\link{stan_glm}}, \code{stan_glm.nb}}{
 Similar to \code{\link[stats]{glm}} but with various possible prior
 distributions for the coefficients and, if applicable, a prior distribution
 for any auxiliary parameter in a Generalized Linear Model (GLM) that is
 characterized by a \code{\link[stats]{family}} object (e.g. the shape
 parameter in Gamma models). It is also possible to estimate a negative
 binomial model in a similar way to the \code{\link[MASS]{glm.nb}} function
 in the \pkg{MASS} package.
 }
 \item{\code{\link{stan_glmer}}, \code{stan_glmer.nb}, \code{stan_lmer}}{
  Similar to the \code{\link[lme4]{glmer}}, \code{\link[lme4]{glmer.nb}} and
  \code{\link[lme4]{lmer}} functions in the \pkg{lme4} package in that GLMs
  are augmented to have group-specific terms that deviate from the common
  coefficients according to a mean-zero multivariate normal distribution with
  a highly-structured but unknown covariance matrix (for which \pkg{rstanarm}
  introduces an innovative prior distribution). MCMC provides more
  appropriate estimates of uncertainty for models that consist of a mix of
  common and group-specific parameters.
 }
 \item{\code{\link{stan_nlmer}}}{
  Similar to \code{\link[lme4]{nlmer}} in the \pkg{lme4} package for 
  nonlinear "mixed-effects" models, but the group-specific coefficients 
  have flexible priors on their unknown covariance matrices.
 }
 \item{\code{\link{stan_gamm4}}}{
  Similar to \code{\link[gamm4]{gamm4}} in the \pkg{gamm4} package, which
  augments a GLM (possibly with group-specific terms) with nonlinear smooth
  functions of the predictors to form a Generalized Additive Mixed Model
  (GAMM). Rather than calling \code{\link[lme4]{glmer}} like
  \code{\link[gamm4]{gamm4}} does, \code{\link{stan_gamm4}} essentially calls
  \code{\link{stan_glmer}}, which avoids the optimization issues that often
  crop up with GAMMs and provides better estimates for the uncertainty of the
  parameter estimates.
 }
 \item{\code{\link{stan_polr}}}{
  Similar to \code{\link[MASS]{polr}} in the \pkg{MASS} package in that it
  models an ordinal response, but the Bayesian model also implies a prior
  distribution on the unknown cutpoints. Can also be used to model binary
  outcomes, possibly while estimating an unknown exponent governing the
  probability of success.
 }
 \item{\code{\link{stan_betareg}}}{
  Similar to \code{\link[betareg]{betareg}} in that it models an outcome that
  is a rate (proportion) but, rather than performing maximum likelihood
  estimation, full Bayesian estimation is performed by default, with
  customizable prior distributions for all parameters.
 }
 \item{\code{\link{stan_clogit}}}{
   Similar to \code{\link[survival]{clogit}} in that it models an binary outcome
   where the number of successes and failures is fixed within each stratum by
   the research design. There are some minor syntactical differences relative
   to \code{\link[survival]{clogit}} that allow \code{stan_clogit} to accept
   group-specific terms as in \code{\link{stan_glmer}}.
 }
 \item{\code{\link{stan_mvmer}}}{
   A multivariate form of \code{\link{stan_glmer}}, whereby the user can
   specify one or more submodels each consisting of a GLM with group-specific 
   terms. If more than one submodel is specified (i.e. there is more than one
   outcome variable) then a dependence is induced by assuming that the
   group-specific terms for each grouping factor are correlated across submodels. 
 }
 \item{\code{\link{stan_jm}}}{
   Estimates shared parameter joint models for longitudinal and time-to-event 
   (i.e. survival) data. The joint model can be univariate (i.e. one longitudinal 
   outcome) or multivariate (i.e. more than one longitudinal outcome). A variety 
   of parameterisations are available for linking the longitudinal and event 
   processes (i.e. a variety of association structures).      
 }
}
}

\section{Estimation algorithms}{

The modeling functions in the \pkg{rstanarm} package take an \code{algorithm}
argument that can be one of the following:
\describe{
 \item{\strong{Sampling} (\code{algorithm="sampling"})}{
 Uses Markov Chain Monte Carlo (MCMC) --- in particular, Hamiltonian Monte
 Carlo (HMC) with a tuned but diagonal mass matrix --- to draw from the
 posterior distribution of the parameters. See \code{\link[rstan:stanmodel-method-sampling]{sampling}}
 (\pkg{rstan}) for more details. This is the slowest but most reliable of the
 available estimation algorithms and it is \strong{the default and
 recommended algorithm for statistical inference.}
 }
 \item{\strong{Mean-field} (\code{algorithm="meanfield"})}{
 Uses mean-field variational inference to draw from an approximation to the
 posterior distribution. In particular, this algorithm finds the set of
 independent normal distributions in the unconstrained space that --- when
 transformed into the constrained space --- most closely approximate the
 posterior distribution. Then it draws repeatedly from these independent
 normal distributions and transforms them into the constrained space. The
 entire process is much faster than HMC and yields independent draws but
 \strong{is not recommended for final statistical inference}. It can be
 useful to narrow the set of candidate models in large problems, particularly
 when specifying \code{QR=TRUE} in \code{\link{stan_glm}},
 \code{\link{stan_glmer}}, and \code{\link{stan_gamm4}}, but is \strong{only
 an approximation to the posterior distribution}.
 }
 \item{\strong{Full-rank} (\code{algorithm="fullrank"})}{
 Uses full-rank variational inference to draw from an approximation to the
 posterior distribution by finding the multivariate normal distribution in
 the unconstrained space that --- when transformed into the constrained space
 --- most closely approximates the posterior distribution. Then it draws
 repeatedly from this multivariate normal distribution and transforms the
 draws into the constrained space. This process is slower than meanfield
 variational inference but is faster than HMC. Although still an
 approximation to the posterior distribution and thus \strong{not recommended
 for final statistical inference}, the approximation is more realistic than
 that of mean-field variational inference because the parameters are not
 assumed to be independent in the unconstrained space. Nevertheless, fullrank
 variational inference is a more difficult optimization problem and the
 algorithm is more prone to non-convergence or convergence to a local
 optimum.
 }
 \item{\strong{Optimizing} (\code{algorithm="optimizing"})}{
 Finds the posterior mode using a C++ implementation of the LBGFS algorithm.
 See \code{\link[rstan:stanmodel-method-optimizing]{optimizing}} for more details. If there is no prior
 information, then this is equivalent to maximum likelihood, in which case
 there is no great reason to use the functions in the \pkg{rstanarm} package
 over the emulated functions in other packages. However, if priors are
 specified, then the estimates are penalized maximum likelihood estimates,
 which may have some redeeming value. Currently, optimization is only
 supported for \code{\link{stan_glm}}.
 }
}
}

\references{
Bates, D., Maechler, M., Bolker, B., and Walker, S. (2015). Fitting linear 
mixed-Effects models using lme4. \emph{Journal of Statistical Software}.
67(1), 1--48.

Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari,
  A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC
  Press, London, third edition. \url{https://stat.columbia.edu/~gelman/book/}

Gelman, A. and Hill, J. (2007). \emph{Data Analysis Using
  Regression and Multilevel/Hierarchical Models.} Cambridge University Press,
  Cambridge, UK. \url{https://stat.columbia.edu/~gelman/arm/}

Stan Development Team. \emph{Stan Modeling Language Users Guide and
Reference Manual.} \url{https://mc-stan.org/users/documentation/}.

Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical
  Bayesian model evaluation using leave-one-out cross-validation and WAIC.
  \emph{Statistics and Computing}. 27(5), 1413--1432.
  doi:10.1007/s11222-016-9696-4. arXiv preprint:
  \url{https://arxiv.org/abs/1507.04544}

  Yao, Y., Vehtari, A., Simpson, D., and Gelman, A. (2018) Using
  stacking to average Bayesian predictive distributions. \emph{Bayesian
  Analysis}, advance publication,  \doi{10.1214/17-BA1091}.

Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and
  Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat.
  Soc. A}, 182: 389-402. doi:10.1111/rssa.12378,
  \href{https://arxiv.org/abs/1709.01449}{arXiv preprint},
  \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub})

Muth, C., Oravecz, Z., and Gabry, J. (2018)
User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan.
\emph{The Quantitative Methods for Psychology}. 14(2), 99--119.
\url{https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf}
}
\seealso{
\itemize{
  \item \url{https://mc-stan.org/} for more information on the Stan C++
  package used by \pkg{rstanarm} for model fitting.
  \item \url{https://github.com/stan-dev/rstanarm/issues/} to submit a bug
  report or feature request.
  \item \url{https://discourse.mc-stan.org} to ask a
  question about \pkg{rstanarm} on the Stan-users forum.
}
}
\author{
\strong{Maintainer}: Ben Goodrich \email{benjamin.goodrich@columbia.edu}

Authors:
\itemize{
  \item Jonah Gabry \email{jsg2201@columbia.edu}
}

Other contributors:
\itemize{
  \item Imad Ali [contributor]
  \item Sam Brilleman [contributor]
  \item Jacqueline Buros Novik (R/stan_jm.R) [contributor]
  \item AstraZeneca (R/stan_jm.R) [contributor]
  \item Trustees of Columbia University [copyright holder]
  \item Simon Wood (R/stan_gamm4.R) [copyright holder]
  \item R Core Deveopment Team (R/stan_aov.R) [copyright holder]
  \item Douglas Bates (R/pp_data.R) [copyright holder]
  \item Martin Maechler (R/pp_data.R) [copyright holder]
  \item Ben Bolker (R/pp_data.R) [copyright holder]
  \item Steve Walker (R/pp_data.R) [copyright holder]
  \item Brian Ripley (R/stan_aov.R, R/stan_polr.R) [copyright holder]
  \item William Venables (R/stan_polr.R) [copyright holder]
  \item Paul-Christian Burkner \email{paul.buerkner@gmail.com} (R/misc.R) [copyright holder]
}

}
