From a51659dd5b16a044624395c450b62e211400bb79 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Wed, 5 Jun 2024 11:17:30 +0300 Subject: [PATCH] Add rd files --- .gitignore | 1 - DESCRIPTION | 2 +- cleanup | 5 - cleanup.win | 6 - man/QR-argument.Rd | 46 +++ man/adapt_delta.Rd | 41 ++ man/as.matrix.stanreg.Rd | 80 ++++ man/available-algorithms.Rd | 67 ++++ man/available-models.Rd | 95 +++++ man/bayes_R2.stanreg.Rd | 61 +++ man/example_jm.Rd | 32 ++ man/example_model.Rd | 32 ++ man/family.stanmvreg.Rd | 17 + man/family.stanreg.Rd | 15 + man/formula.stanreg.Rd | 18 + man/get_y.Rd | 29 ++ man/kfold.stanreg.Rd | 127 ++++++ man/launch_shinystan.stanreg.Rd | 127 ++++++ man/log_lik.stanreg.Rd | 82 ++++ man/logit.Rd | 20 + man/loo.stanreg.Rd | 259 ++++++++++++ man/loo_predict.stanreg.Rd | 107 +++++ man/model.frame.stanmvreg.Rd | 19 + man/model.frame.stanreg.Rd | 17 + man/model.matrix.stanreg.Rd | 15 + man/neg_binomial_2.Rd | 36 ++ man/pairs.stanreg.Rd | 114 ++++++ man/plot.predict.stanjm.Rd | 122 ++++++ man/plot.stanreg.Rd | 169 ++++++++ man/plot.survfit.stanjm.Rd | 147 +++++++ man/posterior_interval.stanreg.Rd | 113 ++++++ man/posterior_linpred.stanreg.Rd | 103 +++++ man/posterior_predict.stanreg.Rd | 174 ++++++++ man/posterior_survfit.Rd | 287 +++++++++++++ man/posterior_traj.Rd | 301 ++++++++++++++ man/posterior_vs_prior.Rd | 158 ++++++++ man/pp_check.stanreg.Rd | 150 +++++++ man/pp_validate.Rd | 87 ++++ man/predict.stanreg.Rd | 42 ++ man/predictive_error.stanreg.Rd | 95 +++++ man/predictive_interval.stanreg.Rd | 80 ++++ man/print.stanreg.Rd | 68 ++++ man/print.survfit.stanjm.Rd | 21 + man/prior_summary.stanreg.Rd | 122 ++++++ man/priors.Rd | 506 +++++++++++++++++++++++ man/ps_check.Rd | 80 ++++ man/reexports.Rd | 16 + man/rstanarm-datasets.Rd | 202 ++++++++++ man/rstanarm-deprecated.Rd | 43 ++ man/rstanarm-package.Rd | 266 ++++++++++++ man/se.Rd | 23 ++ man/stan_betareg.Rd | 254 ++++++++++++ man/stan_biglm.Rd | 178 +++++++++ man/stan_clogit.Rd | 174 ++++++++ man/stan_gamm4.Rd | 288 +++++++++++++ man/stan_glm.Rd | 434 ++++++++++++++++++++ man/stan_glmer.Rd | 275 +++++++++++++ man/stan_jm.Rd | 622 +++++++++++++++++++++++++++++ man/stan_lm.Rd | 224 +++++++++++ man/stan_mvmer.Rd | 189 +++++++++ man/stan_nlmer.Rd | 199 +++++++++ man/stan_polr.Rd | 203 ++++++++++ man/stanmvreg-methods.Rd | 149 +++++++ man/stanreg-draws-formats.Rd | 64 +++ man/stanreg-methods.Rd | 141 +++++++ man/stanreg-objects.Rd | 160 ++++++++ man/stanreg_list.Rd | 45 +++ man/summary.stanreg.Rd | 126 ++++++ man/terms.stanmvreg.Rd | 17 + man/terms.stanreg.Rd | 15 + 70 files changed, 8589 insertions(+), 13 deletions(-) delete mode 100755 cleanup delete mode 100755 cleanup.win create mode 100644 man/QR-argument.Rd create mode 100644 man/adapt_delta.Rd create mode 100644 man/as.matrix.stanreg.Rd create mode 100644 man/available-algorithms.Rd create mode 100644 man/available-models.Rd create mode 100644 man/bayes_R2.stanreg.Rd create mode 100644 man/example_jm.Rd create mode 100644 man/example_model.Rd create mode 100644 man/family.stanmvreg.Rd create mode 100644 man/family.stanreg.Rd create mode 100644 man/formula.stanreg.Rd create mode 100644 man/get_y.Rd create mode 100644 man/kfold.stanreg.Rd create mode 100644 man/launch_shinystan.stanreg.Rd create mode 100644 man/log_lik.stanreg.Rd create mode 100644 man/logit.Rd create mode 100644 man/loo.stanreg.Rd create mode 100644 man/loo_predict.stanreg.Rd create mode 100644 man/model.frame.stanmvreg.Rd create mode 100644 man/model.frame.stanreg.Rd create mode 100644 man/model.matrix.stanreg.Rd create mode 100644 man/neg_binomial_2.Rd create mode 100644 man/pairs.stanreg.Rd create mode 100644 man/plot.predict.stanjm.Rd create mode 100644 man/plot.stanreg.Rd create mode 100644 man/plot.survfit.stanjm.Rd create mode 100644 man/posterior_interval.stanreg.Rd create mode 100644 man/posterior_linpred.stanreg.Rd create mode 100644 man/posterior_predict.stanreg.Rd create mode 100644 man/posterior_survfit.Rd create mode 100644 man/posterior_traj.Rd create mode 100644 man/posterior_vs_prior.Rd create mode 100644 man/pp_check.stanreg.Rd create mode 100644 man/pp_validate.Rd create mode 100644 man/predict.stanreg.Rd create mode 100644 man/predictive_error.stanreg.Rd create mode 100644 man/predictive_interval.stanreg.Rd create mode 100644 man/print.stanreg.Rd create mode 100644 man/print.survfit.stanjm.Rd create mode 100644 man/prior_summary.stanreg.Rd create mode 100644 man/priors.Rd create mode 100644 man/ps_check.Rd create mode 100644 man/reexports.Rd create mode 100644 man/rstanarm-datasets.Rd create mode 100644 man/rstanarm-deprecated.Rd create mode 100644 man/rstanarm-package.Rd create mode 100644 man/se.Rd create mode 100644 man/stan_betareg.Rd create mode 100644 man/stan_biglm.Rd create mode 100644 man/stan_clogit.Rd create mode 100644 man/stan_gamm4.Rd create mode 100644 man/stan_glm.Rd create mode 100644 man/stan_glmer.Rd create mode 100644 man/stan_jm.Rd create mode 100644 man/stan_lm.Rd create mode 100644 man/stan_mvmer.Rd create mode 100644 man/stan_nlmer.Rd create mode 100644 man/stan_polr.Rd create mode 100644 man/stanmvreg-methods.Rd create mode 100644 man/stanreg-draws-formats.Rd create mode 100644 man/stanreg-methods.Rd create mode 100644 man/stanreg-objects.Rd create mode 100644 man/stanreg_list.Rd create mode 100644 man/summary.stanreg.Rd create mode 100644 man/terms.stanmvreg.Rd create mode 100644 man/terms.stanreg.Rd diff --git a/.gitignore b/.gitignore index e61a23194..b81d5901c 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,6 @@ src/stan_files/*.hpp src/rstanarm.so src/rstanarm.dll src/init.o -man/*.Rd !man/rstanarm-internal.Rd vignettes/*.R !vignettes/*.Rmd diff --git a/DESCRIPTION b/DESCRIPTION index 7cb9c7a07..d4818bf3b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -75,4 +75,4 @@ UseLTO: true NeedsCompilation: yes URL: https://mc-stan.org/rstanarm/, https://discourse.mc-stan.org BugReports: https://github.com/stan-dev/rstanarm/issues -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.1 diff --git a/cleanup b/cleanup deleted file mode 100755 index 5f49d7c23..000000000 --- a/cleanup +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/sh -e - -# Note to Windows users: This is not actually platform specific. -"${R_HOME}/bin/R" --vanilla --slave -e 'roxygen2::roxygenize(clean = TRUE)' -exit $? diff --git a/cleanup.win b/cleanup.win deleted file mode 100755 index 9bbc18cd4..000000000 --- a/cleanup.win +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/sh -e - -# Note to Windows users: This is not actually platform specific. -"${R_HOME}/bin/R" --vanilla --slave -e 'rstantools::rstan_config()' -"${R_HOME}/bin/R" --vanilla --slave -e 'roxygen2::roxygenize(load_code = roxygen2::load_source, clean = TRUE)' -exit $? diff --git a/man/QR-argument.Rd b/man/QR-argument.Rd new file mode 100644 index 000000000..9c839da7f --- /dev/null +++ b/man/QR-argument.Rd @@ -0,0 +1,46 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-QR.R +\name{QR-argument} +\alias{QR-argument} +\title{The \code{QR} argument} +\description{ +Details about the \code{QR} argument to \pkg{rstanarm}'s modeling +functions. +} +\details{ +The \code{QR} argument is a logical scalar defaulting to + \code{FALSE}, but if \code{TRUE} applies a scaled \code{\link{qr}} + decomposition to the design matrix, \eqn{X = Q^\ast R^\ast}{X = Q* R*}. + If \code{autoscale = TRUE} (the default) + in the call to the function passed to the \code{prior} argument, then + \eqn{Q^\ast = Q \sqrt{n-1}}{Q* = Q (n-1)^0.5} and + \eqn{R^\ast = \frac{1}{\sqrt{n-1}} R}{R* = (n-1)^(-0.5) R}. When + \code{autoscale = FALSE}, \eqn{R} is scaled such that the lower-right + element of \eqn{R^\ast}{R*} is \eqn{1}. + + The coefficients relative to \eqn{Q^\ast}{Q*} are obtained and then + premultiplied by the inverse of \eqn{R^{\ast}}{R*} to obtain coefficients + relative to the original predictors, \eqn{X}. Thus, when + \code{autoscale = FALSE}, the coefficient on the last column of \eqn{X} + is the same as the coefficient on the last column of \eqn{Q^\ast}{Q*}. + + These transformations do not change the likelihood of the data but are + recommended for computational reasons when there are multiple predictors. + Importantly, while the columns of \eqn{X} are almost generally correlated, + the columns of \eqn{Q^\ast}{Q*} are uncorrelated by design, which often makes + sampling from the posterior easier. However, because when \code{QR} is + \code{TRUE} the \code{prior} argument applies to the coefficients relative to + \eqn{Q^\ast}{Q*} (and those are not very interpretable), setting \code{QR=TRUE} + is only recommended if you do not have an informative prior for the regression + coefficients or if the only informative prior is on the last regression + coefficient (in which case you should set \code{autoscale = FALSE} when + specifying such priors). + + For more details see the Stan case study + \emph{The QR Decomposition For Regression Models} at + \url{https://mc-stan.org/users/documentation/case-studies/qr_regression.html}. +} +\references{ +Stan Development Team. \emph{Stan Modeling Language Users Guide and +Reference Manual.} \url{https://mc-stan.org/users/documentation/}. +} diff --git a/man/adapt_delta.Rd b/man/adapt_delta.Rd new file mode 100644 index 000000000..888cc56fb --- /dev/null +++ b/man/adapt_delta.Rd @@ -0,0 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-adapt_delta.R +\name{adapt_delta} +\alias{adapt_delta} +\title{\code{adapt_delta}: Target average acceptance probability} +\description{ +Details about the \code{adapt_delta} argument to \pkg{rstanarm}'s modeling +functions. +} +\details{ +For the No-U-Turn Sampler (NUTS), the variant of Hamiltonian Monte + Carlo used used by \pkg{rstanarm}, \code{adapt_delta} is the target average + proposal acceptance probability during Stan's adaptation period. + \code{adapt_delta} is ignored by \pkg{rstanarm} if the \code{algorithm} argument + is not set to \code{"sampling"}. + + The default value of \code{adapt_delta} is 0.95, except when the prior for + the regression coefficients is \code{\link{R2}}, \code{\link{hs}}, or + \code{\link{hs_plus}}, in which case the default is 0.99. + + These defaults are higher (more conservative) than the default of + \code{adapt_delta=0.8} used in the \pkg{rstan} package, which may result in + slower sampling speeds but will be more robust to posterior distributions + with high curvature. + + In general you should not need to change \code{adapt_delta} unless you see + a warning message about divergent transitions, in which case you can + increase \code{adapt_delta} from the default to a value \emph{closer} to 1 + (e.g. from 0.95 to 0.99, or from 0.99 to 0.999, etc). The step size used by + the numerical integrator is a function of \code{adapt_delta} in that + increasing \code{adapt_delta} will result in a smaller step size and fewer + divergences. Increasing \code{adapt_delta} will typically result in a + slower sampler, but it will always lead to a more robust sampler. +} +\references{ +Stan Development Team. \emph{Stan Modeling Language Users Guide and +Reference Manual.} \url{https://mc-stan.org/users/documentation/}. + +Brief Guide to Stan's Warnings: + \url{https://mc-stan.org/misc/warnings.html#divergent-transitions-after-warmup} +} diff --git a/man/as.matrix.stanreg.Rd b/man/as.matrix.stanreg.Rd new file mode 100644 index 000000000..47ad50667 --- /dev/null +++ b/man/as.matrix.stanreg.Rd @@ -0,0 +1,80 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/as.matrix.stanreg.R +\name{as.matrix.stanreg} +\alias{as.matrix.stanreg} +\alias{as.array.stanreg} +\alias{as.data.frame.stanreg} +\title{Extract the posterior sample} +\usage{ +\method{as.matrix}{stanreg}(x, ..., pars = NULL, regex_pars = NULL) + +\method{as.array}{stanreg}(x, ..., pars = NULL, regex_pars = NULL) + +\method{as.data.frame}{stanreg}(x, ..., pars = NULL, regex_pars = NULL) +} +\arguments{ +\item{x}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{Ignored.} + +\item{pars}{An optional character vector of parameter names.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} +} +\value{ +A matrix, data.frame, or array, the dimensions of which depend on + \code{pars} and \code{regex_pars}, as well as the model and estimation + algorithm (see the Description section above). +} +\description{ +For models fit using MCMC (\code{algorithm="sampling"}), the posterior sample +---the post-warmup draws from the posterior distribution--- can be extracted +from a fitted model object as a matrix, data frame, or array. The +\code{as.matrix} and \code{as.data.frame} methods merge all chains together, +whereas the \code{as.array} method keeps the chains separate. For models fit +using optimization (\code{"optimizing"}) or variational inference +(\code{"meanfield"} or \code{"fullrank"}), there is no posterior sample but +rather a matrix (or data frame) of 1000 draws from either the asymptotic +multivariate Gaussian sampling distribution of the parameters or the +variational approximation to the posterior distribution. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +if (!exists("example_model")) example(example_model) +# Extract posterior sample after MCMC +draws <- as.matrix(example_model) +print(dim(draws)) + +# For example, we can see that the median of the draws for the intercept +# is the same as the point estimate rstanarm uses +print(median(draws[, "(Intercept)"])) +print(example_model$coefficients[["(Intercept)"]]) + +# The as.array method keeps the chains separate +draws_array <- as.array(example_model) +print(dim(draws_array)) # iterations x chains x parameters + +# Extract draws from asymptotic Gaussian sampling distribution +# after optimization +fit <- stan_glm(mpg ~ wt, data = mtcars, algorithm = "optimizing") +draws <- as.data.frame(fit) +print(colnames(draws)) +print(nrow(draws)) # 1000 draws are taken + +# Extract draws from variational approximation to the posterior distribution +fit2 <- update(fit, algorithm = "meanfield") +draws <- as.data.frame(fit2, pars = "wt") +print(colnames(draws)) +print(nrow(draws)) # 1000 draws are taken +} +} +} +\seealso{ +\code{\link{stanreg-draws-formats}}, \code{\link{stanreg-methods}} +} diff --git a/man/available-algorithms.Rd b/man/available-algorithms.Rd new file mode 100644 index 000000000..7d644715e --- /dev/null +++ b/man/available-algorithms.Rd @@ -0,0 +1,67 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-algorithms.R +\name{available-algorithms} +\alias{available-algorithms} +\title{Estimation algorithms available for \pkg{rstanarm} models} +\description{ +Estimation algorithms available for \pkg{rstanarm} models +} +\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}}. + } +} +} + +\seealso{ +\url{https://mc-stan.org/rstanarm/} +} diff --git a/man/available-models.Rd b/man/available-models.Rd new file mode 100644 index 000000000..e164e89d8 --- /dev/null +++ b/man/available-models.Rd @@ -0,0 +1,95 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-modeling-functions.R +\name{available-models} +\alias{available-models} +\title{Modeling functions available in \pkg{rstanarm}} +\description{ +Modeling functions available in \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). + } +} +} + +\seealso{ +\url{https://mc-stan.org/rstanarm/} +} diff --git a/man/bayes_R2.stanreg.Rd b/man/bayes_R2.stanreg.Rd new file mode 100644 index 000000000..ee9c75a56 --- /dev/null +++ b/man/bayes_R2.stanreg.Rd @@ -0,0 +1,61 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bayes_R2.R +\name{bayes_R2.stanreg} +\alias{bayes_R2.stanreg} +\alias{bayes_R2} +\alias{loo_R2.stanreg} +\alias{loo_R2} +\title{Compute a Bayesian version of R-squared or LOO-adjusted R-squared for +regression models.} +\usage{ +\method{bayes_R2}{stanreg}(object, ..., re.form = NULL) + +\method{loo_R2}{stanreg}(object, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{Currently ignored.} + +\item{re.form}{For models with group-level terms, \code{re.form} is +passed to \code{\link{posterior_epred}} if specified.} +} +\value{ +A vector of R-squared values with length equal to the posterior + sample size (the posterior distribution of R-squared). +} +\description{ +Compute a Bayesian version of R-squared or LOO-adjusted R-squared for +regression models. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +fit <- stan_glm( + mpg ~ wt + cyl, + data = mtcars, + QR = TRUE, + chains = 2, + refresh = 0 +) +rsq <- bayes_R2(fit) +print(median(rsq)) +hist(rsq) + +loo_rsq <- loo_R2(fit) +print(median(loo_rsq)) + +# multilevel binomial model +if (!exists("example_model")) example(example_model) +print(example_model) +median(bayes_R2(example_model)) +median(bayes_R2(example_model, re.form = NA)) # exclude group-level +} +} +\references{ +Andrew Gelman, Ben Goodrich, Jonah Gabry, and Aki Vehtari (2018). R-squared +for Bayesian regression models. \emph{The American Statistician}, to appear. +\doi{10.1080/00031305.2018.1549100} +(\href{http://www.stat.columbia.edu/~gelman/research/published/bayes_R2_v3.pdf}{Preprint}, +\href{https://avehtari.github.io/bayes_R2/bayes_R2.html}{Notebook}) +} diff --git a/man/example_jm.Rd b/man/example_jm.Rd new file mode 100644 index 000000000..aa5b51ca3 --- /dev/null +++ b/man/example_jm.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-example_jm.R +\name{example_jm} +\alias{example_jm} +\title{Example joint longitudinal and time-to-event model} +\format{ +Calling \code{example("example_jm")} will run the model in the + Examples section, below, and the resulting stanmvreg object will then be + available in the global environment. The \code{chains} and \code{iter} + arguments are specified to make this example be small in size. In practice, + we recommend that they be left unspecified in order to use the default + values or increased if there are convergence problems. The \code{cores} + argument is optional and on a multicore system, the user may well want + to set that equal to the number of chains being executed. +} +\description{ +A model for use in the \pkg{rstanarm} examples related to \code{\link{stan_jm}}. +} +\examples{ + # set.seed(123) + if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") + example_jm <- + stan_jm(formulaLong = logBili ~ year + (1 | id), + dataLong = pbcLong[1:101,], + formulaEvent = survival::Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv[1:15,], + time_var = "year", + # this next line is only to keep the example small in size! + chains = 1, seed = 12345, iter = 100, refresh = 0) + + +} diff --git a/man/example_model.Rd b/man/example_model.Rd new file mode 100644 index 000000000..5d4f7bca6 --- /dev/null +++ b/man/example_model.Rd @@ -0,0 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-example_model.R +\name{example_model} +\alias{example_model} +\title{Example model} +\format{ +Calling \code{example("example_model")} will run the model in the + Examples section, below, and the resulting stanreg object will then be + available in the global environment. The \code{chains} and \code{iter} + arguments are specified to make this example be small in size. In practice, + we recommend that they be left unspecified in order to use the default + values (4 and 2000 respectively) or increased if there are convergence + problems. The \code{cores} argument is optional and on a multicore system, + the user may well want to set that equal to the number of chains being + executed. +} +\description{ +A model for use in \pkg{rstanarm} examples. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +example_model <- + stan_glmer(cbind(incidence, size - incidence) ~ size + period + (1|herd), + data = lme4::cbpp, family = binomial, QR = TRUE, + # this next line is only to keep the example small in size! + chains = 2, cores = 1, seed = 12345, iter = 1000, refresh = 0) +example_model +} +} +\seealso{ +\code{\link[lme4]{cbpp}} for a description of the data. +} diff --git a/man/family.stanmvreg.Rd b/man/family.stanmvreg.Rd new file mode 100644 index 000000000..99b51448b --- /dev/null +++ b/man/family.stanmvreg.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanmvreg-methods.R +\name{family.stanmvreg} +\alias{family.stanmvreg} +\title{family method for stanmvreg objects} +\usage{ +\method{family}{stanmvreg}(object, m = NULL, ...) +} +\arguments{ +\item{object, ...}{See \code{\link[stats]{family}}.} + +\item{m}{Integer specifying the number or name of the submodel} +} +\description{ +family method for stanmvreg objects +} +\keyword{internal} diff --git a/man/family.stanreg.Rd b/man/family.stanreg.Rd new file mode 100644 index 000000000..47958b008 --- /dev/null +++ b/man/family.stanreg.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{family.stanreg} +\alias{family.stanreg} +\title{family method for stanreg objects} +\usage{ +\method{family}{stanreg}(object, ...) +} +\arguments{ +\item{object, ...}{See \code{\link[stats]{family}}.} +} +\description{ +family method for stanreg objects +} +\keyword{internal} diff --git a/man/formula.stanreg.Rd b/man/formula.stanreg.Rd new file mode 100644 index 000000000..a09049abb --- /dev/null +++ b/man/formula.stanreg.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{formula.stanreg} +\alias{formula.stanreg} +\title{formula method for stanreg objects} +\usage{ +\method{formula}{stanreg}(x, ..., m = NULL) +} +\arguments{ +\item{x}{A stanreg object.} + +\item{...}{Can contain \code{fixed.only} and \code{random.only} arguments +that both default to \code{FALSE}.} +} +\description{ +formula method for stanreg objects +} +\keyword{internal} diff --git a/man/get_y.Rd b/man/get_y.Rd new file mode 100644 index 000000000..c3f8f1b28 --- /dev/null +++ b/man/get_y.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/misc.R +\name{get_y} +\alias{get_y} +\alias{get_x} +\alias{get_z} +\title{Extract X, Y or Z from a stanreg object} +\usage{ +get_y(object, ...) + +get_x(object, ...) + +get_z(object, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{Other arguments passed to methods. For a \code{stanmvreg} object +this can be an integer \code{m} specifying the submodel.} +} +\value{ +For \code{get_x} and \code{get_z}, a matrix. For \code{get_y}, either + a vector or a matrix, depending on how the response variable was specified. +} +\description{ +Extract X, Y or Z from a stanreg object +} +\keyword{internal} diff --git a/man/kfold.stanreg.Rd b/man/kfold.stanreg.Rd new file mode 100644 index 000000000..83e4bbd91 --- /dev/null +++ b/man/kfold.stanreg.Rd @@ -0,0 +1,127 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/loo-kfold.R +\name{kfold.stanreg} +\alias{kfold.stanreg} +\alias{kfold} +\title{K-fold cross-validation} +\usage{ +\method{kfold}{stanreg}( + x, + K = 10, + ..., + folds = NULL, + save_fits = FALSE, + cores = getOption("mc.cores", 1) +) +} +\arguments{ +\item{x}{A fitted model object returned by one of the rstanarm modeling +functions. See \link{stanreg-objects}.} + +\item{K}{For \code{kfold}, the number of subsets (folds) into which the data +will be partitioned for performing \eqn{K}-fold cross-validation. The model +is refit \code{K} times, each time leaving out one of the \code{K} folds. +If the \code{folds} argument is specified then \code{K} will automatically +be set to \code{length(unique(folds))}, otherwise the specified value of +\code{K} is passed to \code{loo::\link[loo:kfold-helpers]{kfold_split_random}} to +randomly partition the data into \code{K} subsets of equal (or as close to +equal as possible) size.} + +\item{...}{Currently ignored.} + +\item{folds}{For \code{kfold}, an optional integer vector with one element +per observation in the data used to fit the model. Each element of the +vector is an integer in \code{1:K} indicating to which of the \code{K} +folds the corresponding observation belongs. There are some convenience +functions available in the \pkg{loo} package that create integer vectors to +use for this purpose (see the \strong{Examples} section below and also the +\link[loo]{kfold-helpers} page).} + +\item{save_fits}{For \code{kfold}, if \code{TRUE}, a component \code{'fits'} +is added to the returned object to store the cross-validated +\link[=stanreg-objects]{stanreg} objects and the indices of the omitted +observations for each fold. Defaults to \code{FALSE}.} + +\item{cores}{The number of cores to use for parallelization. Instead fitting +separate Markov chains for the same model on different cores, by default +\code{kfold} will distribute the \code{K} models to be fit across the cores +(using \code{\link[parallel:clusterApply]{parLapply}} on Windows and +\code{\link[parallel]{mclapply}} otherwise). The Markov chains for each +model will be run sequentially. This will often be the most efficient +option, especially if many cores are available, but in some cases it may be +preferable to fit the \code{K} models sequentially and instead use the +cores for the Markov chains. This can be accomplished by setting +\code{options(mc.cores)} to be the desired number of cores to use +for the Markov chains \emph{and} also manually specifying \code{cores=1} +when calling the \code{kfold} function. See the end of the +\strong{Examples} section for a demonstration.} +} +\value{ +An object with classes 'kfold' and 'loo' that has a similar structure + as the objects returned by the \code{\link{loo}} and \code{\link{waic}} + methods and is compatible with the \code{\link{loo_compare}} function for + comparing models. +} +\description{ +The \code{kfold} method performs exact \eqn{K}-fold cross-validation. First +the data are randomly partitioned into \eqn{K} subsets of equal size (or as close +to equal as possible), or the user can specify the \code{folds} argument +to determine the partitioning. Then the model is refit \eqn{K} times, each time +leaving out one of the \eqn{K} subsets. If \eqn{K} is equal to the total +number of observations in the data then \eqn{K}-fold cross-validation is +equivalent to exact leave-one-out cross-validation (to which +\code{\link[=loo.stanreg]{loo}} is an efficient approximation). +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +fit1 <- stan_glm(mpg ~ wt, data = mtcars, refresh = 0) +fit2 <- stan_glm(mpg ~ wt + cyl, data = mtcars, refresh = 0) +fit3 <- stan_glm(mpg ~ disp * as.factor(cyl), data = mtcars, refresh = 0) + +# 10-fold cross-validation +# (if possible also specify the 'cores' argument to use multiple cores) +(kfold1 <- kfold(fit1, K = 10)) +kfold2 <- kfold(fit2, K = 10) +kfold3 <- kfold(fit3, K = 10) +loo_compare(kfold1, kfold2, kfold3) + +# stratifying by a grouping variable +# (note: might get some divergences warnings with this model but +# this is just intended as a quick example of how to code this) +fit4 <- stan_lmer(mpg ~ disp + (1|cyl), data = mtcars, refresh = 0) +table(mtcars$cyl) +folds_cyl <- loo::kfold_split_stratified(K = 3, x = mtcars$cyl) +table(cyl = mtcars$cyl, fold = folds_cyl) +kfold4 <- kfold(fit4, folds = folds_cyl, cores = 2) +print(kfold4) +} +} +# Example code demonstrating the different ways to specify the number +# of cores and how the cores are used +# +# options(mc.cores = NULL) +# +# # spread the K models over N_CORES cores (method 1) +# kfold(fit, K, cores = N_CORES) +# +# # spread the K models over N_CORES cores (method 2) +# options(mc.cores = N_CORES) +# kfold(fit, K) +# +# # fit K models sequentially using N_CORES cores for the Markov chains each time +# options(mc.cores = N_CORES) +# kfold(fit, K, cores = 1) + +} +\references{ +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}. +} diff --git a/man/launch_shinystan.stanreg.Rd b/man/launch_shinystan.stanreg.Rd new file mode 100644 index 000000000..e001c6af4 --- /dev/null +++ b/man/launch_shinystan.stanreg.Rd @@ -0,0 +1,127 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/launch_shinystan.R +\name{launch_shinystan.stanreg} +\alias{launch_shinystan.stanreg} +\alias{launch_shinystan} +\title{Using the ShinyStan GUI with rstanarm models} +\usage{ +\method{launch_shinystan}{stanreg}( + object, + ppd = TRUE, + seed = 1234, + model_name = NULL, + note = NULL, + rstudio = getOption("shinystan.rstudio"), + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{ppd}{Should \pkg{rstanarm} draw from the posterior predictive +distribution before launching ShinyStan? The default is \code{TRUE}, +although for very large objects it can be convenient to set it to +\code{FALSE} as drawing from the posterior predictive distribution can be +time consuming. If \code{ppd} is \code{TRUE} then graphical posterior +predictive checks are available when ShinyStan is launched.} + +\item{seed}{Passed to \link[=pp_check]{pp_check} if +\code{ppd} is \code{TRUE}.} + +\item{model_name, note}{Optional arguments passed to +\code{\link[shinystan]{as.shinystan}}.} + +\item{rstudio}{Only relevant for 'RStudio' users. The default (\code{FALSE}) +is to launch the app in the user's default web browser rather than the +pop-up Viewer provided by 'RStudio'. Users can change the default to +\code{TRUE} by setting the global option \code{options(shinystan.rstudio = +TRUE)}.} + +\item{...}{Optional arguments passed to \code{\link[shiny]{runApp}}.} +} +\description{ +The ShinyStan interface provides visual and numerical summaries of model +parameters and convergence diagnostics. +} +\details{ +The \code{\link[shinystan]{launch_shinystan}} function will accept a + \code{\link[=stanreg-objects]{stanreg}} object as input. Currently, almost + any model fit using one of \pkg{rstanarm}'s model-fitting functions can be + used with ShinyStan. The only exception is that ShinyStan does not + currently support \pkg{rstanarm} models fit using + \code{algorithm='optimizing'}. See the + \pkg{\link[=shinystan-package]{shinystan}} package documentation for more + information. +} +\section{Faster launch times}{ + +For some \pkg{rstanarm} models ShinyStan may take a very long time to launch. +If this is the case with one of your models you may be able to speed up +\code{launch_shinystan} in one of several ways: +\describe{ + \item{Prevent ShinyStan from preparing graphical posterior predictive + checks:}{ + When used with a \code{\link[=stanreg-objects]{stanreg}} object + (\pkg{rstanarm} model object) ShinyStan will draw from the posterior + predictive distribution and prepare graphical posterior predictive checks + before launching. That way when you go to the PPcheck page the plots are + immediately available. This can be time consuming for models fit to very + large datasets and you can prevent this behavior by creating a shinystan + object before calling \code{launch_shinystan}. To do this use + \code{\link[shinystan]{as.shinystan}} with optional argument \code{ppd} set + to \code{FALSE} (see the Examples section below). When you then launch + ShinyStan and go to the PPcheck page the plots will no longer be + automatically generated and you will be presented with the standard + interface requiring you to first specify the appropriate \eqn{y} and + \eqn{yrep}, which can be done for many but not all \pkg{rstanarm} models. + } + \item{Use a shinystan object:}{ + Even if you don't want to prevent ShinyStan from preparing graphical + posterior predictive checks, first creating a shinystan object using + \code{\link[shinystan]{as.shinystan}} can reduce \emph{future} launch + times. That is, \code{launch_shinystan(sso)} will be faster than + \code{launch_shinystan(fit)}, where \code{sso} is a shinystan object and + \code{fit} is a stanreg object. It still may take some time for + \code{as.shinystan} to create \code{sso} initially, but each time you + subsequently call \code{launch_shinystan(sso)} it will reuse \code{sso} + instead of internally creating a shinystan object every time. See the + Examples section below.} +} +} + +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\dontrun{ +if (!exists("example_model")) example(example_model) + +# Launch the ShinyStan app without saving the resulting shinystan object +if (interactive()) launch_shinystan(example_model) + +# Launch the ShinyStan app (saving resulting shinystan object as sso) +if (interactive()) sso <- launch_shinystan(example_model) + +# First create shinystan object then call launch_shinystan +sso <- shinystan::as.shinystan(example_model) +if (interactive()) launch_shinystan(sso) + +# Prevent ShinyStan from preparing graphical posterior predictive checks that +# can be time consuming. example_model is small enough that it won't matter +# much here but in general this can help speed up launch_shinystan +sso <- shinystan::as.shinystan(example_model, ppd = FALSE) +if (interactive()) launch_shinystan(sso) +} +} +} +\references{ +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} +} diff --git a/man/log_lik.stanreg.Rd b/man/log_lik.stanreg.Rd new file mode 100644 index 000000000..850892b5e --- /dev/null +++ b/man/log_lik.stanreg.Rd @@ -0,0 +1,82 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/log_lik.R +\name{log_lik.stanreg} +\alias{log_lik.stanreg} +\alias{log_lik} +\alias{log_lik.stanmvreg} +\alias{log_lik.stanjm} +\title{Pointwise log-likelihood matrix} +\usage{ +\method{log_lik}{stanreg}(object, newdata = NULL, offset = NULL, ...) + +\method{log_lik}{stanmvreg}(object, m = 1, newdata = NULL, ...) + +\method{log_lik}{stanjm}(object, newdataLong = NULL, newdataEvent = NULL, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{newdata}{An optional data frame of new data (e.g. holdout data) to use +when evaluating the log-likelihood. See the description of \code{newdata} +for \code{\link{posterior_predict}}.} + +\item{offset}{A vector of offsets. Only required if \code{newdata} is +specified and an \code{offset} was specified when fitting the model.} + +\item{...}{Currently ignored.} + +\item{m}{Integer specifying the number or name of the submodel} + +\item{newdataLong, newdataEvent}{Optional data frames containing new data +(e.g. holdout data) to use when evaluating the log-likelihood for a +model estimated using \code{\link{stan_jm}}. If the fitted model +was a multivariate joint model (i.e. more than one longitudinal outcome), +then \code{newdataLong} is allowed to be a list of data frames. If supplying +new data, then \code{newdataEvent} should also include variables corresponding +to the event time and event indicator as these are required for evaluating the +log likelihood for the event submodel. For more details, see the description +of \code{newdataLong} and \code{newdataEvent} for \code{\link{posterior_survfit}}.} +} +\value{ +For the \code{stanreg} and \code{stanmvreg} methods an \eqn{S} by + \eqn{N} matrix, where \eqn{S} is the size of the posterior sample and + \eqn{N} is the number of data points. For the \code{stanjm} method + an \eqn{S} by \eqn{Npat} matrix where \eqn{Npat} is the number of individuals. +} +\description{ +For models fit using MCMC only, the \code{log_lik} method returns the +\eqn{S} by \eqn{N} pointwise log-likelihood matrix, where \eqn{S} is the size +of the posterior sample and \eqn{N} is the number of data points, or in the +case of the \code{stanmvreg} method (when called on \code{\link{stan_jm}} +model objects) an \eqn{S} by \eqn{Npat} matrix where \eqn{Npat} is the number +of individuals. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + roaches$roach100 <- roaches$roach1 / 100 + fit <- stan_glm( + y ~ roach100 + treatment + senior, + offset = log(exposure2), + data = roaches, + family = poisson(link = "log"), + prior = normal(0, 2.5), + prior_intercept = normal(0, 10), + iter = 500, # just to speed up example, + refresh = 0 + ) + ll <- log_lik(fit) + dim(ll) + all.equal(ncol(ll), nobs(fit)) + + # using newdata argument + nd <- roaches[1:2, ] + nd$treatment[1:2] <- c(0, 1) + ll2 <- log_lik(fit, newdata = nd, offset = c(0, 0)) + head(ll2) + dim(ll2) + all.equal(ncol(ll2), nrow(nd)) +} +} +} diff --git a/man/logit.Rd b/man/logit.Rd new file mode 100644 index 000000000..e78f0b4fa --- /dev/null +++ b/man/logit.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/misc.R +\name{logit} +\alias{logit} +\alias{invlogit} +\title{Logit and inverse logit} +\usage{ +logit(x) + +invlogit(x) +} +\arguments{ +\item{x}{Numeric vector.} +} +\value{ +A numeric vector the same length as \code{x}. +} +\description{ +Logit and inverse logit +} diff --git a/man/loo.stanreg.Rd b/man/loo.stanreg.Rd new file mode 100644 index 000000000..277e29cd7 --- /dev/null +++ b/man/loo.stanreg.Rd @@ -0,0 +1,259 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/loo.R +\name{loo.stanreg} +\alias{loo.stanreg} +\alias{loo} +\alias{waic.stanreg} +\alias{waic} +\alias{loo_compare.stanreg} +\alias{loo_compare} +\alias{loo_compare.stanreg_list} +\alias{loo_model_weights.stanreg_list} +\alias{loo_model_weights} +\alias{compare_models} +\title{Information criteria and cross-validation} +\usage{ +\method{loo}{stanreg}( + x, + ..., + cores = getOption("mc.cores", 1), + save_psis = FALSE, + k_threshold = NULL +) + +\method{waic}{stanreg}(x, ...) + +\method{loo_compare}{stanreg}(x, ..., criterion = c("loo", "kfold", "waic"), detail = FALSE) + +\method{loo_compare}{stanreg_list}(x, ..., criterion = c("loo", "kfold", "waic"), detail = FALSE) + +\method{loo_model_weights}{stanreg_list}(x, ..., cores = getOption("mc.cores", 1), k_threshold = NULL) + +compare_models(..., loos = list(), detail = FALSE) +} +\arguments{ +\item{x}{For \code{loo} and \code{waic}, a fitted model object returned by + one of the rstanarm modeling functions. See \link{stanreg-objects}. + + For the \code{loo_model_weights} method, \code{x} should be a + "stanreg_list" object, which is a list of fitted model objects created by + \code{\link{stanreg_list}}. \code{loo_compare} also allows \code{x} to be a + single stanreg object, with the remaining objects passed via \code{...}, or + a single \code{stanreg_list} object.} + +\item{...}{For \code{loo_compare.stanreg}, \code{...} can contain objects + returned by the \code{loo}, \code{\link[=kfold.stanreg]{kfold}}, or + \code{waic} method (see the \strong{Examples} section, below). + + For \code{loo_model_weights}, \code{...} should contain arguments (e.g. + \code{method}) to pass to the default \code{\link[loo]{loo_model_weights}} + method from the \pkg{loo} package.} + +\item{cores, save_psis}{Passed to \code{\link[loo]{loo}}.} + +\item{k_threshold}{Threshold for flagging estimates of the Pareto shape +parameters \eqn{k} estimated by \code{loo}. See the \emph{How to proceed +when \code{loo} gives warnings} section, below, for details.} + +\item{criterion}{For \code{loo_compare.stanreg} and +\code{loo_compare.stanreg_list}, should the comparison be based on LOO-CV +(\code{criterion="loo"}), K-fold-CV (\code{criterion="kfold"}), or WAIC +(\code{criterion="waic"}). The default is LOO-CV. See the \strong{Comparing +models} and \strong{Examples} sections below.} + +\item{detail}{For \code{loo_compare.stanreg} and +\code{loo_compare.stanreg_list}, if \code{TRUE} then extra information +about each model (currently just the model formulas) will be printed with +the output.} + +\item{loos}{a list of objects produced by the \code{\link{loo}} function} +} +\value{ +The structure of the objects returned by \code{loo} and \code{waic} + methods are documented in detail in the \strong{Value} section in + \code{\link[loo]{loo}} and \code{\link[loo]{waic}} (from the \pkg{loo} + package). + +\code{loo_compare} returns a matrix with class 'compare.loo'. See the + \strong{Comparing models} section below for more details. +} +\description{ +For models fit using MCMC, compute approximate leave-one-out + cross-validation (LOO, LOOIC) or, less preferably, the Widely Applicable + Information Criterion (WAIC) using the \pkg{\link[=loo-package]{loo}} + package. (For \eqn{K}-fold cross-validation see \code{\link{kfold.stanreg}}.) + Functions for model comparison, and model weighting/averaging are also + provided. + + \strong{Note}: these functions are not guaranteed to work + properly unless the \code{data} argument was specified when the model was + fit. Also, as of \pkg{loo} version \code{2.0.0} the default number of cores + is now only 1, but we recommend using as many (or close to as many) cores + as possible by setting the \code{cores} argument or using + \code{options(mc.cores = VALUE)} to set it for an entire session. +} +\section{Approximate LOO CV}{ + The \code{loo} method for stanreg objects + provides an interface to the \pkg{\link[=loo-package]{loo}} package for + approximate leave-one-out cross-validation (LOO). The LOO Information + Criterion (LOOIC) has the same purpose as the Akaike Information Criterion + (AIC) that is used by frequentists. Both are intended to estimate the + expected log predictive density (ELPD) for a new dataset. However, the AIC + ignores priors and assumes that the posterior distribution is multivariate + normal, whereas the functions from the \pkg{loo} package do not make this + distributional assumption and integrate over uncertainty in the parameters. + This only assumes that any one observation can be omitted without having a + major effect on the posterior distribution, which can be judged using the + diagnostic plot provided by the \code{\link[loo:pareto-k-diagnostic]{plot.loo}} method and the + warnings provided by the \code{\link[loo]{print.loo}} method (see the + \emph{How to Use the rstanarm Package} vignette for an example of this + process). + + \subsection{How to proceed when \code{loo} gives warnings (k_threshold)}{ + The \code{k_threshold} argument to the \code{loo} method for \pkg{rstanarm} + models is provided as a possible remedy when the diagnostics reveal + problems stemming from the posterior's sensitivity to particular + observations. Warnings about Pareto \eqn{k} estimates indicate observations + for which the approximation to LOO is problematic (this is described in + detail in Vehtari, Gelman, and Gabry (2017) and the + \pkg{\link[=loo-package]{loo}} package documentation). The + \code{k_threshold} argument can be used to set the \eqn{k} value above + which an observation is flagged. If \code{k_threshold} is not \code{NULL} + and there are \eqn{J} observations with \eqn{k} estimates above + \code{k_threshold} then when \code{loo} is called it will refit the + original model \eqn{J} times, each time leaving out one of the \eqn{J} + problematic observations. The pointwise contributions of these observations + to the total ELPD are then computed directly and substituted for the + previous estimates from these \eqn{J} observations that are stored in the + object created by \code{loo}. Another option to consider is K-fold + cross-validation, which is documented on a separate page (see + \code{\link[=kfold.stanreg]{kfold}}). + + \strong{Note}: in the warning messages issued by \code{loo} about large + Pareto \eqn{k} estimates we recommend setting \code{k_threshold} to at + least \eqn{0.7}. There is a theoretical reason, explained in Vehtari, + Gelman, and Gabry (2017), for setting the threshold to the stricter value + of \eqn{0.5}, but in practice they find that errors in the LOO + approximation start to increase non-negligibly when \eqn{k > 0.7}. + } +} + +\section{Comparing models}{ + "loo" (or "waic" or "kfold") objects can be passed + to the \code{\link[loo]{loo_compare}} function in the \pkg{loo} package to + perform model comparison. \pkg{rstanarm} also provides a + \code{loo_compare.stanreg} method that can be used if the "loo" (or "waic" + or "kfold") object has been added to the fitted model object (see the + \strong{Examples} section below for how to do this). This second method + allows \pkg{rstanarm} to perform some extra checks that can't be done by + the \pkg{loo} package itself (e.g., verifying that all models to be + compared were fit using the same outcome variable). + + \code{loo_compare} will return a matrix with one row per model and columns + containing the ELPD difference and the standard error of the difference. In + the first row of the matrix will be the model with the largest ELPD + (smallest LOOIC) and will contain zeros (there is no difference between + this model and itself). For each of the remaining models the ELPD + difference and SE are reported relative to the model with the best ELPD + (the first row). See the \strong{Details} section at the + \code{\link[loo]{loo_compare}} page in the \pkg{loo} package for more + information. +} + +\section{Model weights}{ + The \code{loo_model_weights} method can be used to + compute model weights for a \code{"stanreg_list"} object, which is a list + of fitted model objects made with \code{\link{stanreg_list}}. The end of + the \strong{Examples} section has a demonstration. For details see the + \code{\link[loo]{loo_model_weights}} documentation in the \pkg{loo} + package. +} + +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +fit1 <- stan_glm(mpg ~ wt, data = mtcars, refresh = 0) +fit2 <- stan_glm(mpg ~ wt + cyl, data = mtcars, refresh = 0) + +# (for bigger models use as many cores as possible) +loo1 <- loo(fit1, cores = 1) +print(loo1) +loo2 <- loo(fit2, cores = 1) +print(loo2) + +# when comparing models the loo objects can be passed to loo_compare +# as individual arguments or as a list of loo objects +loo_compare(loo1, loo2) +loo_compare(list(loo1, loo2)) + +# if the fitted model objects contain a loo object in the component "loo" +# then the model objects can be passed directly or as a stanreg_list +fit1$loo <- loo1 +fit2$loo <- loo2 +loo_compare(fit1, fit2) + +# if the fitted model objects contain a loo object _and_ a waic or kfold +# object, then the criterion argument determines which of them the comparison +# is based on +fit1$waic <- waic(fit1) +fit2$waic <- waic(fit2) +loo_compare(fit1, fit2, criterion = "waic") + +# the models can also be combined into a stanreg_list object, and more +# informative model names can be provided to use when printing +model_list <- stanreg_list(fit1, fit2, model_names = c("Fewer predictors", "More predictors")) +loo_compare(model_list) + +fit3 <- stan_glm(mpg ~ disp * as.factor(cyl), data = mtcars, refresh = 0) +loo3 <- loo(fit3, cores = 2, k_threshold = 0.7) +loo_compare(loo1, loo2, loo3) + +# setting detail=TRUE will also print model formulas if used with +# loo_compare.stanreg or loo_compare.stanreg_list +fit3$loo <- loo3 +model_list <- stanreg_list(fit1, fit2, fit3) +loo_compare(model_list, detail=TRUE) + +# Computing model weights +# +# if the objects in model_list already have 'loo' components then those +# will be used. otherwise loo will be computed for each model internally +# (in which case the 'cores' argument may also be used and is passed to loo()) +loo_model_weights(model_list) # defaults to method="stacking" +loo_model_weights(model_list, method = "pseudobma") +loo_model_weights(model_list, method = "pseudobma", BB = FALSE) + +# you can also pass precomputed loo objects directly to loo_model_weights +loo_list <- list(A = loo1, B = loo2, C = loo3) # names optional (affects printing) +loo_model_weights(loo_list) +} +} +} +\references{ +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}) +} +\seealso{ +\itemize{ + \item The new \href{https://mc-stan.org/loo/articles/}{\pkg{loo} package vignettes} + and various \href{https://mc-stan.org/rstanarm/articles/}{\pkg{rstanarm} vignettes} + for more examples using \code{loo} and related functions with \pkg{rstanarm} models. + \item \code{\link[loo]{pareto-k-diagnostic}} in the \pkg{loo} package for + more on Pareto \eqn{k} diagnostics. + \item \code{\link{log_lik.stanreg}} to directly access the pointwise + log-likelihood matrix. +} +} diff --git a/man/loo_predict.stanreg.Rd b/man/loo_predict.stanreg.Rd new file mode 100644 index 000000000..3de42e869 --- /dev/null +++ b/man/loo_predict.stanreg.Rd @@ -0,0 +1,107 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/loo-prediction.R +\name{loo_predict.stanreg} +\alias{loo_predict.stanreg} +\alias{loo_predict} +\alias{loo_linpred} +\alias{loo_predictive_interval} +\alias{loo_linpred.stanreg} +\alias{loo_predictive_interval.stanreg} +\title{Compute weighted expectations using LOO} +\usage{ +\method{loo_predict}{stanreg}( + object, + type = c("mean", "var", "quantile"), + probs = 0.5, + ..., + psis_object = NULL +) + +\method{loo_linpred}{stanreg}( + object, + type = c("mean", "var", "quantile"), + probs = 0.5, + transform = FALSE, + ..., + psis_object = NULL +) + +\method{loo_predictive_interval}{stanreg}(object, prob = 0.9, ..., psis_object = NULL) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{type}{The type of expectation to compute. The options are +\code{"mean"}, \code{"variance"}, \code{"sd"}, and \code{"quantile"}.} + +\item{probs}{For computing quantiles, a vector of probabilities.} + +\item{...}{Currently unused.} + +\item{psis_object}{An object returned by \code{\link[loo]{psis}}. If missing +then \code{psis} will be run internally, which may be time consuming +for models fit to very large datasets.} + +\item{transform}{Passed to \code{\link{posterior_linpred}}.} + +\item{prob}{For \code{loo_predictive_interval}, a scalar in \eqn{(0,1)} +indicating the desired probability mass to include in the intervals. The +default is \code{prob=0.9} (\eqn{90}\% intervals).} +} +\value{ +A list with elements \code{value} and \code{pareto_k}. + + For \code{loo_predict} and \code{loo_linpred} the value component is a + vector with one element per observation. + + For \code{loo_predictive_interval} the \code{value} component is a matrix + with one row per observation and two columns (like + \code{\link{predictive_interval}}). \code{loo_predictive_interval(..., prob + = p)} is equivalent to \code{loo_predict(..., type = "quantile", probs = + c(a, 1-a))} with \code{a = (1 - p)/2}, except it transposes the result and + adds informative column names. + + See \code{\link[loo]{E_loo}} and \code{\link[loo]{pareto-k-diagnostic}} for + details on the \code{pareto_k} diagnostic. +} +\description{ +These functions are wrappers around the \code{\link[loo]{E_loo}} function +(\pkg{loo} package) that provide compatibility for \pkg{rstanarm} models. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\dontrun{ +if (!exists("example_model")) example(example_model) + +# optionally, log-weights can be pre-computed and reused +psis_result <- loo::psis(log_ratios = -log_lik(example_model)) + +loo_probs <- loo_linpred(example_model, type = "mean", transform = TRUE, psis_object = psis_result) +str(loo_probs) + +loo_pred_var <- loo_predict(example_model, type = "var", psis_object = psis_result) +str(loo_pred_var) + +loo_pred_ints <- loo_predictive_interval(example_model, prob = 0.8, psis_object = psis_result) +str(loo_pred_ints) +} +} +} +\references{ +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}) +} diff --git a/man/model.frame.stanmvreg.Rd b/man/model.frame.stanmvreg.Rd new file mode 100644 index 000000000..1560e7fab --- /dev/null +++ b/man/model.frame.stanmvreg.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanmvreg-methods.R +\name{model.frame.stanmvreg} +\alias{model.frame.stanmvreg} +\title{model.frame method for stanmvreg objects} +\usage{ +\method{model.frame}{stanmvreg}(formula, fixed.only = FALSE, m = NULL, ...) +} +\arguments{ +\item{formula, ...}{See \code{\link[stats]{model.frame}}.} + +\item{fixed.only}{See \code{\link[lme4:merMod-class]{model.frame.merMod}}.} + +\item{m}{Integer specifying the number or name of the submodel} +} +\description{ +model.frame method for stanmvreg objects +} +\keyword{internal} diff --git a/man/model.frame.stanreg.Rd b/man/model.frame.stanreg.Rd new file mode 100644 index 000000000..95f2c79b9 --- /dev/null +++ b/man/model.frame.stanreg.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{model.frame.stanreg} +\alias{model.frame.stanreg} +\title{model.frame method for stanreg objects} +\usage{ +\method{model.frame}{stanreg}(formula, fixed.only = FALSE, ...) +} +\arguments{ +\item{formula, ...}{See \code{\link[stats]{model.frame}}.} + +\item{fixed.only}{See \code{\link[lme4:merMod-class]{model.frame.merMod}}.} +} +\description{ +model.frame method for stanreg objects +} +\keyword{internal} diff --git a/man/model.matrix.stanreg.Rd b/man/model.matrix.stanreg.Rd new file mode 100644 index 000000000..16793af9a --- /dev/null +++ b/man/model.matrix.stanreg.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{model.matrix.stanreg} +\alias{model.matrix.stanreg} +\title{model.matrix method for stanreg objects} +\usage{ +\method{model.matrix}{stanreg}(object, ...) +} +\arguments{ +\item{object, ...}{See \code{\link[stats]{model.matrix}}.} +} +\description{ +model.matrix method for stanreg objects +} +\keyword{internal} diff --git a/man/neg_binomial_2.Rd b/man/neg_binomial_2.Rd new file mode 100644 index 000000000..2ddd5f0d2 --- /dev/null +++ b/man/neg_binomial_2.Rd @@ -0,0 +1,36 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/neg_binomial_2.R +\name{neg_binomial_2} +\alias{neg_binomial_2} +\title{Family function for negative binomial GLMs} +\usage{ +neg_binomial_2(link = "log") +} +\arguments{ +\item{link}{The same as for \code{\link[stats:family]{poisson}}, typically a character +vector of length one among \code{"log"}, \code{"identity"}, and +\code{"sqrt"}.} +} +\value{ +An object of class \code{\link[stats]{family}} very similar to + that of \code{\link[stats:family]{poisson}} but with a different family name. +} +\description{ +Specifies the information required to fit a Negative Binomial GLM in a +similar way to \code{\link[MASS]{negative.binomial}}. However, here the +overdispersion parameter \code{theta} is not specified by the user and always +estimated (really the \emph{reciprocal} of the dispersion parameter is +estimated). A call to this function can be passed to the \code{family} +argument of \code{\link{stan_glm}} or \code{\link{stan_glmer}} to estimate a +Negative Binomial model. Alternatively, the \code{\link{stan_glm.nb}} and +\code{\link{stan_glmer.nb}} wrapper functions may be used, which call +\code{neg_binomial_2} internally. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") +stan_glm(Days ~ Sex/(Age + Eth*Lrn), data = MASS::quine, seed = 123, + family = neg_binomial_2, QR = TRUE, algorithm = "optimizing") + +# or, equivalently, call stan_glm.nb() without specifying the family + +} diff --git a/man/pairs.stanreg.Rd b/man/pairs.stanreg.Rd new file mode 100644 index 000000000..36df099ac --- /dev/null +++ b/man/pairs.stanreg.Rd @@ -0,0 +1,114 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plots.R +\name{pairs.stanreg} +\alias{pairs.stanreg} +\alias{pairs_style_np} +\alias{pairs_condition} +\title{Pairs method for stanreg objects} +\usage{ +\method{pairs}{stanreg}( + x, + pars = NULL, + regex_pars = NULL, + condition = pairs_condition(nuts = "accept_stat__"), + ... +) +} +\arguments{ +\item{x}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{pars}{An optional character vector of parameter names. All parameters +are included by default, but for models with more than just a few +parameters it may be far too many to visualize on a small computer screen +and also may require substantial computing time.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} + +\item{condition}{Same as the \code{condition} argument to +\code{\link[bayesplot:MCMC-scatterplots]{mcmc_pairs}} except the \emph{default is different} +for \pkg{rstanarm} models. By default, the \code{mcmc_pairs} function in +the \pkg{bayesplot} package plots some of the Markov chains (half, in the +case of an even number of chains) in the panels above the diagonal and the +other half in the panels below the diagonal. However since we know that +\pkg{rstanarm} models were fit using Stan (which \pkg{bayesplot} doesn't +assume) we can make the default more useful by splitting the draws +according to the \code{accept_stat__} diagnostic. The plots below the +diagonal will contain realizations that are below the median +\code{accept_stat__} and the plots above the diagonal will contain +realizations that are above the median \code{accept_stat__}. To change this +behavior see the documentation of the \code{condition} argument at +\code{\link[bayesplot:MCMC-scatterplots]{mcmc_pairs}}.} + +\item{...}{Optional arguments passed to +\code{\link[bayesplot:MCMC-scatterplots]{mcmc_pairs}}. +The \code{np}, \code{lp}, and \code{max_treedepth} arguments to +\code{mcmc_pairs} are handled automatically by \pkg{rstanarm} and do not +need to be specified by the user in \code{...}. The arguments that can be +specified in \code{...} include \code{transformations}, \code{diag_fun}, +\code{off_diag_fun}, \code{diag_args}, \code{off_diag_args}, +and \code{np_style}. These arguments are +documented thoroughly on the help page for +\code{\link[bayesplot:MCMC-scatterplots]{mcmc_pairs}}.} +} +\description{ +Interface to \pkg{bayesplot}'s +\code{\link[bayesplot:MCMC-scatterplots]{mcmc_pairs}} function for use with +\pkg{rstanarm} models. Be careful not to specify too many parameters to +include or the plot will be both hard to read and slow to render. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +if (!exists("example_model")) example(example_model) + +bayesplot::color_scheme_set("purple") + +# see 'condition' argument above for details on the plots below and +# above the diagonal. default is to split by accept_stat__. +pairs(example_model, pars = c("(Intercept)", "log-posterior")) + +# for demonstration purposes, intentionally fit a model that +# will (almost certainly) have some divergences +fit <- stan_glm( + mpg ~ ., data = mtcars, + iter = 1000, + # this combo of prior and adapt_delta should lead to some divergences + prior = hs(), + adapt_delta = 0.9, + refresh = 0 +) + +pairs(fit, pars = c("wt", "sigma", "log-posterior")) + +# requires hexbin package +# pairs( +# fit, +# pars = c("wt", "sigma", "log-posterior"), +# transformations = list(sigma = "log"), # show log(sigma) instead of sigma +# off_diag_fun = "hex" # use hexagonal heatmaps instead of scatterplots +# ) + +bayesplot::color_scheme_set("brightblue") +pairs( + fit, + pars = c("(Intercept)", "wt", "sigma", "log-posterior"), + transformations = list(sigma = "log"), + off_diag_args = list(size = 3/4, alpha = 1/3), # size and transparency of scatterplot points + np_style = pairs_style_np(div_color = "black", div_shape = 2) # color and shape of the divergences +) + +# Using the condition argument to show divergences above the diagonal +pairs( + fit, + pars = c("(Intercept)", "wt", "log-posterior"), + condition = pairs_condition(nuts = "divergent__") +) + +} +} +} diff --git a/man/plot.predict.stanjm.Rd b/man/plot.predict.stanjm.Rd new file mode 100644 index 000000000..cf78bcea0 --- /dev/null +++ b/man/plot.predict.stanjm.Rd @@ -0,0 +1,122 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_traj.R +\name{plot.predict.stanjm} +\alias{plot.predict.stanjm} +\title{Plot the estimated subject-specific or marginal longitudinal trajectory} +\usage{ +\method{plot}{predict.stanjm}( + x, + ids = NULL, + limits = c("ci", "pi", "none"), + xlab = NULL, + ylab = NULL, + vline = FALSE, + plot_observed = FALSE, + facet_scales = "free_x", + ci_geom_args = NULL, + grp_overlay = FALSE, + ... +) +} +\arguments{ +\item{x}{A data frame and object of class \code{predict.stanjm} +returned by a call to the function \code{\link{posterior_traj}}. +The object contains point estimates and uncertainty interval limits +for the fitted values of the longitudinal response.} + +\item{ids}{An optional vector providing a subset of subject IDs for whom +the predicted curves should be plotted.} + +\item{limits}{A quoted character string specifying the type of limits to +include in the plot. Can be one of: \code{"ci"} for the Bayesian +posterior uncertainty interval for the estimated mean longitudinal +response (often known as a credible interval); +\code{"pi"} for the prediction interval for the estimated (raw) +longitudinal response; or \code{"none"} for no interval limits.} + +\item{xlab, ylab}{An optional axis label passed to +\code{\link[ggplot2]{labs}}.} + +\item{vline}{A logical. If \code{TRUE} then a vertical dashed line +is added to the plot indicating the event or censoring time for +the individual. Can only be used if each plot within the figure +is for a single individual.} + +\item{plot_observed}{A logical. If \code{TRUE} then the observed +longitudinal measurements are overlaid on the plot.} + +\item{facet_scales}{A character string passed to the \code{scales} +argument of \code{\link[ggplot2]{facet_wrap}} when plotting the +longitudinal trajectory for more than one individual.} + +\item{ci_geom_args}{Optional arguments passed to +\code{\link[ggplot2]{geom_ribbon}} and used to control features +of the plotted interval limits. They should be supplied as a named list.} + +\item{grp_overlay}{Only relevant if the model had lower level units +clustered within an individual. If \code{TRUE}, then the fitted trajectories +for the lower level units will be overlaid in the same plot region (that +is, all lower level units for a single individual will be shown within a +single facet). If \code{FALSE}, then the fitted trajectories for each lower +level unit will be shown in a separate facet.} + +\item{...}{Optional arguments passed to +\code{\link[ggplot2]{geom_smooth}} and used to control features +of the plotted longitudinal trajectory.} +} +\value{ +A \code{ggplot} object, also of class \code{plot.predict.stanjm}. + This object can be further customised using the \pkg{ggplot2} package. + It can also be passed to the function \code{\link{plot_stack_jm}}. +} +\description{ +This generic \code{plot} method for \code{predict.stanjm} objects will +plot the estimated subject-specific or marginal longitudinal trajectory +using the data frame returned by a call to \code{\link{posterior_traj}}. +To ensure that enough data points are available to plot the longitudinal +trajectory, it is assumed that the call to \code{\link{posterior_traj}} +would have used the default \code{interpolate = TRUE}, and perhaps also +\code{extrapolate = TRUE} (the latter being optional, depending on +whether or not the user wants to see extrapolation of the longitudinal +trajectory beyond the last observation time). +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + # Run example model if not already loaded + if (!exists("example_jm")) example(example_jm) + + # For a subset of individuals in the estimation dataset we will + # obtain subject-specific predictions for the longitudinal submodel + # at evenly spaced times between 0 and their event or censoring time. + pt1 <- posterior_traj(example_jm, ids = c(7,13,15), interpolate = TRUE) + plot(pt1) # credible interval for mean response + plot(pt1, limits = "pi") # prediction interval for raw response + plot(pt1, limits = "none") # no uncertainty interval + + # We can also extrapolate the longitudinal trajectories. + pt2 <- posterior_traj(example_jm, ids = c(7,13,15), interpolate = TRUE, + extrapolate = TRUE) + plot(pt2) + plot(pt2, vline = TRUE) # add line indicating event or censoring time + plot(pt2, vline = TRUE, plot_observed = TRUE) # overlay observed longitudinal data + + # We can change or add attributes to the plot + plot1 <- plot(pt2, ids = c(7,13,15), xlab = "Follow up time", + vline = TRUE, plot_observed = TRUE, + facet_scales = "fixed", color = "blue", linetype = 2, + ci_geom_args = list(fill = "red")) + plot1 + + # Since the returned plot is also a ggplot object, we can + # modify some of its attributes after it has been returned + plot1 + + ggplot2::theme(strip.background = ggplot2::element_blank()) + + ggplot2::labs(title = "Some plotted longitudinal trajectories") +} +} +} +\seealso{ +\code{\link{posterior_traj}}, \code{\link{plot_stack_jm}}, + \code{\link{posterior_survfit}}, \code{\link{plot.survfit.stanjm}} +} diff --git a/man/plot.stanreg.Rd b/man/plot.stanreg.Rd new file mode 100644 index 000000000..d222e0268 --- /dev/null +++ b/man/plot.stanreg.Rd @@ -0,0 +1,169 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plots.R +\name{plot.stanreg} +\alias{plot.stanreg} +\title{Plot method for stanreg objects} +\usage{ +\method{plot}{stanreg}(x, plotfun = "intervals", pars = NULL, regex_pars = NULL, ...) +} +\arguments{ +\item{x}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{plotfun}{A character string naming the \pkg{bayesplot} +\link[bayesplot:MCMC-overview]{MCMC} function to use. The default is to call +\code{\link[bayesplot:MCMC-intervals]{mcmc_intervals}}. \code{plotfun} can be specified +either as the full name of a \pkg{bayesplot} plotting function (e.g. +\code{"mcmc_hist"}) or can be abbreviated to the part of the name following +the \code{"mcmc_"} prefix (e.g. \code{"hist"}). To get the names of all +available MCMC functions see \code{\link[bayesplot:available_ppc]{available_mcmc}}.} + +\item{pars}{An optional character vector of parameter names.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} + +\item{...}{Additional arguments to pass to \code{plotfun} for customizing the +plot. These are described on the help pages for the individual plotting +functions. For example, the arguments accepted for the default +\code{plotfun="intervals"} can be found at +\code{\link[bayesplot:MCMC-intervals]{mcmc_intervals}}.} +} +\value{ +Either a ggplot object that can be further customized using the + \pkg{ggplot2} package, or an object created from multiple ggplot objects + (e.g. a gtable object created by \code{\link[gridExtra]{arrangeGrob}}). +} +\description{ +The \code{plot} method for \link{stanreg-objects} provides a convenient +interface to the \link[bayesplot:MCMC-overview]{MCMC} module in the +\pkg{\link{bayesplot}} package for plotting MCMC draws and diagnostics. It is also +straightforward to use the functions from the \pkg{bayesplot} package directly rather than +via the \code{plot} method. Examples of both methods of plotting are given +below. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +# Use rstanarm example model +if (!exists("example_model")) example(example_model) +fit <- example_model + +##################################### +### Intervals and point estimates ### +##################################### +plot(fit) # same as plot(fit, "intervals"), plot(fit, "mcmc_intervals") + +p <- plot(fit, pars = "size", regex_pars = "period", + prob = 0.5, prob_outer = 0.9) +p + ggplot2::ggtitle("Posterior medians \n with 50\% and 90\% intervals") + +# Shaded areas under densities +bayesplot::color_scheme_set("brightblue") +plot(fit, "areas", regex_pars = "period", + prob = 0.5, prob_outer = 0.9) + +# Make the same plot by extracting posterior draws and calling +# bayesplot::mcmc_areas directly +x <- as.array(fit, regex_pars = "period") +bayesplot::mcmc_areas(x, prob = 0.5, prob_outer = 0.9) + +# Ridgelines version of the areas plot +bayesplot::mcmc_areas_ridges(x, regex_pars = "period", prob = 0.9) + + +################################## +### Histograms & density plots ### +################################## +plot_title <- ggplot2::ggtitle("Posterior Distributions") +plot(fit, "hist", regex_pars = "period") + plot_title +plot(fit, "dens_overlay", pars = "(Intercept)", + regex_pars = "period") + plot_title + +#################### +### Scatterplots ### +#################### +bayesplot::color_scheme_set("teal") +plot(fit, "scatter", pars = paste0("period", 2:3)) +plot(fit, "scatter", pars = c("(Intercept)", "size"), + size = 3, alpha = 0.5) + + ggplot2::stat_ellipse(level = 0.9) + + +#################################################### +### Rhat, effective sample size, autocorrelation ### +#################################################### +bayesplot::color_scheme_set("red") + +# rhat +plot(fit, "rhat") +plot(fit, "rhat_hist") + +# ratio of effective sample size to total posterior sample size +plot(fit, "neff") +plot(fit, "neff_hist") + +# autocorrelation by chain +plot(fit, "acf", pars = "(Intercept)", regex_pars = "period") +plot(fit, "acf_bar", pars = "(Intercept)", regex_pars = "period") + + +################## +### Traceplots ### +################## +# NOTE: rstanarm doesn't store the warmup draws (to save space because they +# are not so essential for diagnosing the particular models implemented in +# rstanarm) so the iterations in the traceplot are post-warmup iterations + +bayesplot::color_scheme_set("pink") +(trace <- plot(fit, "trace", pars = "(Intercept)")) + +# change traceplot colors to ggplot defaults or custom values +trace + ggplot2::scale_color_discrete() +trace + ggplot2::scale_color_manual(values = c("maroon", "skyblue2")) + +# changing facet layout +plot(fit, "trace", pars = c("(Intercept)", "period2"), + facet_args = list(nrow = 2)) +# same plot by calling bayesplot::mcmc_trace directly +x <- as.array(fit, pars = c("(Intercept)", "period2")) +bayesplot::mcmc_trace(x, facet_args = list(nrow = 2)) + + +############ +### More ### +############ + +# regex_pars examples +plot(fit, regex_pars = "herd:1\\\\]") +plot(fit, regex_pars = "herd:[279]") +plot(fit, regex_pars = "herd:[279]|period2") +plot(fit, regex_pars = c("herd:[279]", "period2")) +} + +# For graphical posterior predictive checks see +# help("pp_check.stanreg") +} +} +\references{ +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}) +} +\seealso{ +\itemize{ + \item The vignettes in the \pkg{bayesplot} package for many examples. + \item \code{\link[bayesplot]{MCMC-overview}} (\pkg{bayesplot}) for links to + the documentation for all the available plotting functions. + \item \code{\link[bayesplot:bayesplot-colors]{color_scheme_set}} (\pkg{bayesplot}) to change + the color scheme used for plotting. + \item \code{\link{pp_check}} for graphical posterior predictive checks. + \item \code{\link{plot_nonlinear}} for models with nonlinear smooth + functions fit using \code{\link{stan_gamm4}}. +} +} diff --git a/man/plot.survfit.stanjm.Rd b/man/plot.survfit.stanjm.Rd new file mode 100644 index 000000000..20d3e1165 --- /dev/null +++ b/man/plot.survfit.stanjm.Rd @@ -0,0 +1,147 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_survfit.R +\name{plot.survfit.stanjm} +\alias{plot.survfit.stanjm} +\alias{plot_stack_jm} +\title{Plot the estimated subject-specific or marginal survival function} +\usage{ +\method{plot}{survfit.stanjm}( + x, + ids = NULL, + limits = c("ci", "none"), + xlab = NULL, + ylab = NULL, + facet_scales = "free", + ci_geom_args = NULL, + ... +) + +plot_stack_jm(yplot, survplot) +} +\arguments{ +\item{x}{A data frame and object of class \code{survfit.stanjm} +returned by a call to the function \code{\link{posterior_survfit}}. +The object contains point estimates and uncertainty interval limits +for estimated values of the survival function.} + +\item{ids}{An optional vector providing a subset of subject IDs for whom +the predicted curves should be plotted.} + +\item{limits}{A quoted character string specifying the type of limits to +include in the plot. Can be one of: \code{"ci"} for the Bayesian +posterior uncertainty interval for the estimated survival probability +(often known as a credible interval); or \code{"none"} for no interval +limits.} + +\item{xlab, ylab}{An optional axis label passed to +\code{\link[ggplot2]{labs}}.} + +\item{facet_scales}{A character string passed to the \code{scales} +argument of \code{\link[ggplot2]{facet_wrap}} when plotting the +longitudinal trajectory for more than one individual.} + +\item{ci_geom_args}{Optional arguments passed to +\code{\link[ggplot2]{geom_ribbon}} and used to control features +of the plotted interval limits. They should be supplied as a named list.} + +\item{...}{Optional arguments passed to +\code{\link[ggplot2:geom_path]{geom_line}} and used to control features +of the plotted survival function.} + +\item{yplot}{An object of class \code{plot.predict.stanjm}, returned by a +call to the generic \code{\link[=plot.predict.stanjm]{plot}} method for +objects of class \code{predict.stanjm}. If there is more than one +longitudinal outcome, then a list of such objects can be provided.} + +\item{survplot}{An object of class \code{plot.survfit.stanjm}, returned by a +call to the generic \code{\link[=plot.survfit.stanjm]{plot}} method for +objects of class \code{survfit.stanjm}.} +} +\value{ +The plot method returns a \code{ggplot} object, also of class + \code{plot.survfit.stanjm}. This object can be further customised using the + \pkg{ggplot2} package. It can also be passed to the function + \code{plot_stack_jm}. + +\code{plot_stack_jm} returns an object of class + \code{\link[bayesplot]{bayesplot_grid}} that includes plots of the + estimated subject-specific longitudinal trajectories stacked on top of the + associated subject-specific survival curve. +} +\description{ +This generic \code{plot} method for \code{survfit.stanjm} objects will +plot the estimated subject-specific or marginal survival function +using the data frame returned by a call to \code{\link{posterior_survfit}}. +The call to \code{posterior_survfit} should ideally have included an +"extrapolation" of the survival function, obtained by setting the +\code{extrapolate} argument to \code{TRUE}. + +The \code{plot_stack_jm} function takes arguments containing the plots of the estimated +subject-specific longitudinal trajectory (or trajectories if a multivariate +joint model was estimated) and the plot of the estimated subject-specific +survival function and combines them into a single figure. This is most +easily understood by running the \strong{Examples} below. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + # Run example model if not already loaded + if (!exists("example_jm")) example(example_jm) + + # Obtain subject-specific conditional survival probabilities + # for all individuals in the estimation dataset. + ps1 <- posterior_survfit(example_jm, extrapolate = TRUE) + + # We then plot the conditional survival probabilities for + # a subset of individuals + plot(ps1, ids = c(7,13,15)) + # We can change or add attributes to the plot + plot(ps1, ids = c(7,13,15), limits = "none") + plot(ps1, ids = c(7,13,15), xlab = "Follow up time") + plot(ps1, ids = c(7,13,15), ci_geom_args = list(fill = "red"), + color = "blue", linetype = 2) + plot(ps1, ids = c(7,13,15), facet_scales = "fixed") + + # Since the returned plot is also a ggplot object, we can + # modify some of its attributes after it has been returned + plot1 <- plot(ps1, ids = c(7,13,15)) + plot1 + + ggplot2::theme(strip.background = ggplot2::element_blank()) + + ggplot2::coord_cartesian(xlim = c(0, 15)) + + ggplot2::labs(title = "Some plotted survival functions") + + # We can also combine the plot(s) of the estimated + # subject-specific survival functions, with plot(s) + # of the estimated longitudinal trajectories for the + # same individuals + ps1 <- posterior_survfit(example_jm, ids = c(7,13,15)) + pt1 <- posterior_traj(example_jm, , ids = c(7,13,15)) + plot_surv <- plot(ps1) + plot_traj <- plot(pt1, vline = TRUE, plot_observed = TRUE) + plot_stack_jm(plot_traj, plot_surv) + + # Lastly, let us plot the standardised survival function + # based on all individuals in our estimation dataset + ps2 <- posterior_survfit(example_jm, standardise = TRUE, times = 0, + control = list(epoints = 20)) + plot(ps2) +} +} +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + if (!exists("example_jm")) example(example_jm) + ps1 <- posterior_survfit(example_jm, ids = c(7,13,15)) + pt1 <- posterior_traj(example_jm, ids = c(7,13,15), extrapolate = TRUE) + plot_surv <- plot(ps1) + plot_traj <- plot(pt1, vline = TRUE, plot_observed = TRUE) + plot_stack_jm(plot_traj, plot_surv) +} +} +} +\seealso{ +\code{\link{posterior_survfit}}, \code{\link{plot_stack_jm}}, + \code{\link{posterior_traj}}, \code{\link{plot.predict.stanjm}} + +\code{\link{plot.predict.stanjm}}, \code{\link{plot.survfit.stanjm}}, + \code{\link{posterior_predict}}, \code{\link{posterior_survfit}} +} diff --git a/man/posterior_interval.stanreg.Rd b/man/posterior_interval.stanreg.Rd new file mode 100644 index 000000000..e412b8daa --- /dev/null +++ b/man/posterior_interval.stanreg.Rd @@ -0,0 +1,113 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_interval.R +\name{posterior_interval.stanreg} +\alias{posterior_interval.stanreg} +\alias{posterior_interval} +\title{Posterior uncertainty intervals} +\usage{ +\method{posterior_interval}{stanreg}( + object, + prob = 0.9, + type = "central", + pars = NULL, + regex_pars = NULL, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{prob}{A number \eqn{p \in (0,1)}{p (0 < p < 1)} indicating the desired +probability mass to include in the intervals. The default is to report +\eqn{90}\% intervals (\code{prob=0.9}) rather than the traditionally used +\eqn{95}\% (see Details).} + +\item{type}{The type of interval to compute. Currently the only option is +\code{"central"} (see Details). A central \eqn{100p}\% +interval is defined by the \eqn{\alpha/2} and \eqn{1 - \alpha/2} quantiles, +where \eqn{\alpha = 1 - p}.} + +\item{pars}{An optional character vector of parameter names.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} + +\item{...}{Currently ignored.} +} +\value{ +A matrix with two columns and as many rows as model parameters (or + the subset of parameters specified by \code{pars} and/or + \code{regex_pars}). For a given value of \code{prob}, \eqn{p}, the columns + correspond to the lower and upper \eqn{100p}\% interval limits and have the + names \eqn{100\alpha/2}\% and \eqn{100(1 - \alpha/2)}\%, where \eqn{\alpha + = 1-p}. For example, if \code{prob=0.9} is specified (a \eqn{90}\% + interval), then the column names will be \code{"5\%"} and \code{"95\%"}, + respectively. +} +\description{ +For models fit using MCMC (\code{algorithm="sampling"}) or one of the +variational approximations (\code{"meanfield"} or \code{"fullrank"}), the +\code{posterior_interval} function computes Bayesian posterior uncertainty +intervals. These intervals are often referred to as \emph{credible} +intervals, but we use the term \emph{uncertainty} intervals to highlight the +fact that wider intervals correspond to greater uncertainty. +} +\details{ +\subsection{Interpretation}{ +Unlike for a frenquentist confidence interval, it is valid to say that, +conditional on the data and model, we believe that with probability \eqn{p} +the value of a parameter is in its \eqn{100p}\% posterior interval. This +intuitive interpretation of Bayesian intervals is often erroneously applied +to frequentist confidence intervals. See Morey et al. (2015) for more details +on this issue and the advantages of using Bayesian posterior uncertainty +intervals (also known as credible intervals). +} +\subsection{Default 90\% intervals}{ +We default to reporting \eqn{90}\% intervals rather than \eqn{95}\% intervals +for several reasons: +\itemize{ + \item Computational stability: \eqn{90}\% intervals are more stable than + \eqn{95}\% intervals (for which each end relies on only \eqn{2.5}\% of the + posterior draws). \item Relation to Type-S errors (Gelman and Carlin, 2014): + \eqn{95}\% of the mass in a \eqn{90}\% central interval is above the lower + value (and \eqn{95}\% is below the upper value). For a parameter + \eqn{\theta}, it is therefore easy to see if the posterior probability that + \eqn{\theta > 0} (or \eqn{\theta < 0}) is larger or smaller than \eqn{95}\%. +} +Of course, if \eqn{95}\% intervals are desired they can be computed by +specifying \code{prob=0.95}. +} +\subsection{Types of intervals}{ +Currently \code{posterior_interval} only computes central intervals because +other types of intervals are rarely useful for the models that \pkg{rstanarm} +can estimate. Additional possibilities may be provided in future releases as +more models become available. +} +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +posterior_interval(example_model) +posterior_interval(example_model, regex_pars = "herd") +posterior_interval(example_model, pars = "period2", prob = 0.5) +} +} +\references{ +Gelman, A. and Carlin, J. (2014). Beyond power calculations: +assessing Type S (sign) and Type M (magnitude) errors. \emph{Perspectives on +Psychological Science}. 9(6), 641--51. + +Morey, R. D., Hoekstra, R., Rouder, J., Lee, M. D., and Wagenmakers, E. +(2016). The fallacy of placing confidence in confidence intervals. +\emph{Psychonomic Bulletin & Review}. 23(1), 103--123. +} +\seealso{ +\code{\link{confint.stanreg}}, which, for models fit using optimization, can +be used to compute traditional confidence intervals. + +\code{\link{predictive_interval}} for predictive intervals. +} diff --git a/man/posterior_linpred.stanreg.Rd b/man/posterior_linpred.stanreg.Rd new file mode 100644 index 000000000..bbe01d6b1 --- /dev/null +++ b/man/posterior_linpred.stanreg.Rd @@ -0,0 +1,103 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_linpred.R +\name{posterior_linpred.stanreg} +\alias{posterior_linpred.stanreg} +\alias{posterior_linpred} +\alias{posterior_epred} +\alias{posterior_epred.stanreg} +\title{Posterior distribution of the (possibly transformed) linear predictor} +\usage{ +\method{posterior_linpred}{stanreg}( + object, + transform = FALSE, + newdata = NULL, + draws = NULL, + re.form = NULL, + offset = NULL, + XZ = FALSE, + ... +) + +\method{posterior_epred}{stanreg}( + object, + newdata = NULL, + draws = NULL, + re.form = NULL, + offset = NULL, + XZ = FALSE, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{transform}{Should the linear predictor be transformed using the +inverse-link function? The default is \code{FALSE}. This argument is still +allowed but not recommended because the \code{posterior_epred} function now +provides the equivalent of \code{posterior_linpred(..., transform=TRUE)}. +See \strong{Examples}.} + +\item{newdata, draws, re.form, offset}{Same as for \code{\link{posterior_predict}}.} + +\item{XZ}{If \code{TRUE} then instead of computing the linear predictor the +design matrix \code{X} (or \code{cbind(X,Z)} for models with group-specific +terms) constructed from \code{newdata} is returned. The default is +\code{FALSE}.} + +\item{...}{Currently ignored.} +} +\value{ +The default is to return a \code{draws} by \code{nrow(newdata)} + matrix of simulations from the posterior distribution of the (possibly + transformed) linear predictor. The exception is if the argument \code{XZ} + is set to \code{TRUE} (see the \code{XZ} argument description above). +} +\description{ +Extract the posterior draws of the linear predictor, possibly transformed by +the inverse-link function. This function is occasionally useful, but it +should be used sparingly: inference and model checking should generally be +carried out using the posterior predictive distribution (i.e., using +\code{\link{posterior_predict}}). +} +\details{ +The \code{posterior_linpred} function returns the posterior + distribution of the linear predictor, while the \code{posterior_epred} + function returns the posterior distribution of the conditional expectation. + In the special case of a Gaussian likelihood with an identity link + function, these two concepts are the same. The \code{posterior_epred} + function is a less noisy way to obtain expectations over the output of + \code{\link{posterior_predict}}. +} +\note{ +For models estimated with \code{\link{stan_clogit}}, the number of + successes per stratum is ostensibly fixed by the research design. Thus, + when calling \code{posterior_linpred} with new data and \code{transform = + TRUE}, the \code{data.frame} passed to the \code{newdata} argument must + contain an outcome variable and a stratifying factor, both with the same + name as in the original \code{data.frame}. Then, the probabilities will + condition on this outcome in the new data. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +print(family(example_model)) + +# linear predictor on log-odds scale +linpred <- posterior_linpred(example_model) +colMeans(linpred) + +# probabilities +# same as posterior_linpred(example_model, transform = TRUE) +probs <- posterior_epred(example_model) +colMeans(probs) + +# not conditioning on any group-level parameters +probs2 <- posterior_epred(example_model, re.form = NA) +apply(probs2, 2, median) +} +} +\seealso{ +\code{\link{posterior_predict}} to draw from the posterior + predictive distribution of the outcome, which is typically preferable. +} diff --git a/man/posterior_predict.stanreg.Rd b/man/posterior_predict.stanreg.Rd new file mode 100644 index 000000000..d618a411c --- /dev/null +++ b/man/posterior_predict.stanreg.Rd @@ -0,0 +1,174 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_predict.R +\name{posterior_predict.stanreg} +\alias{posterior_predict.stanreg} +\alias{posterior_predict} +\alias{posterior_predict.stanmvreg} +\title{Draw from posterior predictive distribution} +\usage{ +\method{posterior_predict}{stanreg}( + object, + newdata = NULL, + draws = NULL, + re.form = NULL, + fun = NULL, + seed = NULL, + offset = NULL, + ... +) + +\method{posterior_predict}{stanmvreg}( + object, + m = 1, + newdata = NULL, + draws = NULL, + re.form = NULL, + fun = NULL, + seed = NULL, + offset = NULL, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{newdata}{Optionally, a data frame in which to look for variables with +which to predict. If omitted, the model matrix is used. If \code{newdata} +is provided and any variables were transformed (e.g. rescaled) in the data +used to fit the model, then these variables must also be transformed in +\code{newdata}. This only applies if variables were transformed before +passing the data to one of the modeling functions and \emph{not} if +transformations were specified inside the model formula. Also see the Note +section below for a note about using the \code{newdata} argument with with +binomial models.} + +\item{draws}{An integer indicating the number of draws to return. The default +and maximum number of draws is the size of the posterior sample.} + +\item{re.form}{If \code{object} contains \code{\link[=stan_glmer]{group-level}} +parameters, a formula indicating which group-level parameters to +condition on when making predictions. \code{re.form} is specified in the +same form as for \code{\link[lme4]{predict.merMod}}. The default, +\code{NULL}, indicates that all estimated group-level parameters are +conditioned on. To refrain from conditioning on any group-level parameters, +specify \code{NA} or \code{~0}. The \code{newdata} argument may include new +\emph{levels} of the grouping factors that were specified when the model +was estimated, in which case the resulting posterior predictions +marginalize over the relevant variables.} + +\item{fun}{An optional function to apply to the results. \code{fun} is found +by a call to \code{\link{match.fun}} and so can be specified as a function +object, a string naming a function, etc.} + +\item{seed}{An optional \code{\link[=set.seed]{seed}} to use.} + +\item{offset}{A vector of offsets. Only required if \code{newdata} is +specified and an \code{offset} argument was specified when fitting the +model.} + +\item{...}{For \code{stanmvreg} objects, argument \code{m} can be specified +indicating the submodel for which you wish to obtain predictions.} + +\item{m}{Integer specifying the number or name of the submodel} +} +\value{ +A \code{draws} by \code{nrow(newdata)} matrix of simulations from the + posterior predictive distribution. Each row of the matrix is a vector of + predictions generated using a single draw of the model parameters from the + posterior distribution. +} +\description{ +The posterior predictive distribution is the distribution of the outcome +implied by the model after using the observed data to update our beliefs +about the unknown parameters in the model. Simulating data from the posterior +predictive distribution using the observed predictors is useful for checking +the fit of the model. Drawing from the posterior predictive distribution at +interesting values of the predictors also lets us visualize how a +manipulation of a predictor affects (a function of) the outcome(s). With new +observations of predictor variables we can use the posterior predictive +distribution to generate predicted outcomes. +} +\note{ +For binomial models with a number of trials greater than one (i.e., not + Bernoulli models), if \code{newdata} is specified then it must include all + variables needed for computing the number of binomial trials to use for the + predictions. For example if the left-hand side of the model formula is + \code{cbind(successes, failures)} then both \code{successes} and + \code{failures} must be in \code{newdata}. The particular values of + \code{successes} and \code{failures} in \code{newdata} do not matter so + long as their sum is the desired number of trials. If the left-hand side of + the model formula were \code{cbind(successes, trials - successes)} then + both \code{trials} and \code{successes} would need to be in \code{newdata}, + probably with \code{successes} set to \code{0} and \code{trials} specifying + the number of trials. See the Examples section below and the + \emph{How to Use the rstanarm Package} for examples. + +For models estimated with \code{\link{stan_clogit}}, the number of + successes per stratum is ostensibly fixed by the research design. Thus, when + doing posterior prediction with new data, the \code{data.frame} passed to + the \code{newdata} argument must contain an outcome variable and a stratifying + factor, both with the same name as in the original \code{data.frame}. Then, the + posterior predictions will condition on this outcome in the new data. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +yrep <- posterior_predict(example_model) +table(yrep) + +\donttest{ +# Using newdata +counts <- c(18,17,15,20,10,20,25,13,12) +outcome <- gl(3,1,9) +treatment <- gl(3,3) +dat <- data.frame(counts, treatment, outcome) +fit3 <- stan_glm( + counts ~ outcome + treatment, + data = dat, + family = poisson(link="log"), + prior = normal(0, 1, autoscale = FALSE), + prior_intercept = normal(0, 5, autoscale = FALSE), + refresh = 0 +) +nd <- data.frame(treatment = factor(rep(1,3)), outcome = factor(1:3)) +ytilde <- posterior_predict(fit3, nd, draws = 500) +print(dim(ytilde)) # 500 by 3 matrix (draws by nrow(nd)) + +ytilde <- data.frame( + count = c(ytilde), + outcome = rep(nd$outcome, each = 500) +) +ggplot2::ggplot(ytilde, ggplot2::aes(x=outcome, y=count)) + + ggplot2::geom_boxplot() + + ggplot2::ylab("predicted count") + + +# Using newdata with a binomial model. +# example_model is binomial so we need to set +# the number of trials to use for prediction. +# This could be a different number for each +# row of newdata or the same for all rows. +# Here we'll use the same value for all. +nd <- lme4::cbpp +print(formula(example_model)) # cbind(incidence, size - incidence) ~ ... +nd$size <- max(nd$size) + 1L # number of trials +nd$incidence <- 0 # set to 0 so size - incidence = number of trials +ytilde <- posterior_predict(example_model, newdata = nd) + + +# Using fun argument to transform predictions +mtcars2 <- mtcars +mtcars2$log_mpg <- log(mtcars2$mpg) +fit <- stan_glm(log_mpg ~ wt, data = mtcars2, refresh = 0) +ytilde <- posterior_predict(fit, fun = exp) +} +} +} +\seealso{ +\code{\link{pp_check}} for graphical posterior predictive checks. + Examples of posterior predictive checking can also be found in the + \pkg{rstanarm} vignettes and demos. + +\code{\link{predictive_error}} and \code{\link{predictive_interval}}. +} diff --git a/man/posterior_survfit.Rd b/man/posterior_survfit.Rd new file mode 100644 index 000000000..c678d34c6 --- /dev/null +++ b/man/posterior_survfit.Rd @@ -0,0 +1,287 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_survfit.R +\name{posterior_survfit} +\alias{posterior_survfit} +\title{Estimate subject-specific or standardised survival probabilities} +\usage{ +posterior_survfit( + object, + newdataLong = NULL, + newdataEvent = NULL, + extrapolate = TRUE, + control = list(), + condition = NULL, + last_time = NULL, + prob = 0.95, + ids, + times = NULL, + standardise = FALSE, + dynamic = TRUE, + scale = 1.5, + draws = NULL, + seed = NULL, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by the +\code{\link{stan_jm}} modelling function. See +\code{\link{stanreg-objects}}.} + +\item{newdataLong, newdataEvent}{Optionally, a data frame (or in the case of +\code{newdataLong} this can be a list of data frames) in which to look +for variables with which to predict. If omitted, the model matrices are used. +If new data is provided, then it should also contain the longitudinal +outcome data on which to condition when drawing the new group-specific +coefficients for individuals in the new data. Note that there is only +allowed to be one row of data for each individual in \code{newdataEvent}, +that is, time-varying covariates are not allowed in the prediction data for +the event submodel. Also, \code{newdataEvent} can optionally include a +variable with information about the last known survival time for the new +individuals -- see the description for the \code{last_time} argument below +-- however also note that when generating the survival probabilities it +is of course assumed that all individuals in \code{newdataEvent} have not +yet experienced the event (that is, any variable in \code{newdataEvent} that +corresponds to the event indicator will be ignored).} + +\item{extrapolate}{A logical specifying whether to extrapolate the estimated +survival probabilities beyond the times specified in the \code{times} argument. +If \code{TRUE} then the extrapolation can be further controlled using +the \code{control} argument.} + +\item{control}{A named list with parameters controlling extrapolation + of the estimated survival function when \code{extrapolate = TRUE}. The list + can contain one or more of the following named elements: \cr + \describe{ + \item{\code{epoints}}{a positive integer specifying the number of + discrete time points at which to calculate the forecasted survival + probabilities. The default is 10.} + \item{\code{edist}}{a positive scalar specifying the amount of time + across which to forecast the estimated survival function, represented + in units of the time variable \code{time_var} (from fitting the model). + The default is to extrapolate between the times specified in the + \code{times} argument and the maximum event or censoring time in the + original data. If \code{edist} leads to times that are beyond + the maximum event or censoring time in the original data then the + estimated survival probabilities will be truncated at that point, since + the estimate for the baseline hazard is not available beyond that time.} +}} + +\item{condition}{A logical specifying whether the estimated +subject-specific survival probabilities at time \code{t} should be +conditioned on survival up to a fixed time point \code{u}. The default +is for \code{condition} to be set to \code{TRUE}, unless standardised survival +probabilities have been requested (by specifying \code{standardise = TRUE}), +in which case \code{condition} must (and will) be set to \code{FALSE}. +When conditional survival probabilities are requested, the fixed +time point \code{u} will be either: (i) the value specified via the +\code{last_time} argument; or if the \code{last_time} argument is +\code{NULL} then the latest observation time for each individual +(taken to be the value in the \code{times} argument if \code{newdataEvent} +is specified, or the observed event or censoring time if \code{newdataEvent} +is \code{NULL}.} + +\item{last_time}{A scalar, character string, or \code{NULL}. This argument +specifies the last known survival time for each individual when +conditional predictions are being obtained. If +\code{newdataEvent} is provided and conditional survival predictions are being +obtained, then the \code{last_time} argument can be one of the following: +(i) a scalar, this will use the same last time for each individual in +\code{newdataEvent}; (ii) a character string, naming a column in +\code{newdataEvent} in which to look for the last time for each individual; +(iii) \code{NULL}, in which case the default is to use the time of the latest +longitudinal observation in \code{newdataLong}. If \code{newdataEvent} is +\code{NULL} then the \code{last_time} argument cannot be specified +directly; instead it will be set equal to the event or censoring time for +each individual in the dataset that was used to estimate the model. +If standardised survival probabilities are requested (i.e. +\code{standardise = TRUE}) then conditional survival probabilities are +not allowed and therefore the \code{last_time} argument is ignored.} + +\item{prob}{A scalar between 0 and 1 specifying the width to use for the +uncertainty interval (sometimes called credible interval) for the predictions. +For example \code{prob = 0.95} (the default) means that the 2.5th and 97.5th +percentiles will be provided.} + +\item{ids}{An optional vector specifying a subset of IDs for whom the +predictions should be obtained. The default is to predict for all individuals +who were used in estimating the model or, if \code{newdataLong} and +\code{newdataEvent} are specified, then all individuals contained in +the new data.} + +\item{times}{A scalar, a character string, or \code{NULL}. Specifies the +times at which the estimated survival probabilities should be calculated. +It can be either: (i) \code{NULL}, in which case it will default to the last known +survival time for each individual, as determined by the \code{last_time} +argument; (ii) a scalar, specifying a time to estimate the survival probability +for each of the individuals; or (iii) if \code{newdataEvent} is +provided, it can be the name of a variable in \code{newdataEvent} that +indicates the time at which the survival probabilities should be calculated +for each individual.} + +\item{standardise}{A logical specifying whether the estimated +subject-specific survival probabilities should be averaged +across all individuals for whom the subject-specific predictions are +being obtained. This can be used to average over the covariate and random effects +distributions of the individuals used in estimating the model, or the individuals +included in the \code{newdata} arguments. This approach of +averaging across the observed distribution of the covariates is sometimes +referred to as a "standardised" survival curve. If \code{standardise = TRUE}, +then the \code{times} argument must be specified and it must be constant across +individuals, that is, the survival probabilities must be calculated at the +same time for all individuals.} + +\item{dynamic}{A logical that is only relevant if new data is provided +via the \code{newdataLong} and \code{newdataEvent} arguments. If +\code{dynamic = TRUE}, then new group-specific parameters are drawn for +the individuals in the new data, conditional on their longitudinal +biomarker data contained in \code{newdataLong}. These group-specific +parameters are then used to generate individual-specific survival probabilities +for these individuals. These are often referred to as "dynamic predictions" +in the joint modelling context, because the predictions can be updated +each time additional longitudinal biomarker data is collected on the individual. +On the other hand, if \code{dynamic = FALSE} then the survival probabilities +will just be marginalised over the distribution of the group-specific +coefficients; this will mean that the predictions will incorporate all +uncertainty due to between-individual variation so there will likely be +very wide credible intervals on the predicted survival probabilities.} + +\item{scale}{A scalar, specifying how much to multiply the asymptotic +variance-covariance matrix for the random effects by, which is then +used as the "width" (ie. variance-covariance matrix) of the multivariate +Student-t proposal distribution in the Metropolis-Hastings algorithm. This +is only relevant when \code{newdataEvent} is supplied and +\code{dynamic = TRUE}, in which case new random effects are simulated +for the individuals in the new data using the Metropolis-Hastings algorithm.} + +\item{draws}{An integer indicating the number of MCMC draws to return. +The default is to set the number of draws equal to 200, or equal to the +size of the posterior sample if that is less than 200.} + +\item{seed}{An optional \code{\link[=set.seed]{seed}} to use.} + +\item{...}{Currently unused.} +} +\value{ +A data frame of class \code{survfit.stanjm}. The data frame includes + columns for each of the following: + (i) the median of the posterior predictions of the estimated survival + probabilities (\code{survpred}); + (ii) each of the lower and upper limits of the corresponding uncertainty + interval for the estimated survival probabilities (\code{ci_lb} and + \code{ci_ub}); + (iii) a subject identifier (\code{id_var}), unless standardised survival + probabilities were estimated; + (iv) the time that the estimated survival probability is calculated for + (\code{time_var}). + The returned object also includes a number of additional attributes. +} +\description{ +This function allows us to generate estimated survival probabilities +based on draws from the posterior predictive distribution. By default +the survival probabilities are conditional on an individual's +group-specific coefficients (i.e. their individual-level random +effects). If prediction data is provided via the \code{newdataLong} +and \code{newdataEvent} arguments, then the default behaviour is to +sample new group-specific coefficients for the individuals in the +new data using a Monte Carlo scheme that conditions on their +longitudinal outcome data provided in \code{newdataLong} +(sometimes referred to as "dynamic predictions", see Rizopoulos +(2011)). This default behaviour can be stopped by specifying +\code{dynamic = FALSE}, in which case the predicted survival +probabilities will be marginalised over the distribution of the +group-specific coefficients. This has the benefit that the user does +not need to provide longitudinal outcome measurements for the new +individuals, however, it does mean that the predictions will incorporate +all the uncertainty associated with between-individual variation, since +the predictions aren't conditional on any observed data for the individual. +In addition, by default, the predicted subject-specific survival +probabilities are conditional on observed values of the fixed effect +covariates (ie, the predictions will be obtained using either the design +matrices used in the original \code{\link{stan_jm}} model call, or using the +covariate values provided in the \code{newdataLong} and \code{newdataEvent} +arguments). However, if you wish to average over the observed distribution +of the fixed effect covariates then this is possible -- such predictions +are sometimes referred to as standardised survival probabilties -- see the +\code{standardise} argument below. +} +\note{ +Note that if any variables were transformed (e.g. rescaled) in the data + used to fit the model, then these variables must also be transformed in + \code{newdataLong} and \code{newdataEvent}. This only applies if variables + were transformed before passing the data to one of the modeling functions and + \emph{not} if transformations were specified inside the model formula. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + # Run example model if not already loaded + if (!exists("example_jm")) example(example_jm) + + # Obtain subject-specific survival probabilities for a few + # selected individuals in the estimation dataset who were + # known to survive up until their censoring time. By default + # the posterior_survfit function will estimate the conditional + # survival probabilities, that is, conditional on having survived + # until the event or censoring time, and then by default will + # extrapolate the survival predictions forward from there. + ps1 <- posterior_survfit(example_jm, ids = c(7,13,15)) + # We can plot the estimated survival probabilities using the + # associated plot function + plot(ps1) + + # If we wanted to estimate the survival probabilities for the + # same three individuals as the previous example, but this time + # we won't condition on them having survived up until their + # censoring time. Instead, we will estimate their probability + # of having survived between 0 and 5 years given their covariates + # and their estimated random effects. + # The easiest way to achieve the time scale we want (ie, 0 to 5 years) + # is to specify that we want the survival time estimated at time 0 + # and then extrapolated forward 5 years. We also specify that we + # do not want to condition on their last known survival time. + ps2 <- posterior_survfit(example_jm, ids = c(7,13,15), times = 0, + extrapolate = TRUE, condition = FALSE, control = list(edist = 5)) + + # Instead we may want to estimate subject-specific survival probabilities + # for a set of new individuals. To demonstrate this, we will simply take + # the first two individuals in the estimation dataset, but pass their data + # via the newdata arguments so that posterior_survfit will assume we are + # predicting survival for new individuals and draw new random effects + # under a Monte Carlo scheme (see Rizopoulos (2011)). + ndL <- pbcLong[pbcLong$id \%in\% c(1,2),] + ndE <- pbcSurv[pbcSurv$id \%in\% c(1,2),] + ps3 <- posterior_survfit(example_jm, + newdataLong = ndL, newdataEvent = ndE, + last_time = "futimeYears", seed = 12345) + head(ps3) + # We can then compare the estimated random effects for these + # individuals based on the fitted model and the Monte Carlo scheme + ranef(example_jm)$Long1$id[1:2,,drop=FALSE] # from fitted model + colMeans(attr(ps3, "b_new")) # from Monte Carlo scheme + + # Lastly, if we wanted to obtain "standardised" survival probabilities, + # (by averaging over the observed distribution of the fixed effect + # covariates, as well as averaging over the estimated random effects + # for individuals in our estimation sample or new data) then we can + # specify 'standardise = TRUE'. We can then plot the resulting + # standardised survival curve. + ps4 <- posterior_survfit(example_jm, standardise = TRUE, + times = 0, extrapolate = TRUE) + plot(ps4) +} +} +} +\references{ +Rizopoulos, D. (2011). Dynamic predictions and prospective accuracy in + joint models for longitudinal and time-to-event data. \emph{Biometrics} + \strong{67}, 819. +} +\seealso{ +\code{\link{plot.survfit.stanjm}} for plotting the estimated survival + probabilities, \code{\link{ps_check}} for for graphical checks of the estimated + survival function, and \code{\link{posterior_traj}} for estimating the + marginal or subject-specific longitudinal trajectories, and + \code{\link{plot_stack_jm}} for combining plots of the estimated subject-specific + longitudinal trajectory and survival function. +} diff --git a/man/posterior_traj.Rd b/man/posterior_traj.Rd new file mode 100644 index 000000000..6980418b3 --- /dev/null +++ b/man/posterior_traj.Rd @@ -0,0 +1,301 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_traj.R +\name{posterior_traj} +\alias{posterior_traj} +\title{Estimate the subject-specific or marginal longitudinal trajectory} +\usage{ +posterior_traj( + object, + m = 1, + newdata = NULL, + newdataLong = NULL, + newdataEvent = NULL, + interpolate = TRUE, + extrapolate = FALSE, + control = list(), + last_time = NULL, + prob = 0.95, + ids, + dynamic = TRUE, + scale = 1.5, + draws = NULL, + seed = NULL, + return_matrix = FALSE, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by the +\code{\link{stan_jm}} modelling function. See +\code{\link{stanreg-objects}}.} + +\item{m}{Integer specifying the number or name of the submodel} + +\item{newdata}{\strong{Deprecated}: please use \code{newdataLong} instead. +Optionally, a data frame in which to look for variables with +which to predict. If omitted, the model matrix is used. If \code{newdata} +is provided and any variables were transformed (e.g. rescaled) in the data +used to fit the model, then these variables must also be transformed in +\code{newdata}. This only applies if variables were transformed before +passing the data to one of the modeling functions and \emph{not} if +transformations were specified inside the model formula.} + +\item{newdataLong, newdataEvent}{Optionally, a data frame (or in the case of +\code{newdataLong} this can be a list of data frames) in which to look +for variables with which to predict. If omitted, the model matrices are used. +If new data is provided, then two options are available. Either one can +provide observed covariate and outcome data, collected up to some time +\emph{t}, and use this data to draw new individual-specific coefficients +(i.e. individual-level random effects). This is the default behaviour when +new data is provided, determined by the argument \code{dynamic = TRUE}, and +requiring both \code{newdataLong} and \code{newdataEvent} to be specified. +Alternatively, one can specify \code{dynamic = FALSE}, and then predict +using just covariate data, by marginalising over the distribution +of the group-specific coefficients; in this case, only \code{newdataLong} +needs to be specified and it only needs to be a single data frame with +the covariate data for the predictions for the one longitudinal submodel.} + +\item{interpolate}{A logical specifying whether to interpolate the estimated +longitudinal trajectory in between the observation times. This can be used +to achieve a smooth estimate of the longitudinal trajectory across the +entire follow up time. If \code{TRUE} then the interpolation can be further +controlled using the \code{control} argument.} + +\item{extrapolate}{A logical specifying whether to extrapolate the estimated +longitudinal trajectory beyond the time of the last known observation time. +If \code{TRUE} then the extrapolation can be further controlled using +the \code{control} argument.} + +\item{control}{A named list with parameters controlling the interpolation or +extrapolation of the estimated longitudinal trajectory when either +\code{interpolate = TRUE} or \code{extrapolate = TRUE}. The +list can contain one or more of the following named elements: \cr +\describe{ + \item{\code{ipoints}}{a positive integer specifying the number of discrete + time points at which to calculate the estimated longitudinal response for + \code{interpolate = TRUE}. These time points are evenly spaced starting at + 0 and ending at the last known observation time for each individual. The + last observation time for each individual is taken to be either: the + event or censoring time if no new data is provided; the time specified + in the "last_time" column if provided in the new data (see \strong{Details} + section below); or the time of the last longitudinal measurement if new + data is provided but no "last_time" column is included. The default is 15.} + \item{\code{epoints}}{a positive integer specifying the number of discrete + time points at which to calculate the estimated longitudinal response for + \code{extrapolate = TRUE}. These time points are evenly spaced between the + last known observation time for each individual and the extrapolation + distance specifed using either \code{edist} or \code{eprop}. + The default is 15.} + \item{\code{eprop}}{a positive scalar between 0 and 1 specifying the + amount of time across which to extrapolate the longitudinal trajectory, + represented as a proportion of the total observed follow up time for each + individual. For example specifying \code{eprop = 0.2} means that for an + individual for whom the latest of their measurement, event or censoring times + was 10 years, their estimated longitudinal trajectory will be extrapolated + out to 12 years (i.e. 10 + (0.2 * 10)). The default value is 0.2.} + \item{\code{edist}}{a positive scalar specifying the amount of time + across which to extrapolate the longitudinal trajectory for each individual, + represented in units of the time variable \code{time_var} (from fitting the + model). This cannot be specified if \code{eprop} is specified.} +}} + +\item{last_time}{A scalar, character string, or \code{NULL}. This argument +specifies the last known survival time for each individual when +conditional predictions are being obtained. If +\code{newdataEvent} is provided and conditional survival predictions are being +obtained, then the \code{last_time} argument can be one of the following: +(i) a scalar, this will use the same last time for each individual in +\code{newdataEvent}; (ii) a character string, naming a column in +\code{newdataEvent} in which to look for the last time for each individual; +(iii) \code{NULL}, in which case the default is to use the time of the latest +longitudinal observation in \code{newdataLong}. If \code{newdataEvent} is +\code{NULL} then the \code{last_time} argument cannot be specified +directly; instead it will be set equal to the event or censoring time for +each individual in the dataset that was used to estimate the model. +If standardised survival probabilities are requested (i.e. +\code{standardise = TRUE}) then conditional survival probabilities are +not allowed and therefore the \code{last_time} argument is ignored.} + +\item{prob}{A scalar between 0 and 1 specifying the width to use for the +uncertainty interval (sometimes called credible interval) for the predicted +mean response and the prediction interval for the predicted (raw) response. +For example \code{prob = 0.95} (the default) means that the 2.5th and 97.5th +percentiles will be provided. Only relevant when \code{return_matrix} is +\code{FALSE}.} + +\item{ids}{An optional vector specifying a subset of subject IDs for whom the +predictions should be obtained. The default is to predict for all individuals +who were used in estimating the model or, if \code{newdata} is specified, +then all individuals contained in \code{newdata}.} + +\item{dynamic}{A logical that is only relevant if new data is provided +via the \code{newdata} argument. If +\code{dynamic = TRUE}, then new group-specific parameters are drawn for +the individuals in the new data, conditional on their longitudinal +biomarker data contained in \code{newdata}. These group-specific +parameters are then used to generate individual-specific survival probabilities +for these individuals. These are often referred to as "dynamic predictions" +in the joint modelling context, because the predictions can be updated +each time additional longitudinal biomarker data is collected on the individual. +On the other hand, if \code{dynamic = FALSE} then the survival probabilities +will just be marginalised over the distribution of the group-specific +coefficients; this will mean that the predictions will incorporate all +uncertainty due to between-individual variation so there will likely be +very wide credible intervals on the predicted survival probabilities.} + +\item{scale}{A scalar, specifying how much to multiply the asymptotic +variance-covariance matrix for the random effects by, which is then +used as the "width" (ie. variance-covariance matrix) of the multivariate +Student-t proposal distribution in the Metropolis-Hastings algorithm. This +is only relevant when \code{newdataEvent} is supplied and +\code{dynamic = TRUE}, in which case new random effects are simulated +for the individuals in the new data using the Metropolis-Hastings algorithm.} + +\item{draws}{An integer indicating the number of MCMC draws to return. +The default is to set the number of draws equal to 200, or equal to the +size of the posterior sample if that is less than 200.} + +\item{seed}{An optional \code{\link[=set.seed]{seed}} to use.} + +\item{return_matrix}{A logical. If \code{TRUE} then a \code{draws} by +\code{nrow(newdata)} matrix is returned which contains all the actual +simulations or draws from the posterior predictive distribution. Otherwise +if \code{return_matrix} is set to \code{FALSE} (the default) then a +data frame is returned, as described in the \strong{Value} section below.} + +\item{...}{Other arguments passed to \code{\link{posterior_predict}}, for +example \code{draws}, \code{re.form}, \code{seed}, etc.} +} +\value{ +When \code{return_matrix = FALSE}, a data frame + of class \code{predict.stanjm}. The data frame includes a column for the median + of the posterior predictions of the mean longitudinal response (\code{yfit}), + a column for each of the lower and upper limits of the uncertainty interval + corresponding to the posterior predictions of the mean longitudinal response + (\code{ci_lb} and \code{ci_ub}), and a column for each of the lower and upper + limits of the prediction interval corresponding to the posterior predictions + of the (raw) longitudinal response. The data frame also includes columns for + the subject ID variable, and each of the predictor variables. The returned + object also includes a number of attributes. + + When \code{return_matrix = TRUE}, the returned object is the same as that + described for \code{\link{posterior_predict}}. +} +\description{ +This function allows us to generate an estimated longitudinal trajectory +(either subject-specific, or by marginalising over the distribution of the +group-specific parameters) based on draws from the posterior predictive +distribution. +} +\details{ +The \code{posterior_traj} function acts as a wrapper to the +\code{\link{posterior_predict}} function, but allows predictions to be +easily generated at time points that are interpolated and/or extrapolated +between time zero (baseline) and the last known survival time for the +individual, thereby providing predictions that correspond to a smooth estimate +of the longitudinal trajectory (useful for the plotting via the associated +\code{\link{plot.predict.stanjm}} method). In addition it returns a data +frame by default, whereas the \code{\link{posterior_predict}} function +returns a matrix; see the \strong{Value} section below for details. Also, +\code{posterior_traj} allows predictions to only be generated for a subset +of individuals, via the \code{ids} argument. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ + # Run example model if not already loaded + if (!exists("example_jm")) example(example_jm) + + # Obtain subject-specific predictions for all individuals + # in the estimation dataset + pt1 <- posterior_traj(example_jm, interpolate = FALSE, extrapolate = FALSE) + head(pt1) + + # Obtain subject-specific predictions only for a few selected individuals + pt2 <- posterior_traj(example_jm, ids = c(1,3,8)) + + # If we wanted to obtain subject-specific predictions in order to plot the + # longitudinal trajectories, then we might want to ensure a full trajectory + # is obtained by interpolating and extrapolating time. We can then use the + # generic plot function to plot the subject-specific predicted trajectories + # for the first three individuals. Interpolation and extrapolation is + # carried out by default. + pt3 <- posterior_traj(example_jm) + head(pt3) # predictions at additional time points compared with pt1 + plot(pt3, ids = 1:3) + + # If we wanted to extrapolate further in time, but decrease the number of + # discrete time points at which we obtain predictions for each individual, + # then we could specify a named list in the 'control' argument + pt4 <- posterior_traj(example_jm, control = list(ipoints = 10, epoints = 10, eprop = 0.5)) + + # If we have prediction data for a new individual, and we want to + # estimate the longitudinal trajectory for that individual conditional + # on this new data (perhaps extrapolating forward from our last + # longitudinal measurement) then we can do that. It requires drawing + # new individual-specific parameters, based on the full likelihood, + # so we must supply new data for both the longitudinal and event + # submodels. These are sometimes known as dynamic predictions. + ndL <- pbcLong[pbcLong$id == 8, , drop = FALSE] + ndE <- pbcSurv[pbcSurv$id == 8, , drop = FALSE] + ndL$id <- "new_subject" # new id can't match one used in training data + ndE$id <- "new_subject" + pt5 <- posterior_traj(example_jm, + newdataLong = ndL, + newdataEvent = ndE) + + # By default it is assumed that the last known survival time for + # the individual is the time of their last biomarker measurement, + # but if we know they survived to some later time then we can + # condition on that information using the last_time argument + pt6 <- posterior_traj(example_jm, + newdataLong = ndL, + newdataEvent = ndE, + last_time = "futimeYears") + + # Alternatively we may want to estimate the marginal longitudinal + # trajectory for a given set of covariates. To do this, we can pass + # the desired covariate values in a new data frame (however the only + # covariate in our fitted model was the time variable, year). To make sure + # that we marginalise over the random effects, we need to specify an ID value + # which does not correspond to any of the individuals who were used in the + # model estimation and specify the argument dynamic=FALSE. + # The marginal prediction is obtained by generating subject-specific + # predictions using a series of random draws from the random + # effects distribution, and then integrating (ie, averaging) over these. + # Our marginal prediction will therefore capture the between-individual + # variation associated with the random effects. + + nd <- data.frame(id = rep("new1", 11), year = (0:10 / 2)) + pt7 <- posterior_traj(example_jm, newdataLong = nd, dynamic = FALSE) + head(pt7) # note the greater width of the uncertainty interval compared + # with the subject-specific predictions in pt1, pt2, etc + + # Alternatively, we could have estimated the "marginal" trajectory by + # ignoring the random effects (ie, assuming the random effects were set + # to zero). This will generate a predicted longitudinal trajectory only + # based on the fixed effect component of the model. In essence, for a + # linear mixed effects model (ie, a model that uses an identity link + # function), we should obtain a similar point estimate ("yfit") to the + # estimates obtained in pt5 (since the mean of the estimated random effects + # distribution will be approximately 0). However, it is important to note that + # the uncertainty interval will be much more narrow, since it completely + # ignores the between-individual variability captured by the random effects. + # Further, if the model uses a non-identity link function, then the point + # estimate ("yfit") obtained only using the fixed effect component of the + # model will actually provide a biased estimate of the marginal prediction. + # Nonetheless, to demonstrate how we can obtain the predictions only using + # the fixed effect component of the model, we simply specify 're.form = NA'. + # (We will use the same covariate values as used in the prediction for + # example for pt5). + + pt8 <- posterior_traj(example_jm, newdataLong = nd, dynamic = FALSE, + re.form = NA) + head(pt8) # note the much narrower ci, compared with pt5 +} +} +} +\seealso{ +\code{\link{plot.predict.stanjm}}, \code{\link{posterior_predict}}, + \code{\link{posterior_survfit}} +} diff --git a/man/posterior_vs_prior.Rd b/man/posterior_vs_prior.Rd new file mode 100644 index 000000000..6e9f40c8c --- /dev/null +++ b/man/posterior_vs_prior.Rd @@ -0,0 +1,158 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_vs_prior.R +\name{posterior_vs_prior} +\alias{posterior_vs_prior} +\alias{posterior_vs_prior.stanreg} +\title{Juxtapose prior and posterior} +\usage{ +posterior_vs_prior(object, ...) + +\method{posterior_vs_prior}{stanreg}( + object, + pars = NULL, + regex_pars = NULL, + prob = 0.9, + color_by = c("parameter", "vs", "none"), + group_by_parameter = FALSE, + facet_args = list(), + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{The S3 generic uses \code{...} to pass arguments to any defined +methods. For the method for stanreg objects, \code{...} is for arguments +(other than \code{color}) passed to \code{geom_pointrange} in the \pkg{ggplot2} +package to control the appearance of the plotted intervals.} + +\item{pars}{An optional character vector specifying a subset of parameters to +display. Parameters can be specified by name or several shortcuts can be +used. Using \code{pars="beta"} will restrict the displayed parameters to +only the regression coefficients (without the intercept). \code{"alpha"} +can also be used as a shortcut for \code{"(Intercept)"}. If the model has +varying intercepts and/or slopes they can be selected using \code{pars = +"varying"}. + +In addition, for \code{stanmvreg} objects there are some additional shortcuts +available. Using \code{pars = "long"} will display the +parameter estimates for the longitudinal submodels only (excluding group-specific +pparameters, but including auxiliary parameters). +Using \code{pars = "event"} will display the +parameter estimates for the event submodel only, including any association +parameters. +Using \code{pars = "assoc"} will display only the +association parameters. +Using \code{pars = "fixef"} will display all fixed effects, but not +the random effects or the auxiliary parameters. + \code{pars} and \code{regex_pars} are set to \code{NULL} then all +fixed effect regression coefficients are selected, as well as any +auxiliary parameters and the log posterior. + +If \code{pars} is \code{NULL} all parameters are selected for a \code{stanreg} +object, while for a \code{stanmvreg} object all +fixed effect regression coefficients are selected as well as any +auxiliary parameters and the log posterior. See +\strong{Examples}.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} + +\item{prob}{A number \eqn{p \in (0,1)}{p (0 < p < 1)} indicating the desired +posterior probability mass to include in the (central posterior) interval +estimates displayed in the plot. The default is \eqn{0.9}.} + +\item{color_by}{How should the estimates be colored? Use \code{"parameter"} +to color by parameter name, \code{"vs"} to color the prior one color and +the posterior another, and \code{"none"} to use no color. Except when +\code{color_by="none"}, a variable is mapped to the color +\code{\link[ggplot2]{aes}}thetic and it is therefore also possible to +change the default colors by adding one of the various discrete color +scales available in \code{ggplot2} +(\code{\link[ggplot2:scale_manual]{scale_color_manual}}, +\code{scale_colour_brewer}, etc.). See Examples.} + +\item{group_by_parameter}{Should estimates be grouped together by parameter +(\code{TRUE}) or by posterior and prior (\code{FALSE}, the default)?} + +\item{facet_args}{A named list of arguments passed to +\code{\link[ggplot2]{facet_wrap}} (other than the \code{facets} argument), +e.g., \code{nrow} or \code{ncol} to change the layout, \code{scales} to +allow axis scales to vary across facets, etc. See Examples.} +} +\value{ +A ggplot object that can be further customized using the + \pkg{ggplot2} package. +} +\description{ +Plot medians and central intervals comparing parameter draws from the prior +and posterior distributions. If the plotted priors look different than the +priors you think you specified it is likely either because of internal +rescaling or the use of the \code{QR} argument (see the documentation for the +\code{\link[=prior_summary.stanreg]{prior_summary}} method for details on +these special cases). +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\dontrun{ +if (!exists("example_model")) example(example_model) +# display non-varying (i.e. not group-level) coefficients +posterior_vs_prior(example_model, pars = "beta") + +# show group-level (varying) parameters and group by parameter +posterior_vs_prior(example_model, pars = "varying", + group_by_parameter = TRUE, color_by = "vs") + +# group by parameter and allow axis scales to vary across facets +posterior_vs_prior(example_model, regex_pars = "period", + group_by_parameter = TRUE, color_by = "none", + facet_args = list(scales = "free")) + +# assign to object and customize with functions from ggplot2 +(gg <- posterior_vs_prior(example_model, pars = c("beta", "varying"), prob = 0.8)) + +gg + + ggplot2::geom_hline(yintercept = 0, size = 0.3, linetype = 3) + + ggplot2::coord_flip() + + ggplot2::ggtitle("Comparing the prior and posterior") + +# compare very wide and very narrow priors using roaches example +# (see help(roaches, "rstanarm") for info on the dataset) +roaches$roach100 <- roaches$roach1 / 100 +wide_prior <- normal(0, 10) +narrow_prior <- normal(0, 0.1) +fit_pois_wide_prior <- stan_glm(y ~ treatment + roach100 + senior, + offset = log(exposure2), + family = "poisson", data = roaches, + prior = wide_prior) +posterior_vs_prior(fit_pois_wide_prior, pars = "beta", prob = 0.5, + group_by_parameter = TRUE, color_by = "vs", + facet_args = list(scales = "free")) + +fit_pois_narrow_prior <- update(fit_pois_wide_prior, prior = narrow_prior) +posterior_vs_prior(fit_pois_narrow_prior, pars = "beta", prob = 0.5, + group_by_parameter = TRUE, color_by = "vs", + facet_args = list(scales = "free")) + + +# look at cutpoints for ordinal model +fit_polr <- stan_polr(tobgp ~ agegp, data = esoph, method = "probit", + prior = R2(0.2, "mean"), init_r = 0.1) +(gg_polr <- posterior_vs_prior(fit_polr, regex_pars = "\\\\|", color_by = "vs", + group_by_parameter = TRUE)) +# flip the x and y axes +gg_polr + ggplot2::coord_flip() +} +} +} +\references{ +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}) +} diff --git a/man/pp_check.stanreg.Rd b/man/pp_check.stanreg.Rd new file mode 100644 index 000000000..cfd3b9e1b --- /dev/null +++ b/man/pp_check.stanreg.Rd @@ -0,0 +1,150 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pp_check.R +\name{pp_check.stanreg} +\alias{pp_check.stanreg} +\alias{pp_check} +\title{Graphical posterior predictive checks} +\usage{ +\method{pp_check}{stanreg}(object, plotfun = "dens_overlay", nreps = NULL, seed = NULL, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{plotfun}{A character string naming the \pkg{bayesplot} +\link[bayesplot:PPC-overview]{PPC} function to use. The default is to call +\code{\link[bayesplot:PPC-distributions]{ppc_dens_overlay}}. \code{plotfun} can be specified +either as the full name of a \pkg{bayesplot} plotting function (e.g. +\code{"ppc_hist"}) or can be abbreviated to the part of the name following +the \code{"ppc_"} prefix (e.g. \code{"hist"}). To get the names of all +available PPC functions see \code{\link[bayesplot]{available_ppc}}.} + +\item{nreps}{The number of \eqn{y^{rep}}{yrep} datasets to generate from the +\link[=posterior_predict]{posterior predictive distribution} and show in +the plots. The default depends on \code{plotfun}. For functions that plot +each \code{yrep} dataset separately (e.g. \code{ppc_hist}), \code{nreps} +defaults to a small value to make the plots readable. For functions that +overlay many \code{yrep} datasets (e.g., \code{ppc_dens_overlay}) a larger +number is used by default, and for other functions (e.g. \code{ppc_stat}) +the default is to set \code{nreps} equal to the posterior sample size.} + +\item{seed}{An optional \code{\link[=set.seed]{seed}} to pass to +\code{\link{posterior_predict}}.} + +\item{...}{Additonal arguments passed to the \pkg{\link{bayesplot}} function +called. For many plotting functions \code{...} is optional, however for +functions that require a \code{group} or \code{x} argument, these arguments +should be specified in \code{...}. If specifying \code{group} and/or +\code{x}, they can be provided as either strings naming variables (in which +case they are searched for in the model frame) or as vectors containing the +actual values of the variables. See the \strong{Examples} section, below.} +} +\value{ +\code{pp_check} returns a ggplot object that can be further + customized using the \pkg{ggplot2} package. +} +\description{ +Interface to the \link[bayesplot:PPC-overview]{PPC} (posterior predictive checking) module +in the \pkg{\link{bayesplot}} package, providing various plots comparing the +observed outcome variable \eqn{y} to simulated datasets \eqn{y^{rep}}{yrep} +from the posterior predictive distribution. The \code{pp_check} method for +\link{stanreg-objects} prepares the arguments required for the specified +\pkg{bayesplot} PPC plotting function and then calls that function. It is +also straightforward to use the functions from the \pkg{bayesplot} package +directly rather than via the \code{pp_check} method. Examples of both are +given below. +} +\note{ +For binomial data, plots of \eqn{y} and \eqn{y^{rep}}{yrep} show the + proportion of 'successes' rather than the raw count. Also for binomial + models see \code{\link[bayesplot:PPC-errors]{ppc_error_binned}} for binned residual + plots. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +fit <- stan_glmer( + mpg ~ wt + am + (1|cyl), + data = mtcars, + iter = 400, # iter and chains small just to keep example quick + chains = 2, + refresh = 0 +) + +# Compare distribution of y to distributions of multiple yrep datasets +pp_check(fit) +pp_check(fit, plotfun = "boxplot", nreps = 10, notch = FALSE) +pp_check(fit, plotfun = "hist", nreps = 3) + +\donttest{ +# Same plot (up to RNG noise) using bayesplot package directly +bayesplot::ppc_hist(y = mtcars$mpg, yrep = posterior_predict(fit, draws = 3)) + +# Check histograms of test statistics by level of grouping variable 'cyl' +pp_check(fit, plotfun = "stat_grouped", stat = "median", group = "cyl") + +# Defining a custom test statistic +q25 <- function(y) quantile(y, probs = 0.25) +pp_check(fit, plotfun = "stat_grouped", stat = "q25", group = "cyl") + +# Scatterplot of two test statistics +pp_check(fit, plotfun = "stat_2d", stat = c("mean", "sd")) + +# Scatterplot of y vs. average yrep +pp_check(fit, plotfun = "scatter_avg") # y vs. average yrep +# Same plot (up to RNG noise) using bayesplot package directly +bayesplot::ppc_scatter_avg(y = mtcars$mpg, yrep = posterior_predict(fit)) + +# Scatterplots of y vs. several individual yrep datasets +pp_check(fit, plotfun = "scatter", nreps = 3) + +# Same plot (up to RNG noise) using bayesplot package directly +bayesplot::ppc_scatter(y = mtcars$mpg, yrep = posterior_predict(fit, draws = 3)) + +# yrep intervals with y points overlaid +# by default 1:length(y) used on x-axis but can also specify an x variable +pp_check(fit, plotfun = "intervals") +pp_check(fit, plotfun = "intervals", x = "wt") + ggplot2::xlab("wt") + +# Same plot (up to RNG noise) using bayesplot package directly +bayesplot::ppc_intervals(y = mtcars$mpg, yrep = posterior_predict(fit), + x = mtcars$wt) + ggplot2::xlab("wt") + +# predictive errors +pp_check(fit, plotfun = "error_hist", nreps = 6) +pp_check(fit, plotfun = "error_scatter_avg_vs_x", x = "wt") + + ggplot2::xlab("wt") + +# Example of a PPC for ordinal models (stan_polr) +fit2 <- stan_polr(tobgp ~ agegp, data = esoph, method = "probit", + prior = R2(0.2, "mean"), init_r = 0.1, + refresh = 0) +pp_check(fit2, plotfun = "bars", nreps = 500, prob = 0.5) +pp_check(fit2, plotfun = "bars_grouped", group = esoph$agegp, + nreps = 500, prob = 0.5) +} +} +} +\references{ +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. (Ch. 6) + +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}) +} +\seealso{ +\itemize{ + \item The vignettes in the \pkg{bayesplot} package for many examples. + Examples of posterior predictive checks can also be found in the + \pkg{rstanarm} vignettes and demos. + \item \code{\link[bayesplot]{PPC-overview}} (\pkg{bayesplot}) for links to + the documentation for all the available plotting functions. + \item \code{\link{posterior_predict}} for drawing from the posterior + predictive distribution. + \item \code{\link[bayesplot:bayesplot-colors]{color_scheme_set}} to change the color scheme + of the plots. +} +} diff --git a/man/pp_validate.Rd b/man/pp_validate.Rd new file mode 100644 index 000000000..5027f3f6e --- /dev/null +++ b/man/pp_validate.Rd @@ -0,0 +1,87 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pp_validate.R +\name{pp_validate} +\alias{pp_validate} +\title{Model validation via simulation} +\usage{ +pp_validate(object, nreps = 20, seed = 12345, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{nreps}{The number of replications to be performed. \code{nreps} must be +sufficiently large so that the statistics described below in Details are +meaningful. Depending on the model and the size of the data, running +\code{pp_validate} may be slow. See also the Note section below for advice +on avoiding numerical issues.} + +\item{seed}{A seed passed to Stan to use when refitting the model.} + +\item{...}{Currently ignored.} +} +\value{ +A ggplot object that can be further customized using the + \pkg{ggplot2} package. +} +\description{ +The \code{pp_validate} function is based on the methods described in +Cook, Gelman, and Rubin (2006) for validating software developed to fit +particular Bayesian models. Here we take the perspective that models +themselves are software and thus it is useful to apply this validation +approach to individual models. +} +\details{ +We repeat \code{nreps} times the process of simulating parameters and data +from the model and refitting the model to this simulated data. For each of +the \code{nreps} replications we do the following: +\enumerate{ +\item Refit the model but \emph{without} conditioning on the data (setting +\code{prior_PD=TRUE}), obtaining draws \eqn{\theta^{true}}{\theta_true} +from the \emph{prior} distribution of the model parameters. +\item Given \eqn{\theta^{true}}{\theta_true}, simulate data \eqn{y^\ast}{y*} +from the \emph{prior} predictive distribution (calling +\code{\link{posterior_predict}} on the fitted model object obtained in step +1). +\item Fit the model to the simulated outcome \eqn{y^\ast}{y*}, obtaining +parameters \eqn{\theta^{post}}{\theta_post}. +} +For any individual parameter, the quantile of the "true" parameter value with +respect to its posterior distribution \emph{should} be uniformly distributed. +The validation procedure entails looking for deviations from uniformity by +computing statistics for a test that the quantiles are uniformly distributed. +The absolute values of the computed test statistics are plotted for batches +of parameters (e.g., non-varying coefficients are grouped into a batch called +"beta", parameters that vary by group level are in batches named for the +grouping variable, etc.). See Cook, Gelman, and Rubin (2006) for more details +on the validation procedure. +} +\note{ +In order to make it through \code{nreps} replications without running + into numerical difficulties you may have to restrict the range for randomly + generating initial values for parameters when you fit the \emph{original} + model. With any of \pkg{rstanarm}'s modeling functions this can be done by + specifying the optional argument \code{init_r} as some number less than the + default of \eqn{2}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\dontrun{ +if (!exists("example_model")) example(example_model) +try(pp_validate(example_model)) # fails with default seed / priors +} +} +} +\references{ +Cook, S., Gelman, A., and Rubin, D. +(2006). Validation of software for Bayesian models using posterior quantiles. +\emph{Journal of Computational and Graphical Statistics}. 15(3), 675--692. +} +\seealso{ +\code{\link{pp_check}} for graphical posterior predictive checks and +\code{\link{posterior_predict}} to draw from the posterior predictive +distribution. + +\code{\link[bayesplot:bayesplot-colors]{color_scheme_set}} to change the color scheme of the +plot. +} diff --git a/man/predict.stanreg.Rd b/man/predict.stanreg.Rd new file mode 100644 index 000000000..b472b1902 --- /dev/null +++ b/man/predict.stanreg.Rd @@ -0,0 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/predict.R +\name{predict.stanreg} +\alias{predict.stanreg} +\title{Predict method for stanreg objects} +\usage{ +\method{predict}{stanreg}( + object, + ..., + newdata = NULL, + type = c("link", "response"), + se.fit = FALSE +) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{Ignored.} + +\item{newdata}{Optionally, a data frame in which to look for variables with +which to predict. If omitted, the model matrix is used.} + +\item{type}{The type of prediction. The default \code{'link'} is on the scale +of the linear predictors; the alternative \code{'response'} is on the scale +of the response variable.} + +\item{se.fit}{A logical scalar indicating if standard errors should be +returned. The default is \code{FALSE}.} +} +\value{ +A vector if \code{se.fit} is \code{FALSE} and a list if \code{se.fit} + is \code{TRUE}. +} +\description{ +This method is primarily intended to be used only for models fit using +optimization. For models fit using MCMC or one of the variational +approximations, see \code{\link{posterior_predict}}. +} +\seealso{ +\code{\link{posterior_predict}} +} diff --git a/man/predictive_error.stanreg.Rd b/man/predictive_error.stanreg.Rd new file mode 100644 index 000000000..96c126d61 --- /dev/null +++ b/man/predictive_error.stanreg.Rd @@ -0,0 +1,95 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/predictive_error.R +\name{predictive_error.stanreg} +\alias{predictive_error.stanreg} +\alias{predictive_error} +\alias{predictive_error.matrix} +\alias{predictive_error.ppd} +\title{In-sample or out-of-sample predictive errors} +\usage{ +\method{predictive_error}{stanreg}( + object, + newdata = NULL, + draws = NULL, + re.form = NULL, + seed = NULL, + offset = NULL, + ... +) + +\method{predictive_error}{matrix}(object, y, ...) + +\method{predictive_error}{ppd}(object, y, ...) +} +\arguments{ +\item{object}{Either a fitted model object returned by one of the +\pkg{rstanarm} modeling functions (a \link[=stanreg-objects]{stanreg +object}) or, for the matrix method, a matrix of draws from the +posterior predictive distribution returned by +\code{\link{posterior_predict}}.} + +\item{newdata, draws, seed, offset, re.form}{Optional arguments passed to +\code{\link{posterior_predict}}. For binomial models, please see the +\strong{Note} section below if \code{newdata} will be specified.} + +\item{...}{Currently ignored.} + +\item{y}{For the matrix method only, a vector of \eqn{y} values the +same length as the number of columns in the matrix used as \code{object}. +The method for stanreg objects takes \code{y} directly from the fitted +model object.} +} +\value{ +A \code{draws} by \code{nrow(newdata)} matrix. If \code{newdata} is + not specified then it will be \code{draws} by \code{nobs(object)}. +} +\description{ +This is a convenience function for computing \eqn{y - y^{rep}}{y - yrep} +(in-sample, for observed \eqn{y}) or \eqn{y - \tilde{y}}{y - ytilde} +(out-of-sample, for new or held-out \eqn{y}). The method for stanreg objects +calls \code{\link{posterior_predict}} internally, whereas the method for +matrices accepts the matrix returned by \code{posterior_predict} as input and +can be used to avoid multiple calls to \code{posterior_predict}. +} +\note{ +The \strong{Note} section in \code{\link{posterior_predict}} about + \code{newdata} for binomial models also applies for + \code{predictive_error}, with one important difference. For + \code{posterior_predict} if the left-hand side of the model formula is + \code{cbind(successes, failures)} then the particular values of + \code{successes} and \code{failures} in \code{newdata} don't matter, only + that they add to the desired number of trials. \strong{This is not the case + for} \code{predictive_error}. For \code{predictive_error} the particular + value of \code{successes} matters because it is used as \eqn{y} when + computing the error. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +err1 <- predictive_error(example_model, draws = 50) +hist(err1) + +# Using newdata with a binomial model +formula(example_model) +nd <- data.frame( + size = c(10, 20), + incidence = c(5, 10), + period = factor(c(1,2)), + herd = c(1, 15) +) +err2 <- predictive_error(example_model, newdata = nd, draws = 10, seed = 1234) + +# stanreg vs matrix methods +fit <- stan_glm(mpg ~ wt, data = mtcars, iter = 300) +preds <- posterior_predict(fit, seed = 123) +all.equal( + predictive_error(fit, seed = 123), + predictive_error(preds, y = fit$y) +) +} +} +\seealso{ +\code{\link[=posterior_predict.stanreg]{posterior_predict}} to draw + from the posterior predictive distribution without computing predictive + errors. +} diff --git a/man/predictive_interval.stanreg.Rd b/man/predictive_interval.stanreg.Rd new file mode 100644 index 000000000..2f4619684 --- /dev/null +++ b/man/predictive_interval.stanreg.Rd @@ -0,0 +1,80 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/predictive_interval.R +\name{predictive_interval.stanreg} +\alias{predictive_interval.stanreg} +\alias{predictive_interval} +\alias{predictive_interval.matrix} +\alias{predictive_interval.ppd} +\title{Predictive intervals} +\usage{ +\method{predictive_interval}{stanreg}( + object, + prob = 0.9, + newdata = NULL, + draws = NULL, + re.form = NULL, + fun = NULL, + seed = NULL, + offset = NULL, + ... +) + +\method{predictive_interval}{matrix}(object, prob = 0.9, ...) + +\method{predictive_interval}{ppd}(object, prob = 0.9, ...) +} +\arguments{ +\item{object}{Either a fitted model object returned by one of the +\pkg{rstanarm} modeling functions (a \link[=stanreg-objects]{stanreg +object}) or, for the matrix method, a matrix of draws from the +posterior predictive distribution returned by +\code{\link{posterior_predict}}.} + +\item{prob}{A number \eqn{p \in (0,1)}{p (0 < p < 1)} indicating the desired +probability mass to include in the intervals. The default is to report +\eqn{90}\% intervals (\code{prob=0.9}) rather than the traditionally used +\eqn{95}\% (see Details).} + +\item{newdata, draws, fun, offset, re.form, seed}{Passed to +\code{\link[=posterior_predict]{posterior_predict}}.} + +\item{...}{Currently ignored.} +} +\value{ +A matrix with two columns and as many rows as are in \code{newdata}. + If \code{newdata} is not provided then the matrix will have as many rows as + the data used to fit the model. For a given value of \code{prob}, \eqn{p}, + the columns correspond to the lower and upper \eqn{100p}\% central interval + limits and have the names \eqn{100\alpha/2}\% and \eqn{100(1 - + \alpha/2)}\%, where \eqn{\alpha = 1-p}. For example, if \code{prob=0.9} is + specified (a \eqn{90}\% interval), then the column names will be + \code{"5\%"} and \code{"95\%"}, respectively. +} +\description{ +For models fit using MCMC (\code{algorithm="sampling"}) or one of the +variational approximations (\code{"meanfield"} or \code{"fullrank"}), the +\code{predictive_interval} function computes Bayesian predictive intervals. +The method for stanreg objects calls \code{\link{posterior_predict}} +internally, whereas the method for matrices accepts the matrix returned by +\code{posterior_predict} as input and can be used to avoid multiple calls to +\code{posterior_predict}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +fit <- stan_glm(mpg ~ wt, data = mtcars, iter = 300) +predictive_interval(fit) +predictive_interval(fit, newdata = data.frame(wt = range(mtcars$wt)), + prob = 0.5) + +# stanreg vs matrix methods +preds <- posterior_predict(fit, seed = 123) +all.equal( + predictive_interval(fit, seed = 123), + predictive_interval(preds) +) +} +} +\seealso{ +\code{\link{predictive_error}}, \code{\link{posterior_predict}}, + \code{\link{posterior_interval}} +} diff --git a/man/print.stanreg.Rd b/man/print.stanreg.Rd new file mode 100644 index 000000000..9579200ad --- /dev/null +++ b/man/print.stanreg.Rd @@ -0,0 +1,68 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/print-and-summary.R +\name{print.stanreg} +\alias{print.stanreg} +\alias{print.stanmvreg} +\title{Print method for stanreg objects} +\usage{ +\method{print}{stanreg}(x, digits = 1, detail = TRUE, ...) + +\method{print}{stanmvreg}(x, digits = 3, ...) +} +\arguments{ +\item{x}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{digits}{Number of digits to use for formatting numbers.} + +\item{detail}{Logical, defaulting to \code{TRUE}. If \code{FALSE} a more +minimal summary is printed consisting only of the parameter estimates.} + +\item{...}{Ignored.} +} +\value{ +Returns \code{x}, invisibly. +} +\description{ +The \code{print} method for stanreg objects displays a compact summary of the +fitted model. See the \strong{Details} section below for descriptions of the +different components of the printed output. For additional summary statistics +and diagnostics use the \code{\link[=summary.stanreg]{summary}} method. +} +\details{ +\subsection{Point estimates}{ +Regardless of the estimation algorithm, point estimates are medians computed +from simulations. For models fit using MCMC (\code{"sampling"}) the posterior +sample is used. For optimization (\code{"optimizing"}), the simulations are +generated from the asymptotic Gaussian sampling distribution of the +parameters. For the \code{"meanfield"} and \code{"fullrank"} variational +approximations, draws from the variational approximation to the posterior are +used. In all cases, the point estimates reported are the same as the values +returned by \code{\link[=coef.stanreg]{coef}}. +} +\subsection{Uncertainty estimates (MAD_SD)}{ +The standard deviations reported (labeled \code{MAD_SD} in the print output) +are computed from the same set of draws described above and are proportional +to the median absolute deviation (\code{\link[stats]{mad}}) from the median. +Compared to the raw posterior standard deviation, the MAD_SD will be +more robust for long-tailed distributions. These are the same as the values +returned by \code{\link[=se.stanreg]{se}}. +} +\subsection{Additional output}{ +\itemize{ +\item For GLMs with group-specific terms (see \code{\link{stan_glmer}}) the printed +output also shows point estimates of the standard deviations of the group +effects (and correlations if there are both intercept and slopes that vary by +group). + +\item For analysis of variance models (see \code{\link{stan_aov}}) models, an +ANOVA-like table is also displayed. + +\item For joint longitudinal and time-to-event (see \code{\link{stan_jm}}) models +the estimates are presented separately for each of the distinct submodels. +} +} +} +\seealso{ +\code{\link{summary.stanreg}}, \code{\link{stanreg-methods}} +} diff --git a/man/print.survfit.stanjm.Rd b/man/print.survfit.stanjm.Rd new file mode 100644 index 000000000..e4784b71d --- /dev/null +++ b/man/print.survfit.stanjm.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/posterior_survfit.R +\name{print.survfit.stanjm} +\alias{print.survfit.stanjm} +\title{Generic print method for \code{survfit.stanjm} objects} +\usage{ +\method{print}{survfit.stanjm}(x, digits = 4, ...) +} +\arguments{ +\item{x}{An object of class \code{survfit.stanjm}, returned by a call to +\code{\link{posterior_survfit}}.} + +\item{digits}{Number of digits to use for formatting the time variable and +the survival probabilities.} + +\item{...}{Ignored.} +} +\description{ +Generic print method for \code{survfit.stanjm} objects +} +\keyword{internal} diff --git a/man/prior_summary.stanreg.Rd b/man/prior_summary.stanreg.Rd new file mode 100644 index 000000000..345b876aa --- /dev/null +++ b/man/prior_summary.stanreg.Rd @@ -0,0 +1,122 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/prior_summary.R +\name{prior_summary.stanreg} +\alias{prior_summary.stanreg} +\alias{prior_summary} +\title{Summarize the priors used for an rstanarm model} +\usage{ +\method{prior_summary}{stanreg}(object, digits = 2, ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{digits}{Number of digits to use for rounding.} + +\item{...}{Currently ignored by the method for stanreg objects.} +} +\value{ +A list of class "prior_summary.stanreg", which has its own print + method. +} +\description{ +The \code{prior_summary} method provides a summary of the prior distributions +used for the parameters in a given model. In some cases the user-specified +prior does not correspond exactly to the prior used internally by +\pkg{rstanarm} (see the sections below). Especially in these cases, but also +in general, it can be much more useful to visualize the priors. Visualizing +the priors can be done using the \code{\link{posterior_vs_prior}} function, +or alternatively by fitting the model with the \code{prior_PD} argument set +to \code{TRUE} (to draw from the prior predictive distribution instead of +conditioning on the outcome) and then plotting the parameters. +} +\section{Intercept (after predictors centered)}{ + + For \pkg{rstanarm} modeling functions that accept a \code{prior_intercept} + argument, the specified prior for the intercept term applies to the + intercept after \pkg{rstanarm} internally centers the predictors so they + each have mean zero. The estimate of the intercept returned to the user + correspond to the intercept with the predictors as specified by the user + (unmodified by \pkg{rstanarm}), but when \emph{specifying} the prior the + intercept can be thought of as the expected outcome when the predictors are + set to their means. The only exception to this is for models fit with the + \code{sparse} argument set to \code{TRUE} (which is only possible with a + subset of the modeling functions and never the default). +} + +\section{Adjusted scales}{ + For some models you may see "\code{adjusted scale}" + in the printed output and adjusted scales included in the object returned + by \code{prior_summary}. These adjusted scale values are the prior scales + actually used by \pkg{rstanarm} and are computed by adjusting the prior + scales specified by the user to account for the scales of the predictors + (as described in the documentation for the \code{\link[=priors]{autoscale}} + argument). To disable internal prior scale adjustments set the + \code{autoscale} argument to \code{FALSE} when setting a prior using one of + the distributions that accepts an \code{autoscale} argument. For example, + \code{normal(0, 5, autoscale=FALSE)} instead of just \code{normal(0, 5)}. +} + +\section{Coefficients in Q-space}{ + + For the models fit with an \pkg{rstanarm} modeling function that supports + the \code{QR} argument (see e.g, \code{\link{stan_glm}}), if \code{QR} is + set to \code{TRUE} then the prior distributions for the regression + coefficients specified using the \code{prior} argument are not relative to + the original predictor variables \eqn{X} but rather to the variables in the + matrix \eqn{Q} obtained from the \eqn{QR} decomposition of \eqn{X}. + + In particular, if \code{prior = normal(location,scale)}, then this prior on + the coefficients in \eqn{Q}-space can be easily translated into a joint + multivariate normal (MVN) prior on the coefficients on the original + predictors in \eqn{X}. Letting \eqn{\theta} denote the coefficients on + \eqn{Q} and \eqn{\beta} the coefficients on \eqn{X} then if \eqn{\theta + \sim N(\mu, \sigma)}{\theta ~ N(\mu, \sigma)} the corresponding prior on + \eqn{\beta} is \eqn{\beta \sim MVN(R\mu, R'R\sigma^2)}{\beta ~ MVN(R\mu, + R'R\sigma)}, where \eqn{\mu} and \eqn{\sigma} are vectors of the + appropriate length. Technically, \pkg{rstanarm} uses a scaled \eqn{QR} + decomposition to ensure that the columns of the predictor matrix used to + fit the model all have unit scale, when the \code{autoscale} argument + to the function passed to the \code{prior} argument is \code{TRUE} (the + default), in which case the matrices actually used are + \eqn{Q^\ast = Q \sqrt{n-1}}{Q* = Q (n-1)^0.5} and \eqn{R^\ast = + \frac{1}{\sqrt{n-1}} R}{R* = (n-1)^(-0.5) R}. If \code{autoscale = FALSE} + we instead scale such that the lower-right element of \eqn{R^\ast}{R*} is + \eqn{1}, which is useful if you want to specify a prior on the coefficient + of the last predictor in its original units (see the documentation for the + \code{\link[=stan_glm]{QR}} argument). + + If you are interested in the prior on \eqn{\beta} implied by the prior on + \eqn{\theta}, we strongly recommend visualizing it as described above in + the \strong{Description} section, which is simpler than working it out + analytically. +} + +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +prior_summary(example_model) + +priors <- prior_summary(example_model) +names(priors) +priors$prior$scale +priors$prior$adjusted_scale + +# for a glm with adjusted scales (see Details, above), compare +# the default (rstanarm adjusting the scales) to setting +# autoscale=FALSE for prior on coefficients +fit <- stan_glm(mpg ~ wt + am, data = mtcars, + prior = normal(0, c(2.5, 4)), + prior_intercept = normal(0, 5), + iter = 10, chains = 1) # only for demonstration +prior_summary(fit) + +fit2 <- update(fit, prior = normal(0, c(2.5, 4), autoscale=FALSE), + prior_intercept = normal(0, 5, autoscale=FALSE)) +prior_summary(fit2) +} +} +\seealso{ +The \link[=priors]{priors help page} and the \emph{Prior + Distributions} vignette. +} diff --git a/man/priors.Rd b/man/priors.Rd new file mode 100644 index 000000000..f4fcc73d6 --- /dev/null +++ b/man/priors.Rd @@ -0,0 +1,506 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/priors.R +\name{priors} +\alias{priors} +\alias{normal} +\alias{student_t} +\alias{cauchy} +\alias{hs} +\alias{hs_plus} +\alias{laplace} +\alias{lasso} +\alias{product_normal} +\alias{exponential} +\alias{decov} +\alias{lkj} +\alias{dirichlet} +\alias{R2} +\alias{default_prior_intercept} +\alias{default_prior_coef} +\title{Prior distributions and options} +\usage{ +normal(location = 0, scale = NULL, autoscale = FALSE) + +student_t(df = 1, location = 0, scale = NULL, autoscale = FALSE) + +cauchy(location = 0, scale = NULL, autoscale = FALSE) + +hs(df = 1, global_df = 1, global_scale = 0.01, slab_df = 4, slab_scale = 2.5) + +hs_plus( + df1 = 1, + df2 = 1, + global_df = 1, + global_scale = 0.01, + slab_df = 4, + slab_scale = 2.5 +) + +laplace(location = 0, scale = NULL, autoscale = FALSE) + +lasso(df = 1, location = 0, scale = NULL, autoscale = FALSE) + +product_normal(df = 2, location = 0, scale = 1) + +exponential(rate = 1, autoscale = FALSE) + +decov(regularization = 1, concentration = 1, shape = 1, scale = 1) + +lkj(regularization = 1, scale = 10, df = 1, autoscale = TRUE) + +dirichlet(concentration = 1) + +R2(location = NULL, what = c("mode", "mean", "median", "log")) + +default_prior_intercept(family) + +default_prior_coef(family) +} +\arguments{ +\item{location}{Prior location. In most cases, this is the prior mean, but +for \code{cauchy} (which is equivalent to \code{student_t} with +\code{df=1}), the mean does not exist and \code{location} is the prior +median. The default value is \eqn{0}, except for \code{R2} which has no +default value for \code{location}. For \code{R2}, \code{location} pertains +to the prior location of the \eqn{R^2} under a Beta distribution, but the +interpretation of the \code{location} parameter depends on the specified +value of the \code{what} argument (see the \emph{R2 family} section in +\strong{Details}).} + +\item{scale}{Prior scale. The default depends on the family (see +\strong{Details}).} + +\item{autoscale}{If \code{TRUE} then the scales of the priors on the +intercept and regression coefficients may be additionally modified +internally by \pkg{rstanarm} in the following cases. First, for Gaussian +models only, the prior scales for the intercept, coefficients, and the +auxiliary parameter \code{sigma} (error standard deviation) are multiplied +by \code{sd(y)}. Additionally --- not only for Gaussian models --- if the +\code{QR} argument to the model fitting function (e.g. \code{stan_glm}) is +\code{FALSE} then we also divide the prior scale(s) by \code{sd(x)}. +Prior autoscaling is also discussed in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}} + +\item{df, df1, df2}{Prior degrees of freedom. The default is \eqn{1} for +\code{student_t}, in which case it is equivalent to \code{cauchy}. For the +hierarchical shrinkage priors (\code{hs} and \code{hs_plus}) the degrees of +freedom parameter(s) default to \eqn{1}. For the \code{product_normal} +prior, the degrees of freedom parameter must be an integer (vector) that is +at least \eqn{2} (the default).} + +\item{global_df, global_scale, slab_df, slab_scale}{Optional arguments for the +hierarchical shrinkage priors. See the \emph{Hierarchical shrinkage family} +section below.} + +\item{rate}{Prior rate for the exponential distribution. Defaults to +\code{1}. For the exponential distribution, the rate parameter is the +\emph{reciprocal} of the mean.} + +\item{regularization}{Exponent for an LKJ prior on the correlation matrix in +the \code{decov} or \code{lkj} prior. The default is \eqn{1}, implying a +joint uniform prior.} + +\item{concentration}{Concentration parameter for a symmetric Dirichlet +distribution. The default is \eqn{1}, implying a joint uniform prior.} + +\item{shape}{Shape parameter for a gamma prior on the scale parameter in the +\code{decov} prior. If \code{shape} and \code{scale} are both \eqn{1} (the +default) then the gamma prior simplifies to the unit-exponential +distribution.} + +\item{what}{A character string among \code{'mode'} (the default), +\code{'mean'}, \code{'median'}, or \code{'log'} indicating how the +\code{location} parameter is interpreted in the \code{LKJ} case. If +\code{'log'}, then \code{location} is interpreted as the expected +logarithm of the \eqn{R^2} under a Beta distribution. Otherwise, +\code{location} is interpreted as the \code{what} of the \eqn{R^2} +under a Beta distribution. If the number of predictors is less than +or equal to two, the mode of this Beta distribution does not exist +and an error will prompt the user to specify another choice for +\code{what}.} + +\item{family}{Not currently used.} +} +\value{ +A named list to be used internally by the \pkg{rstanarm} model + fitting functions. +} +\description{ +The functions described on this page are used to specify the + prior-related arguments of the various modeling functions in the + \pkg{rstanarm} package (to view the priors used for an existing model see + \code{\link{prior_summary}}). + + The default priors used in the various \pkg{rstanarm} modeling functions + are intended to be \emph{weakly informative} in that they provide moderate + regularization and help stabilize computation. For many applications the + defaults will perform well, but prudent use of more informative priors is + encouraged. Uniform prior distributions are possible (e.g. by setting + \code{\link{stan_glm}}'s \code{prior} argument to \code{NULL}) but, unless + the data is very strong, they are not recommended and are \emph{not} + non-informative, giving the same probability mass to implausible values as + plausible ones. + + More information on priors is available in the vignette + \href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior + Distributions for rstanarm Models}} as well as the vignettes for the + various modeling functions. For details on the + priors used for multilevel models in particular see the vignette + \href{https://mc-stan.org/rstanarm/articles/glmer.html}{\emph{Estimating + Generalized (Non-)Linear Models with Group-Specific Terms with rstanarm}} + and also the \strong{Covariance matrices} section lower down on this page. +} +\details{ +The details depend on the family of the prior being used: +\subsection{Student t family}{ + Family members: + \itemize{ + \item \code{normal(location, scale)} + \item \code{student_t(df, location, scale)} + \item \code{cauchy(location, scale)} + } + Each of these functions also takes an argument \code{autoscale}. + + For the prior distribution for the intercept, \code{location}, + \code{scale}, and \code{df} should be scalars. For the prior for the other + coefficients they can either be vectors of length equal to the number of + coefficients (not including the intercept), or they can be scalars, in + which case they will be recycled to the appropriate length. As the + degrees of freedom approaches infinity, the Student t distribution + approaches the normal distribution and if the degrees of freedom are one, + then the Student t distribution is the Cauchy distribution. + + If \code{scale} is not specified it will default to \eqn{2.5}, unless the + probit link function is used, in which case these defaults are scaled by a + factor of \code{dnorm(0)/dlogis(0)}, which is roughly \eqn{1.6}. + + If the \code{autoscale} argument is \code{TRUE}, then the + scales will be further adjusted as described above in the documentation of + the \code{autoscale} argument in the \strong{Arguments} section. +} +\subsection{Hierarchical shrinkage family}{ + Family members: + \itemize{ + \item \code{hs(df, global_df, global_scale, slab_df, slab_scale)} + \item \code{hs_plus(df1, df2, global_df, global_scale, slab_df, slab_scale)} + } + + The hierarchical shrinkage priors are normal with a mean of zero and a + standard deviation that is also a random variable. The traditional + hierarchical shrinkage prior utilizes a standard deviation that is + distributed half Cauchy with a median of zero and a scale parameter that is + also half Cauchy. This is called the "horseshoe prior". The hierarchical + shrinkage (\code{hs}) prior in the \pkg{rstanarm} package instead utilizes + a regularized horseshoe prior, as described by Piironen and Vehtari (2017), + which recommends setting the \code{global_scale} argument equal to the ratio + of the expected number of non-zero coefficients to the expected number of + zero coefficients, divided by the square root of the number of observations. + + The hierarhical shrinkpage plus (\code{hs_plus}) prior is similar except + that the standard deviation that is distributed as the product of two + independent half Cauchy parameters that are each scaled in a similar way + to the \code{hs} prior. + + The hierarchical shrinkage priors have very tall modes and very fat tails. + Consequently, they tend to produce posterior distributions that are very + concentrated near zero, unless the predictor has a strong influence on the + outcome, in which case the prior has little influence. Hierarchical + shrinkage priors often require you to increase the + \code{\link{adapt_delta}} tuning parameter in order to diminish the number + of divergent transitions. For more details on tuning parameters and + divergent transitions see the Troubleshooting section of the \emph{How to + Use the rstanarm Package} vignette. +} +\subsection{Laplace family}{ + Family members: + \itemize{ + \item \code{laplace(location, scale)} + \item \code{lasso(df, location, scale)} + } + Each of these functions also takes an argument \code{autoscale}. + + The Laplace distribution is also known as the double-exponential + distribution. It is a symmetric distribution with a sharp peak at its mean + / median / mode and fairly long tails. This distribution can be motivated + as a scale mixture of normal distributions and the remarks above about the + normal distribution apply here as well. + + The lasso approach to supervised learning can be expressed as finding the + posterior mode when the likelihood is Gaussian and the priors on the + coefficients have independent Laplace distributions. It is commonplace in + supervised learning to choose the tuning parameter by cross-validation, + whereas a more Bayesian approach would be to place a prior on \dQuote{it}, + or rather its reciprocal in our case (i.e. \emph{smaller} values correspond + to more shrinkage toward the prior location vector). We use a chi-square + prior with degrees of freedom equal to that specified in the call to + \code{lasso} or, by default, 1. The expectation of a chi-square random + variable is equal to this degrees of freedom and the mode is equal to the + degrees of freedom minus 2, if this difference is positive. + + It is also common in supervised learning to standardize the predictors + before training the model. We do not recommend doing so. Instead, it is + better to specify \code{autoscale = TRUE}, which + will adjust the scales of the priors according to the dispersion in the + variables. See the documentation of the \code{autoscale} argument above + and also the \code{\link{prior_summary}} page for more information. +} +\subsection{Product-normal family}{ + Family members: + \itemize{ + \item \code{product_normal(df, location, scale)} + } + The product-normal distribution is the product of at least two independent + normal variates each with mean zero, shifted by the \code{location} + parameter. It can be shown that the density of a product-normal variate is + symmetric and infinite at \code{location}, so this prior resembles a + \dQuote{spike-and-slab} prior for sufficiently large values of the + \code{scale} parameter. For better or for worse, this prior may be + appropriate when it is strongly believed (by someone) that a regression + coefficient \dQuote{is} equal to the \code{location}, parameter even though + no true Bayesian would specify such a prior. + + Each element of \code{df} must be an integer of at least \eqn{2} because + these \dQuote{degrees of freedom} are interpreted as the number of normal + variates being multiplied and then shifted by \code{location} to yield the + regression coefficient. Higher degrees of freedom produce a sharper + spike at \code{location}. + + Each element of \code{scale} must be a non-negative real number that is + interpreted as the standard deviation of the normal variates being + multiplied and then shifted by \code{location} to yield the regression + coefficient. In other words, the elements of \code{scale} may differ, but + the k-th standard deviation is presumed to hold for all the normal deviates + that are multiplied together and shifted by the k-th element of + \code{location} to yield the k-th regression coefficient. The elements of + \code{scale} are not the prior standard deviations of the regression + coefficients. The prior variance of the regression coefficients is equal to + the scale raised to the power of \eqn{2} times the corresponding element of + \code{df}. Thus, larger values of \code{scale} put more prior volume on + values of the regression coefficient that are far from zero. +} +\subsection{Dirichlet family}{ + Family members: + \itemize{ + \item \code{dirichlet(concentration)} + } + + The Dirichlet distribution is a multivariate generalization of the beta + distribution. It is perhaps the easiest prior distribution to specify + because the concentration parameters can be interpreted as prior counts + (although they need not be integers) of a multinomial random variable. + + The Dirichlet distribution is used in \code{\link{stan_polr}} for an + implicit prior on the cutpoints in an ordinal regression model. More + specifically, the Dirichlet prior pertains to the prior probability of + observing each category of the ordinal outcome when the predictors are at + their sample means. Given these prior probabilities, it is straightforward + to add them to form cumulative probabilities and then use an inverse CDF + transformation of the cumulative probabilities to define the cutpoints. + + If a scalar is passed to the \code{concentration} argument of the + \code{dirichlet} function, then it is replicated to the appropriate length + and the Dirichlet distribution is symmetric. If \code{concentration} is a + vector and all elements are \eqn{1}, then the Dirichlet distribution is + jointly uniform. If all concentration parameters are equal but greater than + \eqn{1} then the prior mode is that the categories are equiprobable, and + the larger the value of the identical concentration parameters, the more + sharply peaked the distribution is at the mode. The elements in + \code{concentration} can also be given different values to represent that + not all outcome categories are a priori equiprobable. +} +\subsection{Covariance matrices}{ + Family members: + \itemize{ + \item \code{decov(regularization, concentration, shape, scale)} + \item \code{lkj(regularization, scale, df)} + } + (Also see vignette for \code{stan_glmer}, + \href{https://mc-stan.org/rstanarm/articles/glmer.html}{\emph{Estimating + Generalized (Non-)Linear Models with Group-Specific Terms with rstanarm}}) + + Covariance matrices are decomposed into correlation matrices and + variances. The variances are in turn decomposed into the product of a + simplex vector and the trace of the matrix. Finally, the trace is the + product of the order of the matrix and the square of a scale parameter. + This prior on a covariance matrix is represented by the \code{decov} + function. + + The prior for a correlation matrix is called LKJ whose density is + proportional to the determinant of the correlation matrix raised to the + power of a positive regularization parameter minus one. If + \code{regularization = 1} (the default), then this prior is jointly + uniform over all correlation matrices of that size. If + \code{regularization > 1}, then the identity matrix is the mode and in the + unlikely case that \code{regularization < 1}, the identity matrix is the + trough. + + The trace of a covariance matrix is equal to the sum of the variances. We + set the trace equal to the product of the order of the covariance matrix + and the \emph{square} of a positive scale parameter. The particular + variances are set equal to the product of a simplex vector --- which is + non-negative and sums to \eqn{1} --- and the scalar trace. In other words, + each element of the simplex vector represents the proportion of the trace + attributable to the corresponding variable. + + A symmetric Dirichlet prior is used for the simplex vector, which has a + single (positive) \code{concentration} parameter, which defaults to + \eqn{1} and implies that the prior is jointly uniform over the space of + simplex vectors of that size. If \code{concentration > 1}, then the prior + mode corresponds to all variables having the same (proportion of total) + variance, which can be used to ensure the the posterior variances are not + zero. As the \code{concentration} parameter approaches infinity, this + mode becomes more pronounced. In the unlikely case that + \code{concentration < 1}, the variances are more polarized. + + If all the variables were multiplied by a number, the trace of their + covariance matrix would increase by that number squared. Thus, it is + reasonable to use a scale-invariant prior distribution for the positive + scale parameter, and in this case we utilize a Gamma distribution, whose + \code{shape} and \code{scale} are both \eqn{1} by default, implying a + unit-exponential distribution. Set the \code{shape} hyperparameter to some + value greater than \eqn{1} to ensure that the posterior trace is not zero. + + If \code{regularization}, \code{concentration}, \code{shape} and / or + \code{scale} are positive scalars, then they are recycled to the + appropriate length. Otherwise, each can be a positive vector of the + appropriate length, but the appropriate length depends on the number of + covariance matrices in the model and their sizes. A one-by-one covariance + matrix is just a variance and thus does not have \code{regularization} or + \code{concentration} parameters, but does have \code{shape} and + \code{scale} parameters for the prior standard deviation of that + variable. + + Note that for \code{\link{stan_mvmer}} and \code{\link{stan_jm}} models an + additional prior distribution is provided through the \code{lkj} function. + This prior is in fact currently used as the default for those modelling + functions (although \code{decov} is still available as an option if the user + wishes to specify it through the \code{prior_covariance} argument). The + \code{lkj} prior uses the same decomposition of the covariance matrices + into correlation matrices and variances, however, the variances are not + further decomposed into a simplex vector and the trace; instead the + standard deviations (square root of the variances) for each of the group + specific parameters are given a half Student t distribution with the + scale and df parameters specified through the \code{scale} and \code{df} + arguments to the \code{lkj} function. The scale parameter default is 10 + which is then autoscaled, whilst the df parameter default is 1 + (therefore equivalent to a half Cauchy prior distribution for the + standard deviation of each group specific parameter). This prior generally + leads to similar results as the \code{decov} prior, but it is also likely + to be **less** diffuse compared with the \code{decov} prior; therefore it + sometimes seems to lead to faster estimation times, hence why it has + been chosen as the default prior for \code{\link{stan_mvmer}} and + \code{\link{stan_jm}} where estimation times can be long. +} +\subsection{R2 family}{ + Family members: + \itemize{ + \item \code{R2(location, what)} + } + + The \code{\link{stan_lm}}, \code{\link{stan_aov}}, and + \code{\link{stan_polr}} functions allow the user to utilize a function + called \code{R2} to convey prior information about all the parameters. + This prior hinges on prior beliefs about the location of \eqn{R^2}, the + proportion of variance in the outcome attributable to the predictors, + which has a \code{\link[stats]{Beta}} prior with first shape + hyperparameter equal to half the number of predictors and second shape + hyperparameter free. By specifying \code{what} to be the prior mode (the + default), mean, median, or expected log of \eqn{R^2}, the second shape + parameter for this Beta distribution is determined internally. If + \code{what = 'log'}, location should be a negative scalar; otherwise it + should be a scalar on the \eqn{(0,1)} interval. + + For example, if \eqn{R^2 = 0.5}, then the mode, mean, and median of + the \code{\link[stats]{Beta}} distribution are all the same and thus the + second shape parameter is also equal to half the number of predictors. + The second shape parameter of the \code{\link[stats]{Beta}} distribution + is actually the same as the shape parameter in the LKJ prior for a + correlation matrix described in the previous subsection. Thus, the smaller + is \eqn{R^2}, the larger is the shape parameter, the smaller are the + prior correlations among the outcome and predictor variables, and the more + concentrated near zero is the prior density for the regression + coefficients. Hence, the prior on the coefficients is regularizing and + should yield a posterior distribution with good out-of-sample predictions + \emph{if} the prior location of \eqn{R^2} is specified in a reasonable + fashion. +} +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +fmla <- mpg ~ wt + qsec + drat + am + +# Draw from prior predictive distribution (by setting prior_PD = TRUE) +prior_pred_fit <- stan_glm(fmla, data = mtcars, prior_PD = TRUE, + chains = 1, seed = 12345, iter = 250, # for speed only + prior = student_t(df = 4, 0, 2.5), + prior_intercept = cauchy(0,10), + prior_aux = exponential(1/2)) +plot(prior_pred_fit, "hist") + +\donttest{ +# Can assign priors to names +N05 <- normal(0, 5) +fit <- stan_glm(fmla, data = mtcars, prior = N05, prior_intercept = N05) +} + +# Visually compare normal, student_t, cauchy, laplace, and product_normal +compare_priors <- function(scale = 1, df_t = 2, xlim = c(-10, 10)) { + dt_loc_scale <- function(x, df, location, scale) { + 1/scale * dt((x - location)/scale, df) + } + dlaplace <- function(x, location, scale) { + 0.5 / scale * exp(-abs(x - location) / scale) + } + dproduct_normal <- function(x, scale) { + besselK(abs(x) / scale ^ 2, nu = 0) / (scale ^ 2 * pi) + } + stat_dist <- function(dist, ...) { + ggplot2::stat_function(ggplot2::aes_(color = dist), ...) + } + ggplot2::ggplot(data.frame(x = xlim), ggplot2::aes(x)) + + stat_dist("normal", size = .75, fun = dnorm, + args = list(mean = 0, sd = scale)) + + stat_dist("student_t", size = .75, fun = dt_loc_scale, + args = list(df = df_t, location = 0, scale = scale)) + + stat_dist("cauchy", size = .75, linetype = 2, fun = dcauchy, + args = list(location = 0, scale = scale)) + + stat_dist("laplace", size = .75, linetype = 2, fun = dlaplace, + args = list(location = 0, scale = scale)) + + stat_dist("product_normal", size = .75, linetype = 2, fun = dproduct_normal, + args = list(scale = 1)) +} +# Cauchy has fattest tails, followed by student_t, laplace, and normal +compare_priors() + +# The student_t with df = 1 is the same as the cauchy +compare_priors(df_t = 1) + +# Even a scale of 5 is somewhat large. It gives plausibility to rather +# extreme values +compare_priors(scale = 5, xlim = c(-20,20)) + +# If you use a prior like normal(0, 1000) to be "non-informative" you are +# actually saying that a coefficient value of e.g. -500 is quite plausible +compare_priors(scale = 1000, xlim = c(-1000,1000)) +} +} +\references{ +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., Jakulin, A., Pittau, M. G., and Su, Y. (2008). A weakly +informative default prior distribution for logistic and other regression +models. \emph{Annals of Applied Statistics}. 2(4), 1360--1383. + +Piironen, J., and Vehtari, A. (2017). Sparsity information and regularization +in the horseshoe and other shrinkage priors. \url{https://arxiv.org/abs/1707.01694} + +Stan Development Team. \emph{Stan Modeling Language Users Guide and +Reference Manual.} \url{https://mc-stan.org/users/documentation/}. +} +\seealso{ +The various vignettes for the \pkg{rstanarm} package also discuss + and demonstrate the use of some of the supported prior distributions. +} diff --git a/man/ps_check.Rd b/man/ps_check.Rd new file mode 100644 index 000000000..666459045 --- /dev/null +++ b/man/ps_check.Rd @@ -0,0 +1,80 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ps_check.R +\name{ps_check} +\alias{ps_check} +\title{Graphical checks of the estimated survival function} +\usage{ +ps_check( + object, + check = "survival", + limits = c("ci", "none"), + draws = NULL, + seed = NULL, + xlab = NULL, + ylab = NULL, + ci_geom_args = NULL, + ... +) +} +\arguments{ +\item{object}{A fitted model object returned by the +\code{\link{stan_jm}} modelling function. See +\code{\link{stanreg-objects}}.} + +\item{check}{The type of plot to show. Currently only "survival" is +allowed, which compares the estimated marginal survival function under +the joint model to the estimated Kaplan-Meier curve based on the +observed data.} + +\item{limits}{A quoted character string specifying the type of limits to +include in the plot. Can be one of: \code{"ci"} for the Bayesian +posterior uncertainty interval (often known as a credible interval); +or \code{"none"} for no interval limits.} + +\item{draws}{An integer indicating the number of MCMC draws to use to +to estimate the survival function. The default and maximum number of +draws is the size of the posterior sample.} + +\item{seed}{An optional \code{\link[=set.seed]{seed}} to use.} + +\item{xlab, ylab}{An optional axis label passed to +\code{\link[ggplot2]{labs}}.} + +\item{ci_geom_args}{Optional arguments passed to +\code{\link[ggplot2]{geom_ribbon}} and used to control features +of the plotted interval limits. They should be supplied as a named list.} + +\item{...}{Optional arguments passed to +\code{\link[ggplot2:geom_path]{geom_line}} and used to control features +of the plotted trajectory.} +} +\value{ +A ggplot object that can be further customized using the + \pkg{ggplot2} package. +} +\description{ +This function plots the estimated marginal survival function based on draws +from the posterior predictive distribution of the fitted joint model, and then +overlays the Kaplan-Meier curve based on the observed data. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +if (!exists("example_jm")) example(example_jm) +# Compare estimated survival function to Kaplan-Meier curve +ps <- ps_check(example_jm) +ps + + ggplot2::scale_color_manual(values = c("red", "black")) + # change colors + ggplot2::scale_size_manual(values = c(0.5, 3)) + # change line sizes + ggplot2::scale_fill_manual(values = c(NA, NA)) # remove fill +} +} +} +\seealso{ +\code{\link{posterior_survfit}} for the estimated marginal or + subject-specific survival function based on draws of the model parameters + from the posterior distribution, + \code{\link{posterior_predict}} for drawing from the posterior + predictive distribution for the longitudinal submodel, and + \code{\link{pp_check}} for graphical checks of the longitudinal submodel. +} diff --git a/man/reexports.Rd b/man/reexports.Rd new file mode 100644 index 000000000..eeb735c72 --- /dev/null +++ b/man/reexports.Rd @@ -0,0 +1,16 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/jm_data_block.R +\docType{import} +\name{reexports} +\alias{reexports} +\alias{Surv} +\title{Objects exported from other packages} +\keyword{internal} +\description{ +These objects are imported from other packages. Follow the links +below to see their documentation. + +\describe{ + \item{survival}{\code{\link[survival]{Surv}}} +}} + diff --git a/man/rstanarm-datasets.Rd b/man/rstanarm-datasets.Rd new file mode 100644 index 000000000..7659f5091 --- /dev/null +++ b/man/rstanarm-datasets.Rd @@ -0,0 +1,202 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-datasets.R +\name{rstanarm-datasets} +\alias{rstanarm-datasets} +\alias{kidiq} +\alias{roaches} +\alias{wells} +\alias{bball1970} +\alias{bball2006} +\alias{mortality} +\alias{tumors} +\alias{radon} +\alias{pbcLong} +\alias{pbcSurv} +\title{Datasets for rstanarm examples} +\format{ +\describe{ +\item{\code{bball1970}}{ +Data on hits and at-bats from the 1970 Major League Baseball season for 18 +players. + +Source: Efron and Morris (1975). + +18 obs. of 5 variables +\itemize{ +\item \code{Player} Player's last name +\item \code{Hits} Number of hits in the first 45 at-bats of the season +\item \code{AB} Number of at-bats (45 for all players) +\item \code{RemainingAB} Number of remaining at-bats (different for most players) +\item \code{RemainingHits} Number of remaining hits +} +} +\item{\code{bball2006}}{ +Hits and at-bats for the entire 2006 American League season of Major League +Baseball. + +Source: Carpenter (2009) + +302 obs. of 2 variables +\itemize{ +\item \code{y} Number of hits +\item \code{K} Number of at-bats +} +} +\item{\code{kidiq}}{ +Data from a survey of adult American women and their children +(a subsample from the National Longitudinal Survey of Youth). + +Source: Gelman and Hill (2007) + +434 obs. of 4 variables +\itemize{ +\item \code{kid_score} Child's IQ score +\item \code{mom_hs} Indicator for whether the mother has a high school degree +\item \code{mom_iq} Mother's IQ score +\item \code{mom_age} Mother's age +} +} +\item{\code{mortality}}{ +Surgical mortality rates in 12 hospitals performing cardiac surgery +in babies. + +Source: Spiegelhalter et al. (1996). + +12 obs. of 2 variables +\itemize{ +\item \code{y} Number of deaths +\item \code{K} Number of surgeries +} +} +\item{\code{pbcLong,pbcSurv}}{ +Longitudinal biomarker and time-to-event survival data for 40 patients +with primary biliary cirrhosis who participated in a randomised +placebo controlled trial of D-penicillamine conducted at the Mayo +Clinic between 1974 and 1984. + +Source: Therneau and Grambsch (2000) + +304 obs. of 8 variables (\code{pbcLong}) and 40 obs. of 7 variables (\code{pbcSurv}) +\itemize{ +\item \code{age} in years +\item \code{albumin} serum albumin (g/dl) +\item \code{logBili} logarithm of serum bilirubin +\item \code{death} indicator of death at endpoint +\item \code{futimeYears} time (in years) between baseline and + the earliest of death, transplantion or censoring +\item \code{id} numeric ID unique to each individual +\item \code{platelet} platelet count +\item \code{sex} gender (m = male, f = female) +\item \code{status} status at endpoint (0 = censored, + 1 = transplant, 2 = dead) +\item \code{trt} binary treatment code (0 = placebo, 1 = + D-penicillamine) +\item \code{year} time (in years) of the longitudinal measurements, + taken as time since baseline) +} +} + +\item{\code{radon}}{ +Data on radon levels in houses in the state of Minnesota. + +Source: Gelman and Hill (2007) + +919 obs. of 4 variables +\itemize{ +\item \code{log_radon} Radon measurement from the house (log scale) +\item \code{log_uranium} Uranium level in the county (log scale) +\item \code{floor} Indicator for radon measurement made on the first floor of +the house (0 = basement, 1 = first floor) +\item \code{county} County name (\code{\link{factor}}) +} +} +\item{\code{roaches}}{ +Data on the efficacy of a pest management system at reducing the number of +roaches in urban apartments. + +Source: Gelman and Hill (2007) + +262 obs. of 6 variables +\itemize{ +\item \code{y} Number of roaches caught +\item \code{roach1} Pretreatment number of roaches +\item \code{treatment} Treatment indicator +\item \code{senior} Indicator for only elderly residents in building +\item \code{exposure2} Number of days for which the roach traps were used +} +} +\item{\code{tumors}}{ +Tarone (1982) provides a data set of tumor incidence in historical +control groups of rats; specifically endometrial stromal polyps in +female lab rats of type F344. + +Source: Gelman and Hill (2007) + +71 obs. of 2 variables +\itemize{ +\item \code{y} Number of rats with tumors +\item \code{K} Number of rats +} +} +\item{\code{wells}}{ +A survey of 3200 residents in a small area of Bangladesh suffering from +arsenic contamination of groundwater. Respondents with elevated arsenic +levels in their wells had been encouraged to switch their water source to a +safe public or private well in the nearby area and the survey was conducted +several years later to learn which of the affected residents had switched +wells. + +Souce: Gelman and Hill (2007) + +3020 obs. of 5 variables +\itemize{ +\item \code{switch} Indicator for well-switching +\item \code{arsenic} Arsenic level in respondent's well +\item \code{dist} Distance (meters) from the respondent's house to the +nearest well with safe drinking water. +\item \code{assoc} Indicator for member(s) of household participate +in community organizations +\item \code{educ} Years of education (head of household) +} +} +} +} +\description{ +Small datasets for use in \pkg{rstanarm} examples and vignettes. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +# Using 'kidiq' dataset +fit <- stan_lm(kid_score ~ mom_hs * mom_iq, data = kidiq, + prior = R2(location = 0.30, what = "mean"), + # the next line is only to make the example go fast enough + chains = 1, iter = 500, seed = 12345) +pp_check(fit, nreps = 20) +\donttest{ +bayesplot::color_scheme_set("brightblue") +pp_check(fit, plotfun = "stat_grouped", stat = "median", + group = factor(kidiq$mom_hs, labels = c("No HS", "HS"))) +} +} +} +\references{ +Carpenter, B. (2009) Bayesian estimators for the beta-binomial model of +batting ability. \url{https://web.archive.org/web/20220618114439/https://lingpipe-blog.com/2009/09/23/} + +Efron, B. and Morris, C. (1975) Data analysis using Stein's estimator and its +generalizations. \emph{Journal of the American Statistical Association} +\strong{70}(350), 311--319. + +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/} + +Spiegelhalter, D., Thomas, A., Best, N., & Gilks, W. (1996) BUGS 0.5 +Examples. MRC Biostatistics Unit, Institute of Public health, Cambridge, UK. + +Tarone, R. E. (1982) The use of historical control information in testing for +a trend in proportions. \emph{Biometrics} \strong{38}(1):215--220. + +Therneau, T. and Grambsch, P. (2000) \emph{Modeling Survival Data: Extending +the Cox Model}. Springer-Verlag, New York, US. +} diff --git a/man/rstanarm-deprecated.Rd b/man/rstanarm-deprecated.Rd new file mode 100644 index 000000000..ef5f1f007 --- /dev/null +++ b/man/rstanarm-deprecated.Rd @@ -0,0 +1,43 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-rstanarm-deprecated.R +\name{rstanarm-deprecated} +\alias{rstanarm-deprecated} +\alias{prior_options} +\title{Deprecated functions} +\usage{ +prior_options( + prior_scale_for_dispersion = 5, + min_prior_scale = 1e-12, + scaled = TRUE +) +} +\arguments{ +\item{prior_scale_for_dispersion, min_prior_scale, scaled}{Arguments to +deprecated \code{prior_options} function. The functionality provided +by the now deprecated \code{prior_options} function has been replaced +as follows: +\describe{ +\item{\code{prior_scale_for_dispersion}}{ + Instead of using the \code{prior_scale_for_dispersion} argument to + \code{prior_options}, priors for these parameters can now be + specified directly when calling \code{\link{stan_glm}} (or + \code{\link{stan_glmer}}, etc.) using the new \code{prior_aux} + argument. +} +\item{\code{scaled}}{ + Instead of setting \code{prior_options(scaled=FALSE)}, internal rescaling + is now toggled using the new \code{autoscale} arguments to + \code{\link{normal}}, \code{\link{student_t}}, and \code{\link{cauchy}} + (the other prior distributions do not support 'autoscale'). +} +\item{\code{min_prior_scale}}{ + No replacement. \code{min_prior_scale} (the minimum possible scale + parameter value that be used for priors) is now fixed to \code{1e-12}. +} +}} +} +\description{ +These functions are deprecated and will be removed in a future release. The +\strong{Arguments} section below provides details on how the functionality +obtained via each of the arguments has been replaced. +} diff --git a/man/rstanarm-package.Rd b/man/rstanarm-package.Rd new file mode 100644 index 000000000..c09e6fd5f --- /dev/null +++ b/man/rstanarm-package.Rd @@ -0,0 +1,266 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/doc-rstanarm-package.R +\docType{package} +\name{rstanarm-package} +\alias{rstanarm-package} +\alias{rstanarm} +\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] +} + +} diff --git a/man/se.Rd b/man/se.Rd new file mode 100644 index 000000000..389f70790 --- /dev/null +++ b/man/se.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{se} +\alias{se} +\title{Extract standard errors} +\usage{ +se(object, ...) +} +\arguments{ +\item{object}{A fitted model object.} + +\item{...}{Arguments to methods.} +} +\value{ +Standard errors of model parameters. +} +\description{ +Generic function for extracting standard errors from fitted models. +} +\seealso{ +\code{\link{se.stanreg}} +} +\keyword{internal} diff --git a/man/stan_betareg.Rd b/man/stan_betareg.Rd new file mode 100644 index 000000000..79992b741 --- /dev/null +++ b/man/stan_betareg.Rd @@ -0,0 +1,254 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_betareg.R, R/stan_betareg.fit.R +\name{stan_betareg} +\alias{stan_betareg} +\alias{stan_betareg.fit} +\title{Bayesian beta regression models via Stan} +\usage{ +stan_betareg( + formula, + data, + subset, + na.action, + weights, + offset, + link = c("logit", "probit", "cloglog", "cauchit", "log", "loglog"), + link.phi = NULL, + model = TRUE, + y = TRUE, + x = FALSE, + ..., + prior = normal(autoscale = TRUE), + prior_intercept = normal(autoscale = TRUE), + prior_z = normal(autoscale = TRUE), + prior_intercept_z = normal(autoscale = TRUE), + prior_phi = exponential(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE +) + +stan_betareg.fit( + x, + y, + z = NULL, + weights = rep(1, NROW(x)), + offset = rep(0, NROW(x)), + link = c("logit", "probit", "cloglog", "cauchit", "log", "loglog"), + link.phi = NULL, + ..., + prior = normal(autoscale = TRUE), + prior_intercept = normal(autoscale = TRUE), + prior_z = normal(autoscale = TRUE), + prior_intercept_z = normal(autoscale = TRUE), + prior_phi = exponential(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE +) +} +\arguments{ +\item{formula, data, subset}{Same as \code{\link[betareg]{betareg}}, +but \emph{we strongly advise against omitting the \code{data} +argument}. Unless \code{data} is specified (and is a data frame) many +post-estimation functions (including \code{update}, \code{loo}, +\code{kfold}) are not guaranteed to work properly.} + +\item{na.action}{Same as \code{\link[betareg]{betareg}}, but +rarely specified.} + +\item{link}{Character specification of the link function used in the model +for mu (specified through \code{x}). Currently, "logit", "probit", +"cloglog", "cauchit", "log", and "loglog" are supported.} + +\item{link.phi}{If applicable, character specification of the link function +used in the model for \code{phi} (specified through \code{z}). Currently, +"identity", "log" (default), and "sqrt" are supported. Since the "sqrt" +link function is known to be unstable, it is advisable to specify a +different link function (or to model \code{phi} as a scalar parameter +instead of via a linear predictor by excluding \code{z} from the +\code{formula} and excluding \code{link.phi}).} + +\item{model, offset, weights}{Same as \code{\link[betareg]{betareg}}.} + +\item{x, y}{In \code{stan_betareg}, logical scalars indicating whether to +return the design matrix and response vector. In \code{stan_betareg.fit}, +a design matrix and response vector.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_intercept}{The prior distribution for the intercept (after + centering all predictors, see note below). + + The default prior is described in the vignette + \href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior + Distributions for rstanarm Models}}. + If not using the default, \code{prior_intercept} can be a call to + \code{normal}, \code{student_t} or \code{cauchy}. See the + \link[=priors]{priors help page} for details on these functions. To omit a + prior on the intercept ---i.e., to use a flat (improper) uniform prior--- + \code{prior_intercept} can be set to \code{NULL}. + + \strong{Note:} If using a dense representation of the design matrix + ---i.e., if the \code{sparse} argument is left at its default value of + \code{FALSE}--- then the prior distribution for the intercept is set so it + applies to the value \emph{when all predictors are centered} (you don't + need to manually center them). This is explained further in + [Prior Distributions for rstanarm Models](https://mc-stan.org/rstanarm/articles/priors.html) + If you prefer to specify a prior on the intercept without the predictors + being auto-centered, then you have to omit the intercept from the + \code{\link[stats]{formula}} and include a column of ones as a predictor, + in which case some element of \code{prior} specifies the prior on it, + rather than \code{prior_intercept}. Regardless of how + \code{prior_intercept} is specified, the reported \emph{estimates} of the + intercept always correspond to a parameterization without centered + predictors (i.e., same as in \code{glm}).} + +\item{prior_z}{Prior distribution for the coefficients in the model for +\code{phi} (if applicable). Same options as for \code{prior}.} + +\item{prior_intercept_z}{Prior distribution for the intercept in the model +for \code{phi} (if applicable). Same options as for \code{prior_intercept}.} + +\item{prior_phi}{The prior distribution for \code{phi} if it is \emph{not} +modeled as a function of predictors. If \code{z} variables are specified +then \code{prior_phi} is ignored and \code{prior_intercept_z} and +\code{prior_z} are used to specify the priors on the intercept and +coefficients in the model for \code{phi}. When applicable, \code{prior_phi} +can be a call to \code{exponential} to use an exponential distribution, or +one of \code{normal}, \code{student_t} or \code{cauchy} to use half-normal, +half-t, or half-Cauchy prior. See \code{\link{priors}} for details on these +functions. To omit a prior ---i.e., to use a flat (improper) uniform +prior--- set \code{prior_phi} to \code{NULL}.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{z}{For \code{stan_betareg.fit}, a regressor matrix for \code{phi}. +Defaults to an intercept only.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_betareg}. + +A \link[=stanfit-class]{stanfit} object (or a slightly modified + stanfit object) is returned if \code{stan_betareg.fit} is called directly. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Beta regression modeling with optional prior distributions for the +coefficients, intercept, and auxiliary parameter \code{phi} (if applicable). +} +\details{ +The \code{stan_betareg} function is similar in syntax to + \code{\link[betareg]{betareg}} but rather than performing maximum + likelihood estimation, full Bayesian estimation is performed (if + \code{algorithm} is \code{"sampling"}) via MCMC. The Bayesian model adds + priors (independent by default) on the coefficients of the beta regression + model. The \code{stan_betareg} function calls the workhorse + \code{stan_betareg.fit} function, but it is also possible to call the + latter directly. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +### Simulated data +N <- 200 +x <- rnorm(N, 2, 1) +z <- rnorm(N, 2, 1) +mu <- binomial(link = "logit")$linkinv(1 + 0.2*x) +phi <- exp(1.5 + 0.4*z) +y <- rbeta(N, mu * phi, (1 - mu) * phi) +hist(y, col = "dark grey", border = FALSE, xlim = c(0,1)) +fake_dat <- data.frame(y, x, z) + +fit <- stan_betareg( + y ~ x | z, data = fake_dat, + link = "logit", + link.phi = "log", + algorithm = "optimizing" # just for speed of example + ) +print(fit, digits = 2) +} +} +\references{ +Ferrari, SLP and Cribari-Neto, F (2004). Beta regression for + modeling rates and proportions. \emph{Journal of Applied Statistics}. + 31(7), 799--815. +} +\seealso{ +\code{\link{stanreg-methods}} and +\code{\link[betareg]{betareg}}. + +The vignette for \code{stan_betareg}. + \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stan_biglm.Rd b/man/stan_biglm.Rd new file mode 100644 index 000000000..bdf35c83c --- /dev/null +++ b/man/stan_biglm.Rd @@ -0,0 +1,178 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_biglm.R, R/stan_biglm.fit.R +\name{stan_biglm} +\alias{stan_biglm} +\alias{stan_biglm.fit} +\title{Bayesian regularized linear but big models via Stan} +\usage{ +stan_biglm( + biglm, + xbar, + ybar, + s_y, + ..., + prior = R2(stop("'location' must be specified")), + prior_intercept = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL +) + +stan_biglm.fit( + b, + R, + SSR, + N, + xbar, + ybar, + s_y, + has_intercept = TRUE, + ..., + prior = R2(stop("'location' must be specified")), + prior_intercept = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank", "optimizing"), + adapt_delta = NULL, + importance_resampling = TRUE, + keep_every = 1 +) +} +\arguments{ +\item{biglm}{The list output by \code{\link[biglm]{biglm}} in the \pkg{biglm} +package.} + +\item{xbar}{A numeric vector of column means in the implicit design matrix +excluding the intercept for the observations included in the model.} + +\item{ybar}{A numeric scalar indicating the mean of the outcome for the +observations included in the model.} + +\item{s_y}{A numeric scalar indicating the unbiased sample standard deviation +of the outcome for the observations included in the model.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{prior}{Must be a call to \code{\link{R2}} with its \code{location} +argument specified or \code{NULL}, which would indicate a standard uniform +prior for the \eqn{R^2}.} + +\item{prior_intercept}{Either \code{NULL} (the default) or a call to +\code{\link{normal}}. If a \code{\link{normal}} prior is specified +without a \code{scale}, then the standard deviation is taken to be +the marginal standard deviation of the outcome divided by the square +root of the sample size, which is legitimate because the marginal +standard deviation of the outcome is a primitive parameter being +estimated. + +\strong{Note:} If using a dense representation of the design matrix +---i.e., if the \code{sparse} argument is left at its default value of +\code{FALSE}--- then the prior distribution for the intercept is set so it +applies to the value \emph{when all predictors are centered}. If you prefer +to specify a prior on the intercept without the predictors being +auto-centered, then you have to omit the intercept from the +\code{\link[stats]{formula}} and include a column of ones as a predictor, +in which case some element of \code{prior} specifies the prior on it, +rather than \code{prior_intercept}. Regardless of how +\code{prior_intercept} is specified, the reported \emph{estimates} of the +intercept always correspond to a parameterization without centered +predictors (i.e., same as in \code{glm}).} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{b}{A numeric vector of OLS coefficients, excluding the intercept} + +\item{R}{A square upper-triangular matrix from the QR decomposition of the +design matrix, excluding the intercept} + +\item{SSR}{A numeric scalar indicating the sum-of-squared residuals for OLS} + +\item{N}{A integer scalar indicating the number of included observations} + +\item{has_intercept}{A logical scalar indicating whether to add an intercept +to the model when estimating it.} + +\item{importance_resampling}{Logical scalar indicating whether to use +importance resampling when approximating the posterior distribution with +a multivariate normal around the posterior mode, which only applies +when \code{algorithm} is \code{"optimizing"} but defaults to \code{TRUE} +in that case} + +\item{keep_every}{Positive integer, which defaults to 1, but can be higher +in order to thin the importance sampling realizations and also only +apples when \code{algorithm} is \code{"optimizing"} but defaults to +\code{TRUE} in that case} +} +\value{ +The output of both \code{stan_biglm} and \code{stan_biglm.fit} is an + object of \code{\link[rstan]{stanfit-class}} rather than + \code{\link{stanreg-objects}}, which is more limited and less convenient + but necessitated by the fact that \code{stan_biglm} does not bring the full + design matrix into memory. Without the full design matrix,some of the + elements of a \code{\link{stanreg-objects}} object cannot be calculated, + such as residuals. Thus, the functions in the \pkg{rstanarm} package that + input \code{\link{stanreg-objects}}, such as + \code{\link{posterior_predict}} cannot be used. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +This is the same model as with \code{\link{stan_lm}} but it utilizes the +output from \code{\link[biglm]{biglm}} in the \pkg{biglm} package in order to +proceed when the data is too large to fit in memory. +} +\details{ +The \code{stan_biglm} function is intended to be used in the same + circumstances as the \code{\link[biglm]{biglm}} function in the \pkg{biglm} + package but with an informative prior on the \eqn{R^2} of the regression. + Like \code{\link[biglm]{biglm}}, the memory required to estimate the model + depends largely on the number of predictors rather than the number of + observations. However, \code{stan_biglm} and \code{stan_biglm.fit} have + additional required arguments that are not necessary in + \code{\link[biglm]{biglm}}, namely \code{xbar}, \code{ybar}, and \code{s_y}. + If any observations have any missing values on any of the predictors or the + outcome, such observations do not contribute to these statistics. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +# create inputs +ols <- lm(mpg ~ wt + qsec + am, data = mtcars, # all row are complete so ... + na.action = na.exclude) # not necessary in this case +b <- coef(ols)[-1] +R <- qr.R(ols$qr)[-1,-1] +SSR <- crossprod(ols$residuals)[1] +not_NA <- !is.na(fitted(ols)) +N <- sum(not_NA) +xbar <- colMeans(mtcars[not_NA,c("wt", "qsec", "am")]) +y <- mtcars$mpg[not_NA] +ybar <- mean(y) +s_y <- sd(y) +post <- stan_biglm.fit(b, R, SSR, N, xbar, ybar, s_y, prior = R2(.75), + # the next line is only to make the example go fast + chains = 1, iter = 500, seed = 12345) +cbind(lm = b, stan_lm = rstan::get_posterior_mean(post)[13:15,]) # shrunk +} +} diff --git a/man/stan_clogit.Rd b/man/stan_clogit.Rd new file mode 100644 index 000000000..180fb7df5 --- /dev/null +++ b/man/stan_clogit.Rd @@ -0,0 +1,174 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_clogit.R +\name{stan_clogit} +\alias{stan_clogit} +\title{Conditional logistic (clogit) regression models via Stan} +\usage{ +stan_clogit( + formula, + data, + subset, + na.action = NULL, + contrasts = NULL, + ..., + strata, + prior = normal(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE +) +} +\arguments{ +\item{formula, data, subset, na.action, contrasts}{Same as for \code{\link[lme4]{glmer}}, +except that any global intercept included in the formula will be dropped. +\emph{We strongly advise against omitting the \code{data} argument}. Unless +\code{data} is specified (and is a data frame) many post-estimation +functions (including \code{update}, \code{loo}, \code{kfold}) are not +guaranteed to work properly.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{strata}{A factor indicating the groups in the data where the number of +successes (possibly one) is fixed by the research design. It may be useful +to use \code{\link{interaction}} or \code{\link[survival]{strata}} to +create this factor. However, the \code{strata} argument must not rely on +any object besides the \code{data} \code{\link{data.frame}}.} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_covariance}{Cannot be \code{NULL} when lme4-style group-specific +terms are included in the \code{formula}. See \code{\link{decov}} for +more information about the default arguments. Ignored when there are no +group-specific terms.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_clogit}. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +A model for case-control studies with optional prior distributions for the +coefficients, intercept, and auxiliary parameters. +} +\details{ +The \code{stan_clogit} function is mostly similar in syntax to + \code{\link[survival]{clogit}} but rather than performing maximum + likelihood estimation of generalized linear models, full Bayesian + estimation is performed (if \code{algorithm} is \code{"sampling"}) via + MCMC. The Bayesian model adds priors (independent by default) on the + coefficients of the GLM. + + The \code{data.frame} passed to the \code{data} argument must be sorted by + the variable passed to the \code{strata} argument. + + The \code{formula} may have group-specific terms like in + \code{\link{stan_glmer}} but should not allow the intercept to vary by the + stratifying variable, since there is no information in the data with which + to estimate such deviations in the intercept. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +dat <- infert[order(infert$stratum), ] # order by strata +post <- stan_clogit(case ~ spontaneous + induced + (1 | education), + strata = stratum, + data = dat, + subset = parity <= 2, + QR = TRUE, + chains = 2, iter = 500) # for speed only + +nd <- dat[dat$parity > 2, c("case", "spontaneous", "induced", "education", "stratum")] +# next line would fail without case and stratum variables +pr <- posterior_epred(post, newdata = nd) # get predicted probabilities + +# not a random variable b/c probabilities add to 1 within strata +all.equal(rep(sum(nd$case), nrow(pr)), rowSums(pr)) +} +} +\seealso{ +\code{\link{stanreg-methods}} and +\code{\link[survival]{clogit}}. + +The vignette for Bernoulli and binomial models, which has more + details on using \code{stan_clogit}. + \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stan_gamm4.Rd b/man/stan_gamm4.Rd new file mode 100644 index 000000000..16434f825 --- /dev/null +++ b/man/stan_gamm4.Rd @@ -0,0 +1,288 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_gamm4.R +\name{stan_gamm4} +\alias{stan_gamm4} +\alias{plot_nonlinear} +\title{Bayesian generalized linear additive models with optional group-specific +terms via Stan} +\usage{ +stan_gamm4( + formula, + random = NULL, + family = gaussian(), + data, + weights = NULL, + subset = NULL, + na.action, + knots = NULL, + drop.unused.levels = TRUE, + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_smooth = exponential(autoscale = FALSE), + prior_aux = exponential(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE +) + +plot_nonlinear( + x, + smooths, + ..., + prob = 0.9, + facet_args = list(), + alpha = 1, + size = 0.75 +) +} +\arguments{ +\item{formula, random, family, data, knots, drop.unused.levels}{Same as for +\code{\link[gamm4]{gamm4}}. \emph{We strongly advise against +omitting the \code{data} argument}. Unless \code{data} is specified (and is +a data frame) many post-estimation functions (including \code{update}, +\code{loo}, \code{kfold}) are not guaranteed to work properly.} + +\item{subset, weights, na.action}{Same as \code{\link[stats]{glm}}, +but rarely specified.} + +\item{...}{Further arguments passed to \code{\link[rstan:stanmodel-method-sampling]{sampling}} (e.g. +\code{iter}, \code{chains}, \code{cores}, etc.) or to +\code{\link[rstan:stanmodel-method-vb]{vb}} (if \code{algorithm} is \code{"meanfield"} or +\code{"fullrank"}).} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_intercept}{The prior distribution for the intercept (after + centering all predictors, see note below). + + The default prior is described in the vignette + \href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior + Distributions for rstanarm Models}}. + If not using the default, \code{prior_intercept} can be a call to + \code{normal}, \code{student_t} or \code{cauchy}. See the + \link[=priors]{priors help page} for details on these functions. To omit a + prior on the intercept ---i.e., to use a flat (improper) uniform prior--- + \code{prior_intercept} can be set to \code{NULL}. + + \strong{Note:} If using a dense representation of the design matrix + ---i.e., if the \code{sparse} argument is left at its default value of + \code{FALSE}--- then the prior distribution for the intercept is set so it + applies to the value \emph{when all predictors are centered} (you don't + need to manually center them). This is explained further in + [Prior Distributions for rstanarm Models](https://mc-stan.org/rstanarm/articles/priors.html) + If you prefer to specify a prior on the intercept without the predictors + being auto-centered, then you have to omit the intercept from the + \code{\link[stats]{formula}} and include a column of ones as a predictor, + in which case some element of \code{prior} specifies the prior on it, + rather than \code{prior_intercept}. Regardless of how + \code{prior_intercept} is specified, the reported \emph{estimates} of the + intercept always correspond to a parameterization without centered + predictors (i.e., same as in \code{glm}).} + +\item{prior_smooth}{The prior distribution for the hyperparameters in GAMs, +with lower values yielding less flexible smooth functions. + +\code{prior_smooth} can be a call to \code{exponential} to +use an exponential distribution, or \code{normal}, \code{student_t} or +\code{cauchy}, which results in a half-normal, half-t, or half-Cauchy +prior. See \code{\link{priors}} for details on these functions. To omit a +prior ---i.e., to use a flat (improper) uniform prior--- set +\code{prior_smooth} to \code{NULL}. The number of hyperparameters depends +on the model specification but a scalar prior will be recylced as necessary +to the appropriate length.} + +\item{prior_aux}{The prior distribution for the "auxiliary" parameter (if +applicable). The "auxiliary" parameter refers to a different parameter +depending on the \code{family}. For Gaussian models \code{prior_aux} +controls \code{"sigma"}, the error +standard deviation. For negative binomial models \code{prior_aux} controls +\code{"reciprocal_dispersion"}, which is similar to the +\code{"size"} parameter of \code{\link[stats:NegBinomial]{rnbinom}}: +smaller values of \code{"reciprocal_dispersion"} correspond to +greater dispersion. For gamma models \code{prior_aux} sets the prior on +to the \code{"shape"} parameter (see e.g., +\code{\link[stats:GammaDist]{rgamma}}), and for inverse-Gaussian models it is the +so-called \code{"lambda"} parameter (which is essentially the reciprocal of +a scale parameter). Binomial and Poisson models do not have auxiliary +parameters. + +The default prior is described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior_aux} can be a call to +\code{exponential} to use an exponential distribution, or \code{normal}, +\code{student_t} or \code{cauchy}, which results in a half-normal, half-t, +or half-Cauchy prior. See \code{\link{priors}} for details on these +functions. To omit a prior ---i.e., to use a flat (improper) uniform +prior--- set \code{prior_aux} to \code{NULL}.} + +\item{prior_covariance}{Cannot be \code{NULL}; see \code{\link{decov}} for +more information about the default arguments.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} + +\item{x}{An object produced by \code{stan_gamm4}.} + +\item{smooths}{An optional character vector specifying a subset of the smooth +functions specified in the call to \code{stan_gamm4}. The default is +include all smooth terms.} + +\item{prob}{For univarite smooths, a scalar between 0 and 1 governing the +width of the uncertainty interval.} + +\item{facet_args}{An optional named list of arguments passed to +\code{\link[ggplot2]{facet_wrap}} (other than the \code{facets} argument).} + +\item{alpha, size}{For univariate smooths, passed to +\code{\link[ggplot2]{geom_ribbon}}. For bivariate smooths, \code{size/2} is +passed to \code{\link[ggplot2]{geom_contour}}.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_gamm4}. + +\code{plot_nonlinear} returns a ggplot object. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for GAMMs with flexible priors. +} +\details{ +The \code{stan_gamm4} function is similar in syntax to + \code{\link[gamm4]{gamm4}} in the \pkg{gamm4} package. But rather than performing + (restricted) maximum likelihood estimation with the \pkg{lme4} package, + the \code{stan_gamm4} function utilizes MCMC to perform Bayesian + estimation. The Bayesian model adds priors on the common regression + coefficients (in the same way as \code{\link{stan_glm}}), priors on the + standard deviations of the smooth terms, and a prior on the decomposition + of the covariance matrices of any group-specific parameters (as in + \code{\link{stan_glmer}}). Estimating these models via MCMC avoids + the optimization issues that often crop up with GAMMs and provides better + estimates for the uncertainty in the parameter estimates. + + See \code{\link[gamm4]{gamm4}} for more information about the model + specicification and \code{\link{priors}} for more information about the + priors on the main coefficients. The \code{formula} should include at least + one smooth term, which can be specified in any way that is supported by the + \code{\link[mgcv]{jagam}} function in the \pkg{mgcv} package. The + \code{prior_smooth} argument should be used to specify a prior on the unknown + standard deviations that govern how smooth the smooth function is. The + \code{prior_covariance} argument can be used to specify the prior on the + components of the covariance matrix for any (optional) group-specific terms. + The \code{\link[gamm4]{gamm4}} function in the \pkg{gamm4} package uses + group-specific terms to implement the departure from linearity in the smooth + terms, but that is not the case for \code{stan_gamm4} where the group-specific + terms are exactly the same as in \code{\link{stan_glmer}}. + + The \code{plot_nonlinear} function creates a ggplot object with one facet for + each smooth function specified in the call to \code{stan_gamm4} in the case + where all smooths are univariate. A subset of the smooth functions can be + specified using the \code{smooths} argument, which is necessary to plot a + bivariate smooth or to exclude the bivariate smooth and plot the univariate + ones. In the bivariate case, a plot is produced using + \code{\link[ggplot2]{geom_contour}}. In the univariate case, the resulting + plot is conceptually similar to \code{\link[mgcv]{plot.gam}} except the + outer lines here demark the edges of posterior uncertainty intervals + (credible intervals) rather than confidence intervals and the inner line + is the posterior median of the function rather than the function implied + by a point estimate. To change the colors used in the plot see + \code{\link[bayesplot:bayesplot-colors]{color_scheme_set}}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +# from example(gamm4, package = "gamm4"), prefixing gamm4() call with stan_ +\donttest{ +dat <- mgcv::gamSim(1, n = 400, scale = 2) ## simulate 4 term additive truth +## Now add 20 level random effect `fac'... +dat$fac <- fac <- as.factor(sample(1:20, 400, replace = TRUE)) +dat$y <- dat$y + model.matrix(~ fac - 1) \%*\% rnorm(20) * .5 + +br <- stan_gamm4(y ~ s(x0) + x1 + s(x2), data = dat, random = ~ (1 | fac), + chains = 1, iter = 500) # for example speed +print(br) +plot_nonlinear(br) +plot_nonlinear(br, smooths = "s(x0)", alpha = 2/3) +} +} +} +\references{ +Crainiceanu, C., Ruppert D., and Wand, M. (2005). Bayesian analysis for +penalized spline regression using WinBUGS. \emph{Journal of Statistical +Software}. \strong{14}(14), 1--22. +\url{https://www.jstatsoft.org/article/view/v014i14} +} +\seealso{ +\code{\link{stanreg-methods}} and +\code{\link[gamm4]{gamm4}}. + +The vignette for \code{stan_glmer}, which also discusses + \code{stan_gamm4}. \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stan_glm.Rd b/man/stan_glm.Rd new file mode 100644 index 000000000..a53ae7c61 --- /dev/null +++ b/man/stan_glm.Rd @@ -0,0 +1,434 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_glm.R, R/stan_glm.fit.R +\name{stan_glm} +\alias{stan_glm} +\alias{stan_glm.nb} +\alias{stan_glm.fit} +\title{Bayesian generalized linear models via Stan} +\usage{ +stan_glm( + formula, + family = gaussian(), + data, + weights, + subset, + na.action = NULL, + offset = NULL, + model = TRUE, + x = FALSE, + y = TRUE, + contrasts = NULL, + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + mean_PPD = algorithm != "optimizing" && !prior_PD, + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE +) + +stan_glm.nb( + formula, + data, + weights, + subset, + na.action = NULL, + offset = NULL, + model = TRUE, + x = FALSE, + y = TRUE, + contrasts = NULL, + link = "log", + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + mean_PPD = algorithm != "optimizing", + adapt_delta = NULL, + QR = FALSE +) + +stan_glm.fit( + x, + y, + weights = rep(1, NROW(y)), + offset = rep(0, NROW(y)), + family = gaussian(), + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_smooth = exponential(autoscale = FALSE), + prior_ops = NULL, + group = list(), + prior_PD = FALSE, + algorithm = c("sampling", "optimizing", "meanfield", "fullrank"), + mean_PPD = algorithm != "optimizing" && !prior_PD, + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE, + importance_resampling = algorithm != "sampling", + keep_every = algorithm != "sampling" +) +} +\arguments{ +\item{formula, data, subset}{Same as \code{\link[stats]{glm}}, +but \emph{we strongly advise against omitting the \code{data} +argument}. Unless \code{data} is specified (and is a data frame) many +post-estimation functions (including \code{update}, \code{loo}, +\code{kfold}) are not guaranteed to work properly.} + +\item{family}{Same as \code{\link[stats]{glm}}, except negative binomial GLMs +are also possible using the \code{\link{neg_binomial_2}} family object.} + +\item{na.action, contrasts}{Same as \code{\link[stats]{glm}}, but +rarely specified.} + +\item{model, offset, weights}{Same as \code{\link[stats]{glm}}.} + +\item{x}{In \code{stan_glm}, logical scalar indicating whether to +return the design matrix. In \code{stan_glm.fit}, usually a design matrix +but can also be a list of design matrices with the same number of rows, in +which case the first element of the list is interpreted as the primary design +matrix and the remaining list elements collectively constitute a basis for a +smooth nonlinear function of the predictors indicated by the \code{formula} +argument to \code{\link{stan_gamm4}}.} + +\item{y}{In \code{stan_glm}, logical scalar indicating whether to +return the response vector. In \code{stan_glm.fit}, a response vector.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_intercept}{The prior distribution for the intercept (after + centering all predictors, see note below). + + The default prior is described in the vignette + \href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior + Distributions for rstanarm Models}}. + If not using the default, \code{prior_intercept} can be a call to + \code{normal}, \code{student_t} or \code{cauchy}. See the + \link[=priors]{priors help page} for details on these functions. To omit a + prior on the intercept ---i.e., to use a flat (improper) uniform prior--- + \code{prior_intercept} can be set to \code{NULL}. + + \strong{Note:} If using a dense representation of the design matrix + ---i.e., if the \code{sparse} argument is left at its default value of + \code{FALSE}--- then the prior distribution for the intercept is set so it + applies to the value \emph{when all predictors are centered} (you don't + need to manually center them). This is explained further in + [Prior Distributions for rstanarm Models](https://mc-stan.org/rstanarm/articles/priors.html) + If you prefer to specify a prior on the intercept without the predictors + being auto-centered, then you have to omit the intercept from the + \code{\link[stats]{formula}} and include a column of ones as a predictor, + in which case some element of \code{prior} specifies the prior on it, + rather than \code{prior_intercept}. Regardless of how + \code{prior_intercept} is specified, the reported \emph{estimates} of the + intercept always correspond to a parameterization without centered + predictors (i.e., same as in \code{glm}).} + +\item{prior_aux}{The prior distribution for the "auxiliary" parameter (if +applicable). The "auxiliary" parameter refers to a different parameter +depending on the \code{family}. For Gaussian models \code{prior_aux} +controls \code{"sigma"}, the error +standard deviation. For negative binomial models \code{prior_aux} controls +\code{"reciprocal_dispersion"}, which is similar to the +\code{"size"} parameter of \code{\link[stats:NegBinomial]{rnbinom}}: +smaller values of \code{"reciprocal_dispersion"} correspond to +greater dispersion. For gamma models \code{prior_aux} sets the prior on +to the \code{"shape"} parameter (see e.g., +\code{\link[stats:GammaDist]{rgamma}}), and for inverse-Gaussian models it is the +so-called \code{"lambda"} parameter (which is essentially the reciprocal of +a scale parameter). Binomial and Poisson models do not have auxiliary +parameters. + +The default prior is described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior_aux} can be a call to +\code{exponential} to use an exponential distribution, or \code{normal}, +\code{student_t} or \code{cauchy}, which results in a half-normal, half-t, +or half-Cauchy prior. See \code{\link{priors}} for details on these +functions. To omit a prior ---i.e., to use a flat (improper) uniform +prior--- set \code{prior_aux} to \code{NULL}.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{mean_PPD}{A logical value indicating whether the sample mean of the +posterior predictive distribution of the outcome should be calculated in +the \code{generated quantities} block. If \code{TRUE} then \code{mean_PPD} +is computed and displayed as a diagnostic in the +\link[=print.stanreg]{printed output}. The default is \code{TRUE} except if +\code{algorithm=="optimizing"}. A useful heuristic is to check if +\code{mean_PPD} is plausible when compared to \code{mean(y)}. If it is +plausible then this does \emph{not} mean that the model is good in general +(only that it can reproduce the sample mean), but if \code{mean_PPD} is +implausible then there may be something wrong, e.g., severe model +misspecification, problems with the data and/or priors, computational +issues, etc.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} + +\item{link}{For \code{stan_glm.nb} only, the link function to use. See +\code{\link{neg_binomial_2}}.} + +\item{prior_smooth}{The prior distribution for the hyperparameters in GAMs, +with lower values yielding less flexible smooth functions. + +\code{prior_smooth} can be a call to \code{exponential} to +use an exponential distribution, or \code{normal}, \code{student_t} or +\code{cauchy}, which results in a half-normal, half-t, or half-Cauchy +prior. See \code{\link{priors}} for details on these functions. To omit a +prior ---i.e., to use a flat (improper) uniform prior--- set +\code{prior_smooth} to \code{NULL}. The number of hyperparameters depends +on the model specification but a scalar prior will be recylced as necessary +to the appropriate length.} + +\item{prior_ops}{Deprecated. See \link{rstanarm-deprecated} for details.} + +\item{group}{A list, possibly of length zero (the default), but otherwise +having the structure of that produced by \code{\link[lme4]{mkReTrms}} to +indicate the group-specific part of the model. In addition, this list must +have elements for the \code{regularization}, \code{concentration} +\code{shape}, and \code{scale} components of a \code{\link{decov}} +prior for the covariance matrices among the group-specific coefficients.} + +\item{importance_resampling}{Logical scalar indicating whether to use +importance resampling when approximating the posterior distribution with +a multivariate normal around the posterior mode, which only applies +when \code{algorithm} is \code{"optimizing"} but defaults to \code{TRUE} +in that case} + +\item{keep_every}{Positive integer, which defaults to 1, but can be higher +in order to "thin" the importance sampling realizations. Applies only +when \code{importance_resampling=TRUE}.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_glm, stan_glm.nb}. + +A \link[=stanfit-class]{stanfit} object (or a slightly modified + stanfit object) is returned if \code{stan_glm.fit} is called directly. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Generalized linear modeling with optional prior distributions for the +coefficients, intercept, and auxiliary parameters. +} +\details{ +The \code{stan_glm} function is similar in syntax to + \code{\link[stats]{glm}} but rather than performing maximum likelihood + estimation of generalized linear models, full Bayesian estimation is + performed (if \code{algorithm} is \code{"sampling"}) via MCMC. The Bayesian + model adds priors (independent by default) on the coefficients of the GLM. + The \code{stan_glm} function calls the workhorse \code{stan_glm.fit} + function, but it is also possible to call the latter directly. + + The \code{stan_glm.nb} function, which takes the extra argument + \code{link}, is a wrapper for \code{stan_glm} with \code{family = + \link{neg_binomial_2}(link)}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +### Linear regression +mtcars$mpg10 <- mtcars$mpg / 10 +fit <- stan_glm( + mpg10 ~ wt + cyl + am, + data = mtcars, + QR = TRUE, + # for speed of example only (default is "sampling") + algorithm = "fullrank", + refresh = 0 + ) + +plot(fit, prob = 0.5) +plot(fit, prob = 0.5, pars = "beta") +plot(fit, "hist", pars = "sigma") +\donttest{ +### Logistic regression +head(wells) +wells$dist100 <- wells$dist / 100 +fit2 <- stan_glm( + switch ~ dist100 + arsenic, + data = wells, + family = binomial(link = "logit"), + prior_intercept = normal(0, 10), + QR = TRUE, + refresh = 0, + # for speed of example only + chains = 2, iter = 200 +) +print(fit2) +prior_summary(fit2) + +# ?bayesplot::mcmc_areas +plot(fit2, plotfun = "areas", prob = 0.9, + pars = c("(Intercept)", "arsenic")) + +# ?bayesplot::ppc_error_binned +pp_check(fit2, plotfun = "error_binned") + + +### Poisson regression (example from help("glm")) +count_data <- data.frame( + counts = c(18,17,15,20,10,20,25,13,12), + outcome = gl(3,1,9), + treatment = gl(3,3) +) +fit3 <- stan_glm( + counts ~ outcome + treatment, + data = count_data, + family = poisson(link="log"), + prior = normal(0, 2), + refresh = 0, + # for speed of example only + chains = 2, iter = 250 +) +print(fit3) + +bayesplot::color_scheme_set("viridis") +plot(fit3) +plot(fit3, regex_pars = c("outcome", "treatment")) +plot(fit3, plotfun = "combo", regex_pars = "treatment") # ?bayesplot::mcmc_combo +posterior_vs_prior(fit3, regex_pars = c("outcome", "treatment")) + +### Gamma regression (example from help("glm")) +clotting <- data.frame(log_u = log(c(5,10,15,20,30,40,60,80,100)), + lot1 = c(118,58,42,35,27,25,21,19,18), + lot2 = c(69,35,26,21,18,16,13,12,12)) +fit4 <- stan_glm( + lot1 ~ log_u, + data = clotting, + family = Gamma(link="log"), + iter = 500, # for speed of example only + refresh = 0 + ) +print(fit4, digits = 2) + +fit5 <- update(fit4, formula = lot2 ~ log_u) + +# ?bayesplot::ppc_dens_overlay +bayesplot::bayesplot_grid( + pp_check(fit4, seed = 123), + pp_check(fit5, seed = 123), + titles = c("lot1", "lot2") +) + + +### Negative binomial regression +fit6 <- stan_glm.nb( + Days ~ Sex/(Age + Eth*Lrn), + data = MASS::quine, + link = "log", + prior_aux = exponential(1.5, autoscale=TRUE), + chains = 2, iter = 200, # for speed of example only + refresh = 0 +) + +prior_summary(fit6) +bayesplot::color_scheme_set("brightblue") +plot(fit6) +pp_check(fit6, plotfun = "hist", nreps = 5) # ?bayesplot::ppc_hist + +# 80\% interval of estimated reciprocal_dispersion parameter +posterior_interval(fit6, pars = "reciprocal_dispersion", prob = 0.8) +plot(fit6, "areas", pars = "reciprocal_dispersion", prob = 0.8) +} +} +} +\references{ +Gelman, A. and Hill, J. (2007). \emph{Data Analysis Using + Regression and Multilevel/Hierarchical Models.} Cambridge University Press, + Cambridge, UK. (Ch. 3-6) + +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{ +\code{\link{stanreg-methods}} and +\code{\link[stats]{glm}}. + +The various vignettes for \code{stan_glm} at + \url{https://mc-stan.org/rstanarm/articles/}. +} diff --git a/man/stan_glmer.Rd b/man/stan_glmer.Rd new file mode 100644 index 000000000..e8c0d6dd9 --- /dev/null +++ b/man/stan_glmer.Rd @@ -0,0 +1,275 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_glmer.R +\name{stan_glmer} +\alias{stan_glmer} +\alias{stan_lmer} +\alias{stan_glmer.nb} +\title{Bayesian generalized linear models with group-specific terms via Stan} +\usage{ +stan_glmer( + formula, + data = NULL, + family = gaussian, + subset, + weights, + na.action = getOption("na.action", "na.omit"), + offset, + contrasts = NULL, + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE +) + +stan_lmer( + formula, + data = NULL, + subset, + weights, + na.action = getOption("na.action", "na.omit"), + offset, + contrasts = NULL, + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE +) + +stan_glmer.nb( + formula, + data = NULL, + subset, + weights, + na.action = getOption("na.action", "na.omit"), + offset, + contrasts = NULL, + link = "log", + ..., + prior = default_prior_coef(family), + prior_intercept = default_prior_intercept(family), + prior_aux = exponential(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE +) +} +\arguments{ +\item{formula, data}{Same as for \code{\link[lme4]{glmer}}. \emph{We +strongly advise against omitting the \code{data} argument}. Unless +\code{data} is specified (and is a data frame) many post-estimation +functions (including \code{update}, \code{loo}, \code{kfold}) are not +guaranteed to work properly.} + +\item{family}{Same as for \code{\link[lme4]{glmer}} except it is also +possible to use \code{family=mgcv::betar} to estimate a Beta regression +with \code{stan_glmer}.} + +\item{subset, weights, offset}{Same as \code{\link[stats]{glm}}.} + +\item{na.action, contrasts}{Same as \code{\link[stats]{glm}}, but rarely +specified.} + +\item{...}{For \code{stan_glmer}, further arguments passed to +\code{\link[rstan:stanmodel-method-sampling]{sampling}} (e.g. \code{iter}, \code{chains}, +\code{cores}, etc.) or to \code{\link[rstan:stanmodel-method-vb]{vb}} (if \code{algorithm} is +\code{"meanfield"} or \code{"fullrank"}). For \code{stan_lmer} and +\code{stan_glmer.nb}, \code{...} should also contain all relevant arguments +to pass to \code{stan_glmer} (except \code{family}).} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_intercept}{The prior distribution for the intercept (after + centering all predictors, see note below). + + The default prior is described in the vignette + \href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior + Distributions for rstanarm Models}}. + If not using the default, \code{prior_intercept} can be a call to + \code{normal}, \code{student_t} or \code{cauchy}. See the + \link[=priors]{priors help page} for details on these functions. To omit a + prior on the intercept ---i.e., to use a flat (improper) uniform prior--- + \code{prior_intercept} can be set to \code{NULL}. + + \strong{Note:} If using a dense representation of the design matrix + ---i.e., if the \code{sparse} argument is left at its default value of + \code{FALSE}--- then the prior distribution for the intercept is set so it + applies to the value \emph{when all predictors are centered} (you don't + need to manually center them). This is explained further in + [Prior Distributions for rstanarm Models](https://mc-stan.org/rstanarm/articles/priors.html) + If you prefer to specify a prior on the intercept without the predictors + being auto-centered, then you have to omit the intercept from the + \code{\link[stats]{formula}} and include a column of ones as a predictor, + in which case some element of \code{prior} specifies the prior on it, + rather than \code{prior_intercept}. Regardless of how + \code{prior_intercept} is specified, the reported \emph{estimates} of the + intercept always correspond to a parameterization without centered + predictors (i.e., same as in \code{glm}).} + +\item{prior_aux}{The prior distribution for the "auxiliary" parameter (if +applicable). The "auxiliary" parameter refers to a different parameter +depending on the \code{family}. For Gaussian models \code{prior_aux} +controls \code{"sigma"}, the error +standard deviation. For negative binomial models \code{prior_aux} controls +\code{"reciprocal_dispersion"}, which is similar to the +\code{"size"} parameter of \code{\link[stats:NegBinomial]{rnbinom}}: +smaller values of \code{"reciprocal_dispersion"} correspond to +greater dispersion. For gamma models \code{prior_aux} sets the prior on +to the \code{"shape"} parameter (see e.g., +\code{\link[stats:GammaDist]{rgamma}}), and for inverse-Gaussian models it is the +so-called \code{"lambda"} parameter (which is essentially the reciprocal of +a scale parameter). Binomial and Poisson models do not have auxiliary +parameters. + +The default prior is described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior_aux} can be a call to +\code{exponential} to use an exponential distribution, or \code{normal}, +\code{student_t} or \code{cauchy}, which results in a half-normal, half-t, +or half-Cauchy prior. See \code{\link{priors}} for details on these +functions. To omit a prior ---i.e., to use a flat (improper) uniform +prior--- set \code{prior_aux} to \code{NULL}.} + +\item{prior_covariance}{Cannot be \code{NULL}; see \code{\link{decov}} for +more information about the default arguments.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} + +\item{link}{For \code{stan_glmer.nb} only, the link function to use. See +\code{\link{neg_binomial_2}}.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_glmer, stan_lmer, stan_glmer.nb}. + +A list with classes \code{stanreg}, \code{glm}, \code{lm}, + and \code{lmerMod}. The conventions for the parameter names are the + same as in the lme4 package with the addition that the standard + deviation of the errors is called \code{sigma} and the variance-covariance + matrix of the group-specific deviations from the common parameters is + called \code{Sigma}, even if this variance-covariance matrix only has + one row and one column (in which case it is just the group-level variance). +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for GLMs with group-specific coefficients that have +unknown covariance matrices with flexible priors. +} +\details{ +The \code{stan_glmer} function is similar in syntax to + \code{\link[lme4]{glmer}} but rather than performing (restricted) maximum + likelihood estimation of generalized linear models, Bayesian estimation is + performed via MCMC. The Bayesian model adds priors on the + regression coefficients (in the same way as \code{\link{stan_glm}}) and + priors on the terms of a decomposition of the covariance matrices of the + group-specific parameters. See \code{\link{priors}} for more information + about the priors. + + The \code{stan_lmer} function is equivalent to \code{stan_glmer} with + \code{family = gaussian(link = "identity")}. + + The \code{stan_glmer.nb} function, which takes the extra argument + \code{link}, is a wrapper for \code{stan_glmer} with \code{family = + \link{neg_binomial_2}(link)}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +# see help(example_model) for details on the model below +if (!exists("example_model")) example(example_model) +print(example_model, digits = 1) +} +} +\references{ +Gelman, A. and Hill, J. (2007). \emph{Data Analysis Using + Regression and Multilevel/Hierarchical Models.} Cambridge University Press, + Cambridge, UK. (Ch. 11-15) + +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{ +\code{\link{stanreg-methods}} and +\code{\link[lme4]{glmer}}. + +The vignette for \code{stan_glmer} and the \emph{Hierarchical + Partial Pooling} vignette. \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stan_jm.Rd b/man/stan_jm.Rd new file mode 100644 index 000000000..758f575d0 --- /dev/null +++ b/man/stan_jm.Rd @@ -0,0 +1,622 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_jm.R +\name{stan_jm} +\alias{stan_jm} +\title{Bayesian joint longitudinal and time-to-event models via Stan} +\usage{ +stan_jm( + formulaLong, + dataLong, + formulaEvent, + dataEvent, + time_var, + id_var, + family = gaussian, + assoc = "etavalue", + lag_assoc = 0, + grp_assoc, + scale_assoc = NULL, + epsilon = 1e-05, + basehaz = c("bs", "weibull", "piecewise"), + basehaz_ops, + qnodes = 15, + init = "prefit", + weights, + priorLong = normal(autoscale = TRUE), + priorLong_intercept = normal(autoscale = TRUE), + priorLong_aux = cauchy(0, 5, autoscale = TRUE), + priorEvent = normal(autoscale = TRUE), + priorEvent_intercept = normal(autoscale = TRUE), + priorEvent_aux = cauchy(autoscale = TRUE), + priorEvent_assoc = normal(autoscale = TRUE), + prior_covariance = lkj(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + max_treedepth = 10L, + QR = FALSE, + sparse = FALSE, + ... +) +} +\arguments{ +\item{formulaLong}{A two-sided linear formula object describing both the +fixed-effects and random-effects parts of the longitudinal submodel, +similar in vein to formula specification in the \strong{lme4} package +(see \code{\link[lme4]{glmer}} or the \strong{lme4} vignette for details). +Note however that the double bar (\code{||}) notation is not allowed +when specifying the random-effects parts of the formula, and neither +are nested grouping factors (e.g. \code{(1 | g1/g2))} or +\code{(1 | g1:g2)}, where \code{g1}, \code{g2} are grouping factors. +Offset terms can also be included in the model formula. +For a multivariate joint model (i.e. more than one longitudinal marker) +this should be a list of such formula objects, with each element +of the list providing the formula for one of the longitudinal submodels.} + +\item{dataLong}{A data frame containing the variables specified in +\code{formulaLong}. If fitting a multivariate joint model, then this can +be either a single data frame which contains the data for all +longitudinal submodels, or it can be a list of data frames where each +element of the list provides the data for one of the longitudinal +submodels.} + +\item{formulaEvent}{A two-sided formula object describing the event +submodel. The left hand side of the formula should be a \code{Surv()} +object. See \code{\link[survival]{Surv}}.} + +\item{dataEvent}{A data frame containing the variables specified in +\code{formulaEvent}.} + +\item{time_var}{A character string specifying the name of the variable +in \code{dataLong} which represents time.} + +\item{id_var}{A character string specifying the name of the variable in +\code{dataLong} which distinguishes between individuals. This can be +left unspecified if there is only one grouping factor (which is assumed +to be the individual). If there is more than one grouping factor (i.e. +clustering beyond the level of the individual) then the \code{id_var} +argument must be specified.} + +\item{family}{The family (and possibly also the link function) for the +longitudinal submodel(s). See \code{\link[lme4]{glmer}} for details. +If fitting a multivariate joint model, then this can optionally be a +list of families, in which case each element of the list specifies the +family for one of the longitudinal submodels.} + +\item{assoc}{A character string or character vector specifying the joint +model association structure. Possible association structures that can +be used include: "etavalue" (the default); "etaslope"; "etaauc"; +"muvalue"; "muslope"; "muauc"; "shared_b"; "shared_coef"; or "null". +These are described in the \strong{Details} section below. For a multivariate +joint model, different association structures can optionally be used for +each longitudinal submodel by specifying a list of character +vectors, with each element of the list specifying the desired association +structure for one of the longitudinal submodels. Specifying \code{assoc = NULL} +will fit a joint model with no association structure (equivalent +to fitting separate longitudinal and time-to-event models). It is also +possible to include interaction terms between the association term +("etavalue", "etaslope", "muvalue", "muslope") and observed data/covariates. +It is also possible, when fitting a multivariate joint model, to include +interaction terms between the association terms ("etavalue" or "muvalue") +corresponding to the different longitudinal outcomes. See the +\strong{Details} section as well as the \strong{Examples} below.} + +\item{lag_assoc}{A non-negative scalar specifying the time lag that should be +used for the association structure. That is, the hazard of the event at +time \emph{t} will be assumed to be associated with the value/slope/auc of +the longitudinal marker at time \emph{t-u}, where \emph{u} is the time lag. +If fitting a multivariate joint model, then a different time lag can be used +for each longitudinal marker by providing a numeric vector of lags, otherwise +if a scalar is provided then the specified time lag will be used for all +longitudinal markers. Note however that only one time lag can be specified +for linking each longitudinal marker to the +event, and that that time lag will be used for all association structure +types (e.g. \code{"etavalue"}, \code{"etaslope"}, \code{"etaauc"}, +\code{"muvalue"}, etc) that are specified for that longitudinal marker in +the \code{assoc} argument.} + +\item{grp_assoc}{Character string specifying the method for combining information +across lower level units clustered within an individual when forming the +association structure. This is only relevant when a grouping factor is +specified in \code{formulaLong} that corresponds to clustering within +individuals. This can be specified as either \code{"sum"}, \code{mean}, +\code{"min"} or \code{"max"}. For example, specifying \code{grp_assoc = "sum"} +indicates that the association structure should be based on a summation across +the lower level units clustered within an individual, or specifying +\code{grp_assoc = "mean"} indicates that the association structure +should be based on the mean (i.e. average) taken across the lower level +units clustered within an individual. +So, for example, specifying \code{assoc = "muvalue"} +and \code{grp_assoc = "sum"} would mean that the log hazard at time +\emph{t} for individual \emph{i} would be linearly related to the sum of +the expected values at time \emph{t} for each of the lower level +units (which may be for example tumor lesions) clustered within that +individual.} + +\item{scale_assoc}{A non-zero numeric value specifying an optional scaling +parameter for the association structure. This multiplicatively scales the +value/slope/auc of the longitudinal marker by \code{scale_assoc} within the +event submodel. When fitting a multivariate joint model, a scaling parameter +must be specified for each longitudinal submodel using a vector of numeric +values. Note that only one scaling parameter can be specified for each +longitudinal submodel, and it will be used for all association structure +types (e.g. \code{"etavalue"}, \code{"etaslope"}, \code{"etaauc"}, +\code{"muvalue"}, etc) that are specified for that longitudinal marker in +the \code{assoc} argument.} + +\item{epsilon}{The half-width of the central difference used to numerically +calculate the derivate when the \code{"etaslope"} association structure +is used.} + +\item{basehaz}{A character string indicating which baseline hazard to use +for the event submodel. Options are a B-splines approximation estimated +for the log baseline hazard (\code{"bs"}, the default), a Weibull +baseline hazard (\code{"weibull"}), or a piecewise +constant baseline hazard (\code{"piecewise"}). (Note however that there +is currently limited post-estimation functionality available for +models estimated using a piecewise constant baseline hazard).} + +\item{basehaz_ops}{A named list specifying options related to the baseline +hazard. Currently this can include: \cr +\describe{ + \item{\code{df}}{A positive integer specifying the degrees of freedom + for the B-splines if \code{basehaz = "bs"}, or the number of + intervals used for the piecewise constant baseline hazard if + \code{basehaz = "piecewise"}. The default is 6.} + \item{\code{knots}}{An optional numeric vector specifying the internal knot + locations for the B-splines if \code{basehaz = "bs"}, or the + internal cut-points for defining intervals of the piecewise constant + baseline hazard if \code{basehaz = "piecewise"}. Knots cannot be + specified if \code{df} is specified. If not specified, then the + default is to use \code{df - 4} knots if \code{basehaz = "bs"}, + or \code{df - 1} knots if \code{basehaz = "piecewise"}, which are + placed at equally spaced percentiles of the distribution of + observed event times.} +}} + +\item{qnodes}{The number of nodes to use for the Gauss-Kronrod quadrature +that is used to evaluate the cumulative hazard in the likelihood function. +Options are 15 (the default), 11 or 7.} + +\item{init}{The method for generating the initial values for the MCMC. +The default is \code{"prefit"}, which uses those obtained from +fitting separate longitudinal and time-to-event models prior to +fitting the joint model. The separate longitudinal model is a +(possibly multivariate) generalised linear mixed +model estimated using variational bayes. This is achieved via the +\code{\link{stan_mvmer}} function with \code{algorithm = "meanfield"}. +The separate Cox model is estimated using \code{\link[survival]{coxph}}. +This is achieved +using the and time-to-event models prior +to fitting the joint model. The separate models are estimated using the +\code{\link[lme4]{glmer}} and \code{\link[survival]{coxph}} functions. +This should provide reasonable initial values which should aid the +MCMC sampler. Parameters that cannot be obtained from +fitting separate longitudinal and time-to-event models are initialised +using the "random" method for \code{\link[rstan]{stan}}. +However it is recommended that any final analysis should ideally +be performed with several MCMC chains each initiated from a different +set of initial values; this can be obtained by setting +\code{init = "random"}. In addition, other possibilities for specifying +\code{init} are the same as those described for \code{\link[rstan]{stan}}.} + +\item{weights}{Experimental and should be used with caution. The +user can optionally supply a 2-column data frame containing a set of +'prior weights' to be used in the estimation process. The data frame should +contain two columns: the first containing the IDs for each individual, and +the second containing the corresponding weights. The data frame should only +have one row for each individual; that is, weights should be constant +within individuals.} + +\item{priorLong, priorEvent, priorEvent_assoc}{The prior distributions for the +regression coefficients in the longitudinal submodel(s), event submodel, +and the association parameter(s). Can be a call to one of the various functions +provided by \pkg{rstanarm} for specifying priors. The subset of these functions +that can be used for the prior on the coefficients can be grouped into several +"families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the scales +of the predictors. See the \link[=priors]{priors help page} for details on +the rescaling and the \code{\link{prior_summary}} function for a summary of +the priors used for a particular model.} + +\item{priorLong_intercept, priorEvent_intercept}{The prior distributions +for the intercepts in the longitudinal submodel(s) and event submodel. +Can be a call to \code{normal}, \code{student_t} or +\code{cauchy}. See the \link[=priors]{priors help page} for details on +these functions. To omit a prior on the intercept ---i.e., to use a flat +(improper) uniform prior--- \code{prior_intercept} can be set to +\code{NULL}. + +\strong{Note:} The prior distribution for the intercept is set so it +applies to the value when all predictors are centered. Moreover, +note that a prior is only placed on the intercept for the event submodel +when a Weibull baseline hazard has been specified. For the B-splines and +piecewise constant baseline hazards there is not intercept parameter that +is given a prior distribution; an intercept parameter will be shown in +the output for the fitted model, but this just corresponds to the +necessary post-estimation adjustment in the linear predictor due to the +centering of the predictiors in the event submodel.} + +\item{priorLong_aux}{The prior distribution for the "auxiliary" parameters +in the longitudinal submodels (if applicable). +The "auxiliary" parameter refers to a different parameter +depending on the \code{family}. For Gaussian models \code{priorLong_aux} +controls \code{"sigma"}, the error +standard deviation. For negative binomial models \code{priorLong_aux} controls +\code{"reciprocal_dispersion"}, which is similar to the +\code{"size"} parameter of \code{\link[stats:NegBinomial]{rnbinom}}: +smaller values of \code{"reciprocal_dispersion"} correspond to +greater dispersion. For gamma models \code{priorLong_aux} sets the prior on +to the \code{"shape"} parameter (see e.g., +\code{\link[stats:GammaDist]{rgamma}}), and for inverse-Gaussian models it is the +so-called \code{"lambda"} parameter (which is essentially the reciprocal of +a scale parameter). Binomial and Poisson models do not have auxiliary +parameters. + +\code{priorLong_aux} can be a call to \code{exponential} to +use an exponential distribution, or \code{normal}, \code{student_t} or +\code{cauchy}, which results in a half-normal, half-t, or half-Cauchy +prior. See \code{\link{priors}} for details on these functions. To omit a +prior ---i.e., to use a flat (improper) uniform prior--- set +\code{priorLong_aux} to \code{NULL}. + +If fitting a multivariate joint model, you have the option to +specify a list of prior distributions, however the elements of the list +that correspond to any longitudinal submodel which does not have an +auxiliary parameter will be ignored.} + +\item{priorEvent_aux}{The prior distribution for the "auxiliary" parameters +in the event submodel. The "auxiliary" parameters refers to different +parameters depending on the baseline hazard. For \code{basehaz = "weibull"} +the auxiliary parameter is the Weibull shape parameter. For +\code{basehaz = "bs"} the auxiliary parameters are the coefficients for the +B-spline approximation to the log baseline hazard. +For \code{basehaz = "piecewise"} the auxiliary parameters are the piecewise +estimates of the log baseline hazard.} + +\item{prior_covariance}{Cannot be \code{NULL}; see \code{\link{priors}} for +more information about the prior distributions on covariance matrices. +Note however that the default prior for covariance matrices in +\code{stan_jm} is slightly different to that in \code{\link{stan_glmer}} +(the details of which are described on the \code{\link{priors}} page).} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{max_treedepth}{A positive integer specifying the maximum treedepth +for the non-U-turn sampler. See the \code{control} argument in +\code{\link[rstan]{stan}}.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} +} +\value{ +A \link[=stanreg-objects]{stanjm} object is returned. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Fits a shared parameter joint model for longitudinal and time-to-event +(e.g. survival) data under a Bayesian framework using Stan. +} +\details{ +The \code{stan_jm} function can be used to fit a joint model (also + known as a shared parameter model) for longitudinal and time-to-event data + under a Bayesian framework. The underlying + estimation is carried out using the Bayesian C++ package Stan + (\url{https://mc-stan.org/}). \cr + \cr + The joint model may be univariate (with only one longitudinal submodel) or + multivariate (with more than one longitudinal submodel). + For the longitudinal submodel a (possibly multivariate) generalised linear + mixed model is assumed with any of the \code{\link[stats]{family}} choices + allowed by \code{\link[lme4]{glmer}}. If a multivariate joint model is specified + (by providing a list of formulas in the \code{formulaLong} argument), then + the multivariate longitudinal submodel consists of a multivariate generalized + linear model (GLM) with group-specific terms that are assumed to be correlated + across the different GLM submodels. That is, within + a grouping factor (for example, patient ID) the group-specific terms are + assumed to be correlated across the different GLM submodels. It is + possible to specify a different outcome type (for example a different + family and/or link function) for each of the GLM submodels, by providing + a list of \code{\link[stats]{family}} objects in the \code{family} + argument. Multi-level + clustered data are allowed, and that additional clustering can occur at a + level higher than the individual-level (e.g. patients clustered within + clinics), or at a level lower than the individual-level (e.g. tumor lesions + clustered within patients). If the clustering occurs at a level lower than + the individual, then the user needs to indicate how the lower level + clusters should be handled when forming the association structure between + the longitudinal and event submodels (see the \code{grp_assoc} argument + described above). \cr + \cr + For the event submodel a parametric + proportional hazards model is assumed. The baseline hazard can be estimated + using either a cubic B-splines approximation (\code{basehaz = "bs"}, the + default), a Weibull distribution (\code{basehaz = "weibull"}), or a + piecewise constant baseline hazard (\code{basehaz = "piecewise"}). + If the B-spline or piecewise constant baseline hazards are used, + then the degrees of freedom or the internal knot locations can be + (optionally) specified. If + the degrees of freedom are specified (through the \code{df} argument) then + the knot locations are automatically generated based on the + distribution of the observed event times (not including censoring times). + Otherwise internal knot locations can be specified + directly through the \code{knots} argument. If neither \code{df} or + \code{knots} is specified, then the default is to set \code{df} equal to 6. + It is not possible to specify both \code{df} and \code{knots}. \cr + \cr + Time-varying covariates are allowed in both the + longitudinal and event submodels. These should be specified in the data + in the same way as they normally would when fitting a separate + longitudinal model using \code{\link[lme4]{lmer}} or a separate + time-to-event model using \code{\link[survival]{coxph}}. These time-varying + covariates should be exogenous in nature, otherwise they would perhaps + be better specified as an additional outcome (i.e. by including them as an + additional longitudinal outcome in the joint model). \cr + \cr + Bayesian estimation of the joint model is performed via MCMC. The Bayesian + model includes independent priors on the + regression coefficients for both the longitudinal and event submodels, + including the association parameter(s) (in much the same way as the + regression parameters in \code{\link{stan_glm}}) and + priors on the terms of a decomposition of the covariance matrices of the + group-specific parameters. + See \code{\link{priors}} for more information about the priors distributions + that are available. \cr + \cr + Gauss-Kronrod quadrature is used to numerically evaluate the integral + over the cumulative hazard in the likelihood function for the event submodel. + The accuracy of the numerical approximation can be controlled using the + number of quadrature nodes, specified through the \code{qnodes} + argument. Using a higher number of quadrature nodes will result in a more + accurate approximation. + + \subsection{Association structures}{ + The association structure for the joint model can be based on any of the + following parameterisations: + \itemize{ + \item current value of the linear predictor in the + longitudinal submodel (\code{"etavalue"}) + \item first derivative (slope) of the linear predictor in the + longitudinal submodel (\code{"etaslope"}) + \item the area under the curve of the linear predictor in the + longitudinal submodel (\code{"etaauc"}) + \item current expected value of the longitudinal submodel + (\code{"muvalue"}) + \item the area under the curve of the expected value from the + longitudinal submodel (\code{"muauc"}) + \item shared individual-level random effects (\code{"shared_b"}) + \item shared individual-level random effects which also incorporate + the corresponding fixed effect as well as any corresponding + random effects for clustering levels higher than the individual) + (\code{"shared_coef"}) + \item interactions between association terms and observed data/covariates + (\code{"etavalue_data"}, \code{"etaslope_data"}, \code{"muvalue_data"}, + \code{"muslope_data"}). These are described further below. + \item interactions between association terms corresponding to different + longitudinal outcomes in a multivariate joint model + (\code{"etavalue_etavalue(#)"}, \code{"etavalue_muvalue(#)"}, + \code{"muvalue_etavalue(#)"}, \code{"muvalue_muvalue(#)"}). These + are described further below. + \item no association structure (equivalent to fitting separate + longitudinal and event models) (\code{"null"} or \code{NULL}) + } + More than one association structure can be specified, however, + not all possible combinations are allowed. + Note that for the lagged association structures baseline values (time = 0) + are used for the instances + where the time lag results in a time prior to baseline. When using the + \code{"etaauc"} or \code{"muauc"} association structures, the area under + the curve is evaluated using Gauss-Kronrod quadrature with 15 quadrature + nodes. By default, \code{"shared_b"} and \code{"shared_coef"} contribute + all random effects to the association structure; however, a subset of the + random effects can be chosen by specifying their indices between parentheses + as a suffix, for example, \code{"shared_b(1)"} or \code{"shared_b(1:3)"} or + \code{"shared_b(1,2,4)"}, and so on. \cr + \cr + In addition, several association terms (\code{"etavalue"}, \code{"etaslope"}, + \code{"muvalue"}, \code{"muslope"}) can be interacted with observed + data/covariates. To do this, use the association term's main handle plus a + suffix of \code{"_data"} then followed by the model matrix formula in + parentheses. For example if we had a variable in our dataset for gender + named \code{sex} then we might want to obtain different estimates for the + association between the current slope of the marker and the risk of the + event for each gender. To do this we would specify + \code{assoc = c("etaslope", "etaslope_data(~ sex)")}. \cr + \cr + It is also possible, when fitting a multivariate joint model, to include + interaction terms between the association terms themselves (this only + applies for interacting \code{"etavalue"} or \code{"muvalue"}). For example, + if we had a joint model with two longitudinal markers, we could specify + \code{assoc = list(c("etavalue", "etavalue_etavalue(2)"), "etavalue")}. + The first element of list says we want to use the value of the linear + predictor for the first marker, as well as it's interaction with the + value of the linear predictor for the second marker. The second element of + the list says we want to also include the expected value of the second marker + (i.e. as a "main effect"). Therefore, the linear predictor for the event + submodel would include the "main effects" for each marker as well as their + interaction. \cr + \cr + There are additional examples in the \strong{Examples} section below. + } +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") { +\donttest{ + +##### +# Univariate joint model, with association structure based on the +# current value of the linear predictor +f1 <- stan_jm(formulaLong = logBili ~ year + (1 | id), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + time_var = "year", + # this next line is only to keep the example small in size! + chains = 1, cores = 1, seed = 12345, iter = 1000) +print(f1) +summary(f1) + +##### +# Univariate joint model, with association structure based on the +# current value and slope of the linear predictor +f2 <- stan_jm(formulaLong = logBili ~ year + (year | id), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + assoc = c("etavalue", "etaslope"), + time_var = "year", + chains = 1, cores = 1, seed = 12345, iter = 1000) +print(f2) + +##### +# Univariate joint model, with association structure based on the +# lagged value of the linear predictor, where the lag is 2 time +# units (i.e. 2 years in this example) +f3 <- stan_jm(formulaLong = logBili ~ year + (1 | id), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + time_var = "year", + assoc = "etavalue", lag_assoc = 2, + chains = 1, cores = 1, seed = 12345, iter = 1000) +print(f3) + +##### +# Univariate joint model, where the association structure includes +# interactions with observed data. Here we specify that we want to use +# an association structure based on the current value of the linear +# predictor from the longitudinal submodel (i.e. "etavalue"), but we +# also want to interact this with the treatment covariate (trt) from +# pbcLong data frame, so that we can estimate a different association +# parameter (i.e. estimated effect of log serum bilirubin on the log +# hazard of death) for each treatment group +f4 <- stan_jm(formulaLong = logBili ~ year + (1 | id), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + time_var = "year", + assoc = c("etavalue", "etavalue_data(~ trt)"), + chains = 1, cores = 1, seed = 12345, iter = 1000) +print(f4) + +###### +# Multivariate joint model, with association structure based +# on the current value and slope of the linear predictor in the +# first longitudinal submodel and the area under the marker +# trajectory for the second longitudinal submodel +mv1 <- stan_jm( + formulaLong = list( + logBili ~ year + (1 | id), + albumin ~ sex + year + (year | id)), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + assoc = list(c("etavalue", "etaslope"), "etaauc"), + time_var = "year", + chains = 1, cores = 1, seed = 12345, iter = 100) +print(mv1) + +##### +# Multivariate joint model, where the association structure is formed by +# including the expected value of each longitudinal marker (logBili and +# albumin) in the linear predictor of the event submodel, as well as their +# interaction effect (i.e. the interaction between the two "etavalue" terms). +# Note that whether such an association structure based on a marker by +# marker interaction term makes sense will depend on the context of your +# application -- here we just show it for demostration purposes). +mv2 <- stan_jm( + formulaLong = list( + logBili ~ year + (1 | id), + albumin ~ sex + year + (year | id)), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + assoc = list(c("etavalue", "etavalue_etavalue(2)"), "etavalue"), + time_var = "year", + chains = 1, cores = 1, seed = 12345, iter = 100) + +##### +# Multivariate joint model, with one bernoulli marker and one +# Gaussian marker. We will artificially create the bernoulli +# marker by dichotomising log serum bilirubin +pbcLong$ybern <- as.integer(pbcLong$logBili >= mean(pbcLong$logBili)) +mv3 <- stan_jm( + formulaLong = list( + ybern ~ year + (1 | id), + albumin ~ sex + year + (year | id)), + dataLong = pbcLong, + formulaEvent = Surv(futimeYears, death) ~ sex + trt, + dataEvent = pbcSurv, + family = list(binomial, gaussian), + time_var = "year", + chains = 1, cores = 1, seed = 12345, iter = 1000) +} +} + +} +\seealso{ +\code{\link{stanreg-objects}}, \code{\link{stanmvreg-methods}}, + \code{\link{print.stanmvreg}}, \code{\link{summary.stanmvreg}}, + \code{\link{posterior_traj}}, \code{\link{posterior_survfit}}, + \code{\link{posterior_predict}}, \code{\link{posterior_interval}}, + \code{\link{pp_check}}, \code{\link{ps_check}}, \code{\link{stan_mvmer}}. +} diff --git a/man/stan_lm.Rd b/man/stan_lm.Rd new file mode 100644 index 000000000..d57aef724 --- /dev/null +++ b/man/stan_lm.Rd @@ -0,0 +1,224 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_aov.R, R/stan_lm.R, R/stan_lm.fit.R +\name{stan_aov} +\alias{stan_aov} +\alias{stan_lm} +\alias{stan_lm.wfit} +\alias{stan_lm.fit} +\title{Bayesian regularized linear models via Stan} +\usage{ +stan_aov( + formula, + data, + projections = FALSE, + contrasts = NULL, + ..., + prior = R2(stop("'location' must be specified")), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL +) + +stan_lm( + formula, + data, + subset, + weights, + na.action, + model = TRUE, + x = FALSE, + y = FALSE, + singular.ok = TRUE, + contrasts = NULL, + offset, + ..., + prior = R2(stop("'location' must be specified")), + prior_intercept = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL +) + +stan_lm.wfit( + x, + y, + w, + offset = NULL, + singular.ok = TRUE, + ..., + prior = R2(stop("'location' must be specified")), + prior_intercept = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL +) + +stan_lm.fit( + x, + y, + offset = NULL, + singular.ok = TRUE, + ..., + prior = R2(stop("'location' must be specified")), + prior_intercept = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL +) +} +\arguments{ +\item{formula, data, subset}{Same as \code{\link[stats]{lm}}, +but \emph{we strongly advise against omitting the \code{data} +argument}. Unless \code{data} is specified (and is a data frame) many +post-estimation functions (including \code{update}, \code{loo}, +\code{kfold}) are not guaranteed to work properly.} + +\item{projections}{For \code{stan_aov}, a logical scalar (defaulting to +\code{FALSE}) indicating whether \code{\link[stats]{proj}} should be called +on the fit.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{prior}{Must be a call to \code{\link{R2}} with its +\code{location} argument specified or \code{NULL}, which would +indicate a standard uniform prior for the \eqn{R^2}.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{na.action, singular.ok, contrasts}{Same as \code{\link[stats]{lm}}, but +rarely specified.} + +\item{model, offset, weights}{Same as \code{\link[stats]{lm}}, but +rarely specified.} + +\item{x, y}{In \code{stan_lm, stan_aov}, logical scalars indicating whether to +return the design matrix and response vector. In \code{stan_lm.fit or stan_lm.wfit}, +a design matrix and response vector.} + +\item{prior_intercept}{Either \code{NULL} (the default) or a call to +\code{\link{normal}}. If a \code{\link{normal}} prior is specified +without a \code{scale}, then the standard deviation is taken to be +the marginal standard deviation of the outcome divided by the square +root of the sample size, which is legitimate because the marginal +standard deviation of the outcome is a primitive parameter being +estimated. + +\strong{Note:} If using a dense representation of the design matrix +---i.e., if the \code{sparse} argument is left at its default value of +\code{FALSE}--- then the prior distribution for the intercept is set so it +applies to the value \emph{when all predictors are centered}. If you prefer +to specify a prior on the intercept without the predictors being +auto-centered, then you have to omit the intercept from the +\code{\link[stats]{formula}} and include a column of ones as a predictor, +in which case some element of \code{prior} specifies the prior on it, +rather than \code{prior_intercept}. Regardless of how +\code{prior_intercept} is specified, the reported \emph{estimates} of the +intercept always correspond to a parameterization without centered +predictors (i.e., same as in \code{glm}).} + +\item{w}{Same as in \code{lm.wfit} but rarely specified.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_lm, stan_aov}. + +A \link[=stanfit-class]{stanfit} object (or a slightly modified + stanfit object) is returned if \code{stan_lm.fit or stan_lm.wfit} is called directly. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for linear modeling with 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. See +\code{\link{priors}} for an explanation of this critical point. +\code{\link{stan_glm}} with \code{family="gaussian"} also estimates a linear +model with normally-distributed errors and allows for various other priors on +the coefficients. +} +\details{ +The \code{stan_lm} function is similar in syntax to the + \code{\link[stats]{lm}} function but rather than choosing the parameters to + minimize the sum of squared residuals, samples from the posterior + distribution are drawn using MCMC (if \code{algorithm} is + \code{"sampling"}). The \code{stan_lm} function has a formula-based + interface and would usually be called by users but the \code{stan_lm.fit} + and \code{stan_lm.wfit} functions might be called by other functions that + parse the data themselves and are analogous to \code{lm.fit} + and \code{lm.wfit} respectively. + + In addition to estimating \code{sigma} --- the standard deviation of the + normally-distributed errors --- this model estimates a positive parameter + called \code{log-fit_ratio}. If it is positive, the marginal posterior + variance of the outcome will exceed the sample variance of the outcome + by a multiplicative factor equal to the square of \code{fit_ratio}. + Conversely if \code{log-fit_ratio} is negative, then the model underfits. + Given the regularizing nature of the priors, a slight underfit is good. + + Finally, the posterior predictive distribution is generated with the + predictors fixed at their sample means. This quantity is useful for + checking convergence because it is reasonably normally distributed + and a function of all the parameters in the model. + + The \code{stan_aov} function is similar to \code{\link[stats]{aov}}, but + does a Bayesian analysis of variance that is basically equivalent to + \code{stan_lm} with dummy variables. \code{stan_aov} has a somewhat + customized \code{\link{print}} method that prints an ANOVA-like table in + addition to the output printed for \code{stan_lm} models. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +\donttest{ +op <- options(contrasts = c("contr.helmert", "contr.poly")) +fit_aov <- stan_aov(yield ~ block + N*P*K, data = npk, + prior = R2(0.5), seed = 12345) +options(op) +print(fit_aov) +} +} +if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") { +(fit <- stan_lm(mpg ~ wt + qsec + am, data = mtcars, prior = R2(0.75), + # the next line is only to make the example go fast enough + chains = 1, iter = 300, seed = 12345, refresh = 0)) +plot(fit, "hist", pars = c("wt", "am", "qsec", "sigma"), + transformations = list(sigma = "log")) +} +} +\references{ +Lewandowski, D., Kurowicka D., and Joe, H. (2009). Generating random +correlation matrices based on vines and extended onion method. +\emph{Journal of Multivariate Analysis}. \strong{100}(9), 1989--2001. +} +\seealso{ +The vignettes for \code{stan_lm} and \code{stan_aov}, which have more +thorough descriptions and examples. +\url{https://mc-stan.org/rstanarm/articles/} + +Also see \code{\link{stan_glm}}, which --- if \code{family = +gaussian(link="identity")} --- also estimates a linear model with +normally-distributed errors but specifies different priors. +} diff --git a/man/stan_mvmer.Rd b/man/stan_mvmer.Rd new file mode 100644 index 000000000..78b7306d9 --- /dev/null +++ b/man/stan_mvmer.Rd @@ -0,0 +1,189 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_mvmer.R +\name{stan_mvmer} +\alias{stan_mvmer} +\title{Bayesian multivariate generalized linear models with correlated +group-specific terms via Stan} +\usage{ +stan_mvmer( + formula, + data, + family = gaussian, + weights, + prior = normal(autoscale = TRUE), + prior_intercept = normal(autoscale = TRUE), + prior_aux = cauchy(0, 5, autoscale = TRUE), + prior_covariance = lkj(autoscale = TRUE), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + max_treedepth = 10L, + init = "random", + QR = FALSE, + sparse = FALSE, + ... +) +} +\arguments{ +\item{formula}{A two-sided linear formula object describing both the +fixed-effects and random-effects parts of the longitudinal submodel +similar in vein to formula specification in the \strong{lme4} package +(see \code{\link[lme4]{glmer}} or the \strong{lme4} vignette for details). +Note however that the double bar (\code{||}) notation is not allowed +when specifying the random-effects parts of the formula, and neither +are nested grouping factors (e.g. \code{(1 | g1/g2))} or +\code{(1 | g1:g2)}, where \code{g1}, \code{g2} are grouping factors. +For a multivariate GLM this should be a list of such formula objects, +with each element of the list providing the formula for one of the +GLM submodels.} + +\item{data}{A data frame containing the variables specified in +\code{formula}. For a multivariate GLM, this can +be either a single data frame which contains the data for all +GLM submodels, or it can be a list of data frames where each +element of the list provides the data for one of the GLM submodels.} + +\item{family}{The family (and possibly also the link function) for the +GLM submodel(s). See \code{\link[lme4]{glmer}} for details. +If fitting a multivariate GLM, then this can optionally be a +list of families, in which case each element of the list specifies the +family for one of the GLM submodels. In other words, a different family +can be specified for each GLM submodel.} + +\item{weights}{Same as in \code{\link[stats]{glm}}, +except that when fitting a multivariate GLM and a list of data frames +is provided in \code{data} then a corresponding list of weights +must be provided. If weights are +provided for one of the GLM submodels, then they must be provided for +all GLM submodels.} + +\item{prior, prior_intercept, prior_aux}{Same as in \code{\link{stan_glmer}} +except that for a multivariate GLM a list of priors can be provided for +any of \code{prior}, \code{prior_intercept} or \code{prior_aux} arguments. +That is, different priors can optionally be specified for each of the GLM +submodels. If a list is not provided, then the same prior distributions are +used for each GLM submodel. Note that the \code{"product_normal"} prior is +not allowed for \code{stan_mvmer}.} + +\item{prior_covariance}{Cannot be \code{NULL}; see \code{\link{priors}} for +more information about the prior distributions on covariance matrices. +Note however that the default prior for covariance matrices in +\code{stan_mvmer} is slightly different to that in \code{\link{stan_glmer}} +(the details of which are described on the \code{\link{priors}} page).} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{max_treedepth}{A positive integer specifying the maximum treedepth +for the non-U-turn sampler. See the \code{control} argument in +\code{\link[rstan]{stan}}.} + +\item{init}{The method for generating initial values. See +\code{\link[rstan]{stan}}.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} +} +\value{ +A \link[=stanreg-objects]{stanmvreg} object is returned. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for multivariate GLMs with group-specific coefficients +that are assumed to be correlated across the GLM submodels. +} +\details{ +The \code{stan_mvmer} function can be used to fit a multivariate + generalized linear model (GLM) with group-specific terms. The model consists + of distinct GLM submodels, each which contains group-specific terms; within + a grouping factor (for example, patient ID) the grouping-specific terms are + assumed to be correlated across the different GLM submodels. It is + possible to specify a different outcome type (for example a different + family and/or link function) for each of the GLM submodels. \cr + \cr + Bayesian estimation of the model is performed via MCMC, in the same way as + for \code{\link{stan_glmer}}. Also, similar to \code{\link{stan_glmer}}, + an unstructured covariance matrix is used for the group-specific terms + within a given grouping factor, with priors on the terms of a decomposition + of the covariance matrix.See \code{\link{priors}} for more information about + the priors distributions that are available for the covariance matrices, + the regression coefficients and the intercept and auxiliary parameters. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") { +\donttest{ +##### +# A multivariate GLM with two submodels. For the grouping factor 'id', the +# group-specific intercept from the first submodel (logBili) is assumed to +# be correlated with the group-specific intercept and linear slope in the +# second submodel (albumin) +f1 <- stan_mvmer( + formula = list( + logBili ~ year + (1 | id), + albumin ~ sex + year + (year | id)), + data = pbcLong, + # this next line is only to keep the example small in size! + chains = 1, cores = 1, seed = 12345, iter = 1000) +summary(f1) + +##### +# A multivariate GLM with one bernoulli outcome and one +# gaussian outcome. We will artificially create the bernoulli +# outcome by dichotomising log serum bilirubin +pbcLong$ybern <- as.integer(pbcLong$logBili >= mean(pbcLong$logBili)) +f2 <- stan_mvmer( + formula = list( + ybern ~ year + (1 | id), + albumin ~ sex + year + (year | id)), + data = pbcLong, + family = list(binomial, gaussian), + chains = 1, cores = 1, seed = 12345, iter = 1000) +} +} +} +\seealso{ +\code{\link{stan_glmer}}, \code{\link{stan_jm}}, + \code{\link{stanreg-objects}}, \code{\link{stanmvreg-methods}}, + \code{\link{print.stanmvreg}}, \code{\link{summary.stanmvreg}}, + \code{\link{posterior_predict}}, \code{\link{posterior_interval}}. +} diff --git a/man/stan_nlmer.Rd b/man/stan_nlmer.Rd new file mode 100644 index 000000000..866757f46 --- /dev/null +++ b/man/stan_nlmer.Rd @@ -0,0 +1,199 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_nlmer.R +\name{stan_nlmer} +\alias{stan_nlmer} +\title{Bayesian nonlinear models with group-specific terms via Stan} +\usage{ +stan_nlmer( + formula, + data = NULL, + subset, + weights, + na.action, + offset, + contrasts = NULL, + ..., + prior = normal(autoscale = TRUE), + prior_aux = exponential(autoscale = TRUE), + prior_covariance = decov(), + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + QR = FALSE, + sparse = FALSE +) +} +\arguments{ +\item{formula, data}{Same as for \code{\link[lme4]{nlmer}}. \emph{We strongly +advise against omitting the \code{data} argument}. Unless \code{data} is +specified (and is a data frame) many post-estimation functions (including +\code{update}, \code{loo}, \code{kfold}) are not guaranteed to work +properly.} + +\item{subset, weights, offset}{Same as \code{\link[stats]{glm}}.} + +\item{na.action, contrasts}{Same as \code{\link[stats]{glm}}, but rarely +specified.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{prior}{The prior distribution for the (non-hierarchical) regression +coefficients. + +The default priors are described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior} should be a call to one of the +various functions provided by \pkg{rstanarm} for specifying priors. The +subset of these functions that can be used for the prior on the +coefficients can be grouped into several "families": + +\tabular{ll}{ + \strong{Family} \tab \strong{Functions} \cr + \emph{Student t family} \tab \code{normal}, \code{student_t}, \code{cauchy} \cr + \emph{Hierarchical shrinkage family} \tab \code{hs}, \code{hs_plus} \cr + \emph{Laplace family} \tab \code{laplace}, \code{lasso} \cr + \emph{Product normal family} \tab \code{product_normal} \cr +} + +See the \link[=priors]{priors help page} for details on the families and +how to specify the arguments for all of the functions in the table above. +To omit a prior ---i.e., to use a flat (improper) uniform prior--- +\code{prior} can be set to \code{NULL}, although this is rarely a good +idea. + +\strong{Note:} Unless \code{QR=TRUE}, if \code{prior} is from the Student t +family or Laplace family, and if the \code{autoscale} argument to the +function used to specify the prior (e.g. \code{\link{normal}}) is left at +its default and recommended value of \code{TRUE}, then the default or +user-specified prior scale(s) may be adjusted internally based on the +scales of the predictors. See the \link[=priors]{priors help page} and the +\emph{Prior Distributions} vignette for details on the rescaling and the +\code{\link{prior_summary}} function for a summary of the priors used for a +particular model.} + +\item{prior_aux}{The prior distribution for the "auxiliary" parameter (if +applicable). The "auxiliary" parameter refers to a different parameter +depending on the \code{family}. For Gaussian models \code{prior_aux} +controls \code{"sigma"}, the error +standard deviation. For negative binomial models \code{prior_aux} controls +\code{"reciprocal_dispersion"}, which is similar to the +\code{"size"} parameter of \code{\link[stats:NegBinomial]{rnbinom}}: +smaller values of \code{"reciprocal_dispersion"} correspond to +greater dispersion. For gamma models \code{prior_aux} sets the prior on +to the \code{"shape"} parameter (see e.g., +\code{\link[stats:GammaDist]{rgamma}}), and for inverse-Gaussian models it is the +so-called \code{"lambda"} parameter (which is essentially the reciprocal of +a scale parameter). Binomial and Poisson models do not have auxiliary +parameters. + +The default prior is described in the vignette +\href{https://mc-stan.org/rstanarm/articles/priors.html}{\emph{Prior +Distributions for rstanarm Models}}. +If not using the default, \code{prior_aux} can be a call to +\code{exponential} to use an exponential distribution, or \code{normal}, +\code{student_t} or \code{cauchy}, which results in a half-normal, half-t, +or half-Cauchy prior. See \code{\link{priors}} for details on these +functions. To omit a prior ---i.e., to use a flat (improper) uniform +prior--- set \code{prior_aux} to \code{NULL}.} + +\item{prior_covariance}{Cannot be \code{NULL}; see \code{\link{decov}} for +more information about the default arguments.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{QR}{A logical scalar defaulting to \code{FALSE}, but if \code{TRUE} +applies a scaled \code{\link{qr}} decomposition to the design matrix. The +transformation does not change the likelihood of the data but is +recommended for computational reasons when there are multiple predictors. +See the \link{QR-argument} documentation page for details on how +\pkg{rstanarm} does the transformation and important information about how +to interpret the prior distributions of the model parameters when using +\code{QR=TRUE}.} + +\item{sparse}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to use a sparse representation of the design (X) matrix. +If \code{TRUE}, the the design matrix is not centered (since that would +destroy the sparsity) and likewise it is not possible to specify both +\code{QR = TRUE} and \code{sparse = TRUE}. Depending on how many zeros +there are in the design matrix, setting \code{sparse = TRUE} may make +the code run faster and can consume much less RAM.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_nlmer}. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for NLMMs with group-specific coefficients that have +unknown covariance matrices with flexible priors. +} +\details{ +The \code{stan_nlmer} function is similar in syntax to + \code{\link[lme4]{nlmer}} but rather than performing (approximate) maximum + marginal likelihood estimation, Bayesian estimation is by default performed + via MCMC. The Bayesian model adds independent priors on the "coefficients" + --- which are really intercepts --- in the same way as + \code{\link{stan_nlmer}} and priors on the terms of a decomposition of the + covariance matrices of the group-specific parameters. See + \code{\link{priors}} for more information about the priors. + + The supported transformation functions are limited to the named + "self-starting" functions in the \pkg{stats} library: + \code{\link[stats]{SSasymp}}, \code{\link[stats]{SSasympOff}}, + \code{\link[stats]{SSasympOrig}}, \code{\link[stats]{SSbiexp}}, + \code{\link[stats]{SSfol}}, \code{\link[stats]{SSfpl}}, + \code{\link[stats]{SSgompertz}}, \code{\link[stats]{SSlogis}}, + \code{\link[stats]{SSmicmen}}, and \code{\link[stats]{SSweibull}}. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") { +\donttest{ +data("Orange", package = "datasets") +Orange$circumference <- Orange$circumference / 100 +Orange$age <- Orange$age / 100 +fit <- stan_nlmer( + circumference ~ SSlogis(age, Asym, xmid, scal) ~ Asym|Tree, + data = Orange, + # for speed only + chains = 1, + iter = 1000 + ) +print(fit) +posterior_interval(fit) +plot(fit, regex_pars = "b\\\\[") +} +} +} +\seealso{ +\code{\link{stanreg-methods}} and +\code{\link[lme4]{nlmer}}. + +The vignette for \code{stan_glmer}, which also discusses + \code{stan_nlmer} models. \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stan_polr.Rd b/man/stan_polr.Rd new file mode 100644 index 000000000..c35173604 --- /dev/null +++ b/man/stan_polr.Rd @@ -0,0 +1,203 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stan_polr.R, R/stan_polr.fit.R +\name{stan_polr} +\alias{stan_polr} +\alias{stan_polr.fit} +\title{Bayesian ordinal regression models via Stan} +\usage{ +stan_polr( + formula, + data, + weights, + ..., + subset, + na.action = getOption("na.action", "na.omit"), + contrasts = NULL, + model = TRUE, + method = c("logistic", "probit", "loglog", "cloglog", "cauchit"), + prior = R2(stop("'location' must be specified")), + prior_counts = dirichlet(1), + shape = NULL, + rate = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + do_residuals = NULL +) + +stan_polr.fit( + x, + y, + wt = NULL, + offset = NULL, + method = c("logistic", "probit", "loglog", "cloglog", "cauchit"), + ..., + prior = R2(stop("'location' must be specified")), + prior_counts = dirichlet(1), + shape = NULL, + rate = NULL, + prior_PD = FALSE, + algorithm = c("sampling", "meanfield", "fullrank"), + adapt_delta = NULL, + do_residuals = algorithm == "sampling" +) +} +\arguments{ +\item{formula, data, subset}{Same as \code{\link[MASS]{polr}}, +but \emph{we strongly advise against omitting the \code{data} +argument}. Unless \code{data} is specified (and is a data frame) many +post-estimation functions (including \code{update}, \code{loo}, +\code{kfold}) are not guaranteed to work properly.} + +\item{weights, na.action, contrasts, model}{Same as \code{\link[MASS]{polr}}, but +rarely specified.} + +\item{...}{Further arguments passed to the function in the \pkg{rstan} +package (\code{\link[rstan:stanmodel-method-sampling]{sampling}}, +\code{\link[rstan:stanmodel-method-vb]{vb}}, or +\code{\link[rstan:stanmodel-method-optimizing]{optimizing}}), +corresponding to the estimation method named by \code{algorithm}. For example, +if \code{algorithm} is \code{"sampling"} it is possible to specify \code{iter}, +\code{chains}, \code{cores}, and other MCMC controls. + +Another useful argument that can be passed to \pkg{rstan} via \code{...} is +\code{refresh}, which specifies how often to print updates when sampling +(i.e., show the progress every \code{refresh} iterations). \code{refresh=0} +turns off the iteration updates.} + +\item{method}{One of 'logistic', 'probit', 'loglog', 'cloglog' or 'cauchit', +but can be abbreviated. See \code{\link[MASS]{polr}} for more details.} + +\item{prior}{Prior for coefficients. Should be a call to \code{\link{R2}} +to specify the prior location of the \eqn{R^2} but can be \code{NULL} +to indicate a standard uniform prior. See \code{\link{priors}}.} + +\item{prior_counts}{A call to \code{\link{dirichlet}} to specify the +prior counts of the outcome when the predictors are at their sample +means.} + +\item{shape}{Either \code{NULL} or a positive scalar that is interpreted +as the shape parameter for a \code{\link[stats]{GammaDist}}ribution on +the exponent applied to the probability of success when there are only +two outcome categories. If \code{NULL}, which is the default, then the +exponent is taken to be fixed at \eqn{1}.} + +\item{rate}{Either \code{NULL} or a positive scalar that is interpreted +as the rate parameter for a \code{\link[stats]{GammaDist}}ribution on +the exponent applied to the probability of success when there are only +two outcome categories. If \code{NULL}, which is the default, then the +exponent is taken to be fixed at \eqn{1}.} + +\item{prior_PD}{A logical scalar (defaulting to \code{FALSE}) indicating +whether to draw from the prior predictive distribution instead of +conditioning on the outcome.} + +\item{algorithm}{A string (possibly abbreviated) indicating the +estimation approach to use. Can be \code{"sampling"} for MCMC (the +default), \code{"optimizing"} for optimization, \code{"meanfield"} for +variational inference with independent normal distributions, or +\code{"fullrank"} for variational inference with a multivariate normal +distribution. See \code{\link{rstanarm-package}} for more details on the +estimation algorithms. NOTE: not all fitting functions support all four +algorithms.} + +\item{adapt_delta}{Only relevant if \code{algorithm="sampling"}. See +the \link{adapt_delta} help page for details.} + +\item{do_residuals}{A logical scalar indicating whether or not to +automatically calculate fit residuals after sampling completes. Defaults to +\code{TRUE} if and only if \code{algorithm="sampling"}. Setting +\code{do_residuals=FALSE} is only useful in the somewhat rare case that +\code{stan_polr} appears to finish sampling but hangs instead of returning +the fitted model object.} + +\item{x}{A design matrix.} + +\item{y}{A response variable, which must be a (preferably ordered) factor.} + +\item{wt}{A numeric vector (possibly \code{NULL}) of observation weights.} + +\item{offset}{A numeric vector (possibly \code{NULL}) of offsets.} +} +\value{ +A \link[=stanreg-objects]{stanreg} object is returned +for \code{stan_polr}. + +A \link[=stanfit-class]{stanfit} object (or a slightly modified + stanfit object) is returned if \code{stan_polr.fit} is called directly. +} +\description{ +\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}} +Bayesian inference for ordinal (or binary) regression models under a +proportional odds assumption. +} +\details{ +The \code{stan_polr} function is similar in syntax to + \code{\link[MASS]{polr}} but rather than performing maximum likelihood + estimation of a proportional odds model, Bayesian estimation is performed + (if \code{algorithm = "sampling"}) via MCMC. The \code{stan_polr} + function calls the workhorse \code{stan_polr.fit} function, but it is + possible to call the latter directly. + + As for \code{\link{stan_lm}}, it is necessary to specify the prior + location of \eqn{R^2}. In this case, the \eqn{R^2} pertains to the + proportion of variance in the latent variable (which is discretized + by the cutpoints) attributable to the predictors in the model. + + Prior beliefs about the cutpoints are governed by prior beliefs about the + outcome when the predictors are at their sample means. Both of these + are explained in the help page on \code{\link{priors}} and in the + \pkg{rstanarm} vignettes. + + Unlike \code{\link[MASS]{polr}}, \code{stan_polr} also allows the "ordinal" + outcome to contain only two levels, in which case the likelihood is the + same by default as for \code{\link{stan_glm}} with \code{family = binomial} + but the prior on the coefficients is different. However, \code{stan_polr} + allows the user to specify the \code{shape} and \code{rate} hyperparameters, + in which case the probability of success is defined as the logistic CDF of + the linear predictor, raised to the power of \code{alpha} where \code{alpha} + has a gamma prior with the specified \code{shape} and \code{rate}. This + likelihood is called \dQuote{scobit} by Nagler (1994) because if \code{alpha} + is not equal to \eqn{1}, then the relationship between the linear predictor + and the probability of success is skewed. If \code{shape} or \code{rate} is + \code{NULL}, then \code{alpha} is assumed to be fixed to \eqn{1}. + + Otherwise, it is usually advisible to set \code{shape} and \code{rate} to + the same number so that the expected value of \code{alpha} is \eqn{1} while + leaving open the possibility that \code{alpha} may depart from \eqn{1} a + little bit. It is often necessary to have a lot of data in order to estimate + \code{alpha} with much precision and always necessary to inspect the + Pareto shape parameters calculated by \code{\link{loo}} to see if the + results are particularly sensitive to individual observations. + + Users should think carefully about how the outcome is coded when using + a scobit-type model. When \code{alpha} is not \eqn{1}, the asymmetry + implies that the probability of success is most sensitive to the predictors + when the probability of success is less than \eqn{0.63}. Reversing the + coding of the successes and failures allows the predictors to have the + greatest impact when the probability of failure is less than \eqn{0.63}. + Also, the gamma prior on \code{alpha} is positively skewed, but you + can reverse the coding of the successes and failures to circumvent this + property. +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386") { + fit <- stan_polr(tobgp ~ agegp, data = esoph, method = "probit", + prior = R2(0.2, "mean"), init_r = 0.1, seed = 12345, + algorithm = "fullrank") # for speed only + print(fit) + plot(fit) +} + +} +\references{ +Nagler, J., (1994). Scobit: An Alternative Estimator to Logit and Probit. +\emph{American Journal of Political Science}. 230 -- 255. +} +\seealso{ +\code{\link{stanreg-methods}} and +\code{\link[MASS]{polr}}. + +The vignette for \code{stan_polr}. + \url{https://mc-stan.org/rstanarm/articles/} +} diff --git a/man/stanmvreg-methods.Rd b/man/stanmvreg-methods.Rd new file mode 100644 index 000000000..5d32a1612 --- /dev/null +++ b/man/stanmvreg-methods.Rd @@ -0,0 +1,149 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanmvreg-methods.R +\name{stanmvreg-methods} +\alias{stanmvreg-methods} +\alias{coef.stanmvreg} +\alias{fitted.stanmvreg} +\alias{residuals.stanmvreg} +\alias{se.stanmvreg} +\alias{formula.stanmvreg} +\alias{update.stanmvreg} +\alias{update.stanjm} +\alias{fixef.stanmvreg} +\alias{ngrps.stanmvreg} +\alias{ranef.stanmvreg} +\alias{sigma.stanmvreg} +\title{Methods for stanmvreg objects} +\usage{ +\method{coef}{stanmvreg}(object, m = NULL, ...) + +\method{fitted}{stanmvreg}(object, m = NULL, ...) + +\method{residuals}{stanmvreg}(object, m = NULL, ...) + +\method{se}{stanmvreg}(object, m = NULL, ...) + +\method{formula}{stanmvreg}(x, fixed.only = FALSE, random.only = FALSE, m = NULL, ...) + +\method{update}{stanmvreg}(object, formula., ..., evaluate = TRUE) + +\method{update}{stanjm}(object, formulaLong., formulaEvent., ..., evaluate = TRUE) + +\method{fixef}{stanmvreg}(object, m = NULL, remove_stub = TRUE, ...) + +\method{ngrps}{stanmvreg}(object, ...) + +\method{ranef}{stanmvreg}(object, m = NULL, ...) + +\method{sigma}{stanmvreg}(object, m = NULL, ...) +} +\arguments{ +\item{object, x}{A fitted model object returned by one of the +multivariate \pkg{rstanarm} modelling functions. See +\code{\link{stanreg-objects}}.} + +\item{m}{Integer specifying the number or name of the submodel} + +\item{...}{Ignored, except by the \code{update} method. See +\code{\link{update}}.} + +\item{fixed.only}{A logical specifying whether to only retain the fixed effect +part of the longitudinal submodel formulas} + +\item{random.only}{A logical specifying whether to only retain the random effect +part of the longitudinal submodel formulas} + +\item{formula.}{An updated formula for the model. For a multivariate model +\code{formula.} should be a list of formulas, as described for the +\code{formula} argument in \code{\link{stan_mvmer}}.} + +\item{evaluate}{See \code{\link[stats]{update}}.} + +\item{formulaLong., formulaEvent.}{An updated formula for the longitudinal +or event submodel, when \code{object} was estimated using +\code{\link{stan_jm}}. For a multivariate joint model \code{formulaLong.} +should be a list of formulas, as described for the \code{formulaLong} +argument in \code{\link{stan_jm}}.} + +\item{remove_stub}{Logical specifying whether to remove the string identifying +the submodel (e.g. \code{y1|}, \code{y2|}, \code{Long1|}, \code{Long2|}, +\code{Event|}) from each of the parameter names.} +} +\description{ +S3 methods for \link[=stanreg-objects]{stanmvreg} objects. There are also +several methods (listed in \strong{See Also}, below) with their own +individual help pages. +The main difference between these methods and the +\link[=stanreg-methods]{stanreg} methods is that the methods described here +generally include an additional argument \code{m} which allows the user to +specify which submodel they wish to return the result for. If the argument +\code{m} is set to \code{NULL} then the result will generally be a named list +with each element of the list containing the result for one of the submodels. +} +\details{ +Most of these methods are similar to the methods defined for objects + of class 'lm', 'glm', 'glmer', etc. However there are a few exceptions: + +\describe{ +\item{\code{coef}}{ +Medians are used for point estimates. See the \emph{Point estimates} section +in \code{\link{print.stanmvreg}} for more details. \code{coef} returns a list +equal to the length of the number of submodels. The first +elements of the list are the coefficients from each of the fitted longitudinal +submodels and are the same layout as those returned by \code{coef} method of the +\pkg{lme4} package, that is, the sum of the random and fixed effects coefficients +for each explanatory variable for each level of each grouping factor. The final +element of the returned list is a vector of fixed effect coefficients from the +event submodel. +} +\item{\code{se}}{ +The \code{se} function returns standard errors based on +\code{\link{mad}}. See the \emph{Uncertainty estimates} section in +\code{\link{print.stanmvreg}} for more details. +} +\item{\code{confint}}{ +Not supplied, since the \code{\link{posterior_interval}} function should +be used instead to compute Bayesian uncertainty intervals. +} +\item{\code{residuals}}{ +Residuals are \emph{always} of type \code{"response"} (not \code{"deviance"} +residuals or any other type). +} +} +} +\seealso{ +\itemize{ + \item The \code{\link[=print.stanmvreg]{print}}, + \code{\link[=summary.stanmvreg]{summary}}, and \code{\link{prior_summary}} + methods for \code{stanmvreg} objects for information on the fitted model. + \item The \code{\link[=plot.stanreg]{plot}} method to plot estimates and + diagnostics. + \item The \code{\link{pp_check}} method for graphical posterior predictive + checking of the longitudinal or glmer submodels. + \item The \code{\link{ps_check}} method for graphical posterior predictive + checking of the event submodel. + \item The \code{\link{posterior_traj}} for predictions for the longitudinal + submodel (for models estimated using \code{\link{stan_jm}}), as well as + it's associated \code{\link[=plot.predict.stanjm]{plot}} method. + \item The \code{\link{posterior_survfit}} for predictions for the event + submodel, including so-called "dynamic" predictions (for models estimated + using \code{\link{stan_jm}}), as well as + it's associated \code{\link[=plot.survfit.stanjm]{plot}} method. + \item The \code{\link{posterior_predict}} for predictions for the glmer + submodel (for models estimated using \code{\link{stan_mvmer}}). + \item The \code{\link{posterior_interval}} for uncertainty intervals for + model parameters. + \item The \code{\link[=loo.stanreg]{loo}}, + and \code{\link[=log_lik.stanmvreg]{log_lik}} methods for leave-one-out + model comparison, and computing the log-likelihood of (possibly new) data. + \item The \code{\link[=as.matrix.stanreg]{as.matrix}}, \code{as.data.frame}, + and \code{as.array} methods to access posterior draws. +} + +Other S3 methods for stanmvreg objects, which have separate documentation, +including \code{\link{print.stanmvreg}}, and \code{\link{summary.stanmvreg}}. + +Also \code{\link{posterior_interval}} for an alternative to \code{confint}, +and \code{posterior_predict}, \code{posterior_traj} and +\code{posterior_survfit} for predictions based on the fitted joint model. +} diff --git a/man/stanreg-draws-formats.Rd b/man/stanreg-draws-formats.Rd new file mode 100644 index 000000000..508a6146b --- /dev/null +++ b/man/stanreg-draws-formats.Rd @@ -0,0 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/draws.R +\name{stanreg-draws-formats} +\alias{stanreg-draws-formats} +\alias{as_draws} +\alias{as_draws_matrix} +\alias{as_draws_array} +\alias{as_draws_df} +\alias{as_draws_rvars} +\alias{as_draws_list} +\alias{as_draws.stanreg} +\alias{as_draws_matrix.stanreg} +\alias{as_draws_array.stanreg} +\alias{as_draws_df.stanreg} +\alias{as_draws_list.stanreg} +\alias{as_draws_rvars.stanreg} +\title{Create a \code{draws} object from a \code{stanreg} object} +\usage{ +\method{as_draws}{stanreg}(x, ...) + +\method{as_draws_matrix}{stanreg}(x, ...) + +\method{as_draws_array}{stanreg}(x, ...) + +\method{as_draws_df}{stanreg}(x, ...) + +\method{as_draws_list}{stanreg}(x, ...) + +\method{as_draws_rvars}{stanreg}(x, ...) +} +\arguments{ +\item{x}{A \code{stanreg} object returned by one of the \pkg{rstanarm} +modeling functions.} + +\item{...}{Arguments (e.g., \code{pars}, \code{regex_pars}) passed internally to +\code{\link{as.matrix.stanreg}} or \code{as.array.stanreg}.} +} +\value{ +A \code{draws} object from the + \pkg{\link[posterior:posterior-package]{posterior}} package. See the + \pkg{posterior} package documentation and vignettes for details on working + with these objects. +} +\description{ +Convert a \code{stanreg} object to a format supported by the +\pkg{\link[posterior:posterior-package]{posterior}} package. +} +\details{ +To subset iterations, chains, or draws, use + \code{\link[posterior:subset_draws]{subset_draws}} after making the + \code{draws} object. To subset variables use \code{...} to pass the \code{pars} + and/or \code{regex_pars} arguments to \code{as.matrix.stanreg} or + \code{as.array.stanreg} (these are called internally by + \code{as_draws.stanreg}), or use + \code{\link[posterior:subset_draws]{subset_draws}} after making the + \code{draws} object. +} +\examples{ +fit <- stan_glm(mpg ~ wt + as.factor(cyl), data = mtcars) +as_draws_matrix(fit) # matrix format combines all chains +as_draws_df(fit, regex_pars = "cyl") +posterior::summarize_draws(as_draws_array(fit)) + +} diff --git a/man/stanreg-methods.Rd b/man/stanreg-methods.Rd new file mode 100644 index 000000000..7a68e837e --- /dev/null +++ b/man/stanreg-methods.Rd @@ -0,0 +1,141 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanmvreg-methods.R, R/stanreg-methods.R +\name{nobs.stanmvreg} +\alias{nobs.stanmvreg} +\alias{stanreg-methods} +\alias{VarCorr} +\alias{fixef} +\alias{ranef} +\alias{ngrps} +\alias{sigma} +\alias{nsamples} +\alias{coef.stanreg} +\alias{confint.stanreg} +\alias{fitted.stanreg} +\alias{nobs.stanreg} +\alias{residuals.stanreg} +\alias{se.stanreg} +\alias{update.stanreg} +\alias{vcov.stanreg} +\alias{fixef.stanreg} +\alias{ngrps.stanreg} +\alias{nsamples.stanreg} +\alias{ranef.stanreg} +\alias{sigma.stanreg} +\alias{VarCorr.stanreg} +\title{Methods for stanreg objects} +\usage{ +\method{nobs}{stanmvreg}(object, ...) + +\method{coef}{stanreg}(object, ...) + +\method{confint}{stanreg}(object, parm, level = 0.95, ...) + +\method{fitted}{stanreg}(object, ...) + +\method{nobs}{stanreg}(object, ...) + +\method{residuals}{stanreg}(object, ...) + +\method{se}{stanreg}(object, ...) + +\method{update}{stanreg}(object, formula., ..., evaluate = TRUE) + +\method{vcov}{stanreg}(object, correlation = FALSE, ...) + +\method{fixef}{stanreg}(object, ...) + +\method{ngrps}{stanreg}(object, ...) + +\method{nsamples}{stanreg}(object, ...) + +\method{ranef}{stanreg}(object, ...) + +\method{sigma}{stanreg}(object, ...) + +\method{VarCorr}{stanreg}(x, sigma = 1, ...) +} +\arguments{ +\item{object, x}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{...}{Ignored, except by the \code{update} method. See +\code{\link{update}}.} + +\item{parm}{For \code{confint}, an optional character vector of parameter +names.} + +\item{level}{For \code{confint}, a scalar between \eqn{0} and \eqn{1} +indicating the confidence level to use.} + +\item{formula., evaluate}{See \code{\link[stats]{update}}.} + +\item{correlation}{For \code{vcov}, if \code{FALSE} (the default) the +covariance matrix is returned. If \code{TRUE}, the correlation matrix is +returned instead.} + +\item{sigma}{Ignored (included for compatibility with +\code{\link[nlme]{VarCorr}}).} +} +\description{ +The methods documented on this page are actually some of the least important +methods defined for \link[=stanreg-objects]{stanreg} objects. The most +important methods are documented separately, each with its own page. Links to +those pages are provided in the \strong{See Also} section, below. +} +\details{ +The methods documented on this page are similar to the methods + defined for objects of class 'lm', 'glm', 'glmer', etc. However there are a + few key differences: + +\describe{ +\item{\code{residuals}}{ +Residuals are \emph{always} of type \code{"response"} (not \code{"deviance"} +residuals or any other type). However, in the case of \code{\link{stan_polr}} +with more than two response categories, the residuals are the difference +between the latent utility and its linear predictor. +} +\item{\code{coef}}{ +Medians are used for point estimates. See the \emph{Point estimates} section +in \code{\link{print.stanreg}} for more details. +} +\item{\code{se}}{ +The \code{se} function returns standard errors based on +\code{\link{mad}}. See the \emph{Uncertainty estimates} section in +\code{\link{print.stanreg}} for more details. +} +\item{\code{confint}}{ +For models fit using optimization, confidence intervals are returned via a +call to \code{\link[stats:confint]{confint.default}}. If \code{algorithm} is +\code{"sampling"}, \code{"meanfield"}, or \code{"fullrank"}, the +\code{confint} will throw an error because the +\code{\link{posterior_interval}} function should be used to compute Bayesian +uncertainty intervals. +} +\item{\code{nsamples}}{ +The number of draws from the posterior distribution obtained +} +} +} +\seealso{ +\itemize{ + \item The \code{\link[=print.stanreg]{print}}, + \code{\link[=summary.stanreg]{summary}}, and \code{\link{prior_summary}} + methods for stanreg objects for information on the fitted model. + \item \code{\link{launch_shinystan}} to use the ShinyStan GUI to explore a + fitted \pkg{rstanarm} model. + \item The \code{\link[=plot.stanreg]{plot}} method to plot estimates and + diagnostics. + \item The \code{\link{pp_check}} method for graphical posterior predictive + checking. + \item The \code{\link{posterior_predict}} and \code{\link{predictive_error}} + methods for predictions and predictive errors. + \item The \code{\link{posterior_interval}} and \code{\link{predictive_interval}} + methods for uncertainty intervals for model parameters and predictions. + \item The \code{\link[=loo.stanreg]{loo}}, \code{\link{kfold}}, and + \code{\link{log_lik}} methods for leave-one-out or K-fold cross-validation, + model comparison, and computing the log-likelihood of (possibly new) data. + \item The \code{\link[=as.matrix.stanreg]{as.matrix}}, \code{as.data.frame}, + and \code{as.array} methods to access posterior draws. +} +} diff --git a/man/stanreg-objects.Rd b/man/stanreg-objects.Rd new file mode 100644 index 000000000..3e51f0a80 --- /dev/null +++ b/man/stanreg-objects.Rd @@ -0,0 +1,160 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-objects.R +\name{stanreg-objects} +\alias{stanreg-objects} +\title{Fitted model objects} +\description{ +The \pkg{rstanarm} model-fitting functions return an object of class +\code{'stanreg'}, which is a list containing at a minimum the components listed +below. Each \code{stanreg} object will also have additional classes (e.g. 'aov', +'betareg', 'glm', 'polr', etc.) and several additional components depending +on the model and estimation algorithm. \cr +\cr +Some additional details apply to models estimated using the \code{\link{stan_mvmer}} +or \code{\link{stan_jm}} modelling functions. The \code{\link{stan_mvmer}} modelling +function returns an object of class \code{'stanmvreg'}, which inherits the +\code{'stanreg'} class, but has a number of additional elements described in the +subsection below. The \code{\link{stan_jm}} modelling function returns an object of class +\code{'stanjm'}, which inherits both the \code{'stanmvreg'} and \code{'stanreg'} +classes, but has a number of additional elements described in the subsection below. +Both the \code{'stanjm'} and \code{'stanmvreg'} classes have several of their own +methods for situations in which the default \code{'stanreg'} methods are not +suitable; see the \strong{See Also} section below. +} +\note{ +The \code{\link{stan_biglm}} function is an exception. It returns a + \link[rstan:stanfit-class]{stanfit} object rather than a stanreg object. +} +\section{Elements for \code{stanreg} objects}{ + +\describe{ + \item{\code{coefficients}}{ + Point estimates, as described in \code{\link{print.stanreg}}. + } + \item{\code{ses}}{ + Standard errors based on \code{\link[stats]{mad}}, as described in + \code{\link{print.stanreg}}. + } + \item{\code{residuals}}{ + Residuals of type \code{'response'}. + } + \item{\code{fitted.values}}{ + Fitted mean values. For GLMs the linear predictors are transformed by the + inverse link function. + } + \item{\code{linear.predictors}}{ + Linear fit on the link scale. For linear models this is the same as + \code{fitted.values}. + } + \item{\code{covmat}}{ + Variance-covariance matrix for the coefficients based on draws from the + posterior distribution, the variational approximation, or the asymptotic + sampling distribution, depending on the estimation algorithm. + } + \item{\code{model,x,y}}{ + If requested, the the model frame, model matrix and response variable used, + respectively. + } + \item{\code{family}}{ + The \code{\link[stats]{family}} object used. + } + \item{\code{call}}{ + The matched call. + } + \item{\code{formula}}{ + The model \code{\link[stats]{formula}}. + } + \item{\code{data,offset,weights}}{ + The \code{data}, \code{offset}, and \code{weights} arguments. + } + \item{\code{algorithm}}{ + The estimation method used. + } + \item{\code{prior.info}}{ + A list with information about the prior distributions used. + } + \item{\code{stanfit,stan_summary}}{ + The object of \code{\link[rstan]{stanfit-class}} returned by RStan and a + matrix of various summary statistics from the stanfit object. + } + \item{\code{rstan_version}}{ + The version of the \pkg{rstan} package that was used to fit the model. + } +} +} + +\section{Elements for \code{stanmvreg} objects}{ + +\describe{ + The \code{stanmvreg} objects contain the majority of the elements described + above for \code{stanreg} objects, but in most cases these will be a list with each + elements of the list correponding to one of the submodels (for example, + the \code{family} element of a \code{stanmvreg} object will be a list with each + element of the list containing the \code{\link[stats]{family}} object for one + submodel). In addition, \code{stanmvreg} objects contain the following additional + elements: + \item{\code{cnms}}{ + The names of the grouping factors and group specific parameters, collapsed + across the longitudinal or glmer submodels. + } + \item{\code{flevels}}{ + The unique factor levels for each grouping factor, collapsed across the + longitudinal or glmer submodels. + } + \item{\code{n_markers}}{ + The number of longitudinal or glmer submodels. + } + \item{\code{n_yobs}}{ + The number of observations for each longitudinal or glmer submodel. + } + \item{\code{n_grps}}{ + The number of levels for each grouping factor (for models estimated using + \code{\link{stan_jm}}, this will be equal to \code{n_subjects} if the + individual is the only grouping factor). + } + \item{\code{runtime}}{ + The time taken to fit the model (in minutes). + } +} +} + +\section{Additional elements for \code{stanjm} objects}{ + +\describe{ + The \code{stanjm} objects contain the elements described above for + \code{stanmvreg} objects, but also contain the following additional + elements: + \item{\code{id_var,time_var}}{ + The names of the variables distinguishing between individuals, and + representing time in the longitudinal submodel. + } + \item{\code{n_subjects}}{ + The number of individuals. + } + \item{\code{n_events}}{ + The number of non-censored events. + } + \item{\code{eventtime,status}}{ + The event (or censoring) time and status indicator for each individual. + } + \item{\code{basehaz}}{ + A list containing information about the baseline hazard. + } + \item{\code{assoc}}{ + An array containing information about the association structure. + } + \item{\code{epsilon}}{ + The width of the one-sided difference used to numerically evaluate the + slope of the longitudinal trajectory; only relevant if a slope-based + association structure was specified (e.g. etaslope, muslope, etc). + } + \item{\code{qnodes}}{ + The number of Gauss-Kronrod quadrature nodes used to evaluate the + cumulative hazard in the joint likelihood function. + } +} +} + +\seealso{ +\code{\link{stanreg-methods}}, \code{\link{stanmvreg-methods}} +} diff --git a/man/stanreg_list.Rd b/man/stanreg_list.Rd new file mode 100644 index 000000000..41cefb1ed --- /dev/null +++ b/man/stanreg_list.Rd @@ -0,0 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg_list.R +\name{stanreg_list} +\alias{stanreg_list} +\alias{stanmvreg_list} +\alias{stanjm_list} +\alias{print.stanreg_list} +\title{Create lists of fitted model objects, combine them, or append new models to +existing lists of models.} +\usage{ +stanreg_list(..., model_names = NULL) + +stanmvreg_list(..., model_names = NULL) + +stanjm_list(..., model_names = NULL) + +\method{print}{stanreg_list}(x, ...) +} +\arguments{ +\item{...}{Objects to combine into a \code{"stanreg_list"}, +\code{"stanmvreg_list"}, or \code{"stanjm_list"}. Can be fitted model +objects, existing \code{"stan*_list"} objects to combine, or one existing +\code{"stan*_list"} object followed by fitted model objects to append to +the list.} + +\item{model_names}{Optionally, a character vector of model names. If not +specified then the names are inferred from the name of the objects passed +in via \code{...}. These model names are used, for example, when printing +the results of the \code{loo_compare.stanreg_list} and +\code{loo_model_weights.stanreg_list} methods.} + +\item{x}{The object to print.} +} +\value{ +A list of class \code{"stanreg_list"}, \code{"stanmvreg_list"}, or + \code{"stanjm_list"}, containing the fitted model objects and some metadata + stored as attributes. +} +\description{ +Create lists of fitted model objects, combine them, or append new models to +existing lists of models. +} +\seealso{ +\code{\link{loo_model_weights}} for usage of \code{stanreg_list}. +} diff --git a/man/summary.stanreg.Rd b/man/summary.stanreg.Rd new file mode 100644 index 000000000..b6ce98a0c --- /dev/null +++ b/man/summary.stanreg.Rd @@ -0,0 +1,126 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/print-and-summary.R +\name{summary.stanreg} +\alias{summary.stanreg} +\alias{print.summary.stanreg} +\alias{as.data.frame.summary.stanreg} +\alias{summary.stanmvreg} +\alias{print.summary.stanmvreg} +\title{Summary method for stanreg objects} +\usage{ +\method{summary}{stanreg}( + object, + pars = NULL, + regex_pars = NULL, + probs = c(0.1, 0.5, 0.9), + ..., + digits = 1 +) + +\method{print}{summary.stanreg}(x, digits = max(1, attr(x, "print.digits")), ...) + +\method{as.data.frame}{summary.stanreg}(x, ...) + +\method{summary}{stanmvreg}(object, pars = NULL, regex_pars = NULL, probs = NULL, ..., digits = 3) + +\method{print}{summary.stanmvreg}(x, digits = max(1, attr(x, "print.digits")), ...) +} +\arguments{ +\item{object}{A fitted model object returned by one of the +\pkg{rstanarm} modeling functions. See \code{\link{stanreg-objects}}.} + +\item{pars}{An optional character vector specifying a subset of parameters to +display. Parameters can be specified by name or several shortcuts can be +used. Using \code{pars="beta"} will restrict the displayed parameters to +only the regression coefficients (without the intercept). \code{"alpha"} +can also be used as a shortcut for \code{"(Intercept)"}. If the model has +varying intercepts and/or slopes they can be selected using \code{pars = +"varying"}. + +In addition, for \code{stanmvreg} objects there are some additional shortcuts +available. Using \code{pars = "long"} will display the +parameter estimates for the longitudinal submodels only (excluding group-specific +pparameters, but including auxiliary parameters). +Using \code{pars = "event"} will display the +parameter estimates for the event submodel only, including any association +parameters. +Using \code{pars = "assoc"} will display only the +association parameters. +Using \code{pars = "fixef"} will display all fixed effects, but not +the random effects or the auxiliary parameters. + \code{pars} and \code{regex_pars} are set to \code{NULL} then all +fixed effect regression coefficients are selected, as well as any +auxiliary parameters and the log posterior. + +If \code{pars} is \code{NULL} all parameters are selected for a \code{stanreg} +object, while for a \code{stanmvreg} object all +fixed effect regression coefficients are selected as well as any +auxiliary parameters and the log posterior. See +\strong{Examples}.} + +\item{regex_pars}{An optional character vector of \link[=grep]{regular +expressions} to use for parameter selection. \code{regex_pars} can be used +in place of \code{pars} or in addition to \code{pars}. Currently, all +functions that accept a \code{regex_pars} argument ignore it for models fit +using optimization.} + +\item{probs}{For models fit using MCMC or one of the variational algorithms, +an optional numeric vector of probabilities passed to +\code{\link[stats]{quantile}}.} + +\item{...}{Currently ignored.} + +\item{digits}{Number of digits to use for formatting numbers when printing. +When calling \code{summary}, the value of digits is stored as the +\code{"print.digits"} attribute of the returned object.} + +\item{x}{An object of class \code{"summary.stanreg"}.} +} +\value{ +The \code{summary} method returns an object of class + \code{"summary.stanreg"} (or \code{"summary.stanmvreg"}, inheriting + \code{"summary.stanreg"}), which is a matrix of + summary statistics and + diagnostics, with attributes storing information for use by the + \code{print} method. The \code{print} method for \code{summary.stanreg} or + \code{summary.stanmvreg} objects is called for its side effect and just returns + its input. The \code{as.data.frame} method for \code{summary.stanreg} + objects converts the matrix to a data.frame, preserving row and column + names but dropping the \code{print}-related attributes. +} +\description{ +Summaries of parameter estimates and MCMC convergence diagnostics +(Monte Carlo error, effective sample size, Rhat). +} +\details{ +\subsection{mean_PPD diagnostic}{ +Summary statistics are also reported for \code{mean_PPD}, the sample +average posterior predictive distribution of the outcome. This is useful as a +quick diagnostic. A useful heuristic is to check if \code{mean_PPD} is +plausible when compared to \code{mean(y)}. If it is plausible then this does +\emph{not} mean that the model is good in general (only that it can reproduce +the sample mean), however if \code{mean_PPD} is implausible then it is a sign +that something is wrong (severe model misspecification, problems with the +data, computational issues, etc.). +} +} +\examples{ +if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") { +if (!exists("example_model")) example(example_model) +summary(example_model, probs = c(0.1, 0.9)) + +# These produce the same output for this example, +# but the second method can be used for any model +summary(example_model, pars = c("(Intercept)", "size", + paste0("period", 2:4))) +summary(example_model, pars = c("alpha", "beta")) + +# Only show parameters varying by group +summary(example_model, pars = "varying") +as.data.frame(summary(example_model, pars = "varying")) +} +} +\seealso{ +\code{\link{prior_summary}} to extract or print a summary of the + priors used for a particular model. +} diff --git a/man/terms.stanmvreg.Rd b/man/terms.stanmvreg.Rd new file mode 100644 index 000000000..eb0f31fa2 --- /dev/null +++ b/man/terms.stanmvreg.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanmvreg-methods.R +\name{terms.stanmvreg} +\alias{terms.stanmvreg} +\title{terms method for stanmvreg objects} +\usage{ +\method{terms}{stanmvreg}(x, fixed.only = TRUE, random.only = FALSE, m = NULL, ...) +} +\arguments{ +\item{x, fixed.only, random.only, ...}{See lme4:::terms.merMod.} + +\item{m}{Integer specifying the number or name of the submodel} +} +\description{ +terms method for stanmvreg objects +} +\keyword{internal} diff --git a/man/terms.stanreg.Rd b/man/terms.stanreg.Rd new file mode 100644 index 000000000..46edfa944 --- /dev/null +++ b/man/terms.stanreg.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/stanreg-methods.R +\name{terms.stanreg} +\alias{terms.stanreg} +\title{terms method for stanreg objects} +\usage{ +\method{terms}{stanreg}(x, ..., fixed.only = TRUE, random.only = FALSE) +} +\arguments{ +\item{x, fixed.only, random.only, ...}{See lme4:::terms.merMod.} +} +\description{ +terms method for stanreg objects +} +\keyword{internal}