rstanarm (version 2.21.1)

prior_summary.stanreg: Summarize the priors used for an rstanarm model

Description

The 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 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 posterior_vs_prior function, or alternatively by fitting the model with the prior_PD argument set to TRUE (to draw from the prior predictive distribution instead of conditioning on the outcome) and then plotting the parameters.

Usage

# S3 method for stanreg
prior_summary(object, digits = 2, ...)

Arguments

object

A fitted model object returned by one of the rstanarm modeling functions. See stanreg-objects.

digits

Number of digits to use for rounding.

...

Currently ignored by the method for stanreg objects.

Value

A list of class "prior_summary.stanreg", which has its own print method.

Intercept (after predictors centered)

For rstanarm modeling functions that accept a prior_intercept argument, the specified prior for the intercept term applies to the intercept after 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 rstanarm), but when 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 sparse argument set to TRUE (which is only possible with a subset of the modeling functions and never the default).

Adjusted scales

For some models you may see "adjusted scale" in the printed output and adjusted scales included in the object returned by prior_summary. These adjusted scale values are the prior scales actually used by 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 autoscale argument). To disable internal prior scale adjustments set the autoscale argument to FALSE when setting a prior using one of the distributions that accepts an autoscale argument. For example, normal(0, 5, autoscale=FALSE) instead of just normal(0, 5).

Coefficients in Q-space

For the models fit with an rstanarm modeling function that supports the QR argument (see e.g, stan_glm), if QR is set to TRUE then the prior distributions for the regression coefficients specified using the prior argument are not relative to the original predictor variables \(X\) but rather to the variables in the matrix \(Q\) obtained from the \(QR\) decomposition of \(X\).

In particular, if prior = normal(location,scale), then this prior on the coefficients in \(Q\)-space can be easily translated into a joint multivariate normal (MVN) prior on the coefficients on the original predictors in \(X\). Letting \(\theta\) denote the coefficients on \(Q\) and \(\beta\) the coefficients on \(X\) then if \(\theta \sim N(\mu, \sigma)\) the corresponding prior on \(\beta\) is \(\beta \sim MVN(R\mu, R'R\sigma^2)\), where \(\mu\) and \(\sigma\) are vectors of the appropriate length. Technically, rstanarm uses a scaled \(QR\) decomposition to ensure that the columns of the predictor matrix used to fit the model all have unit scale, when the autoscale argument to the function passed to the prior argument is TRUE (the default), in which case the matrices actually used are \(Q^\ast = Q \sqrt{n-1}\) and \(R^\ast = \frac{1}{\sqrt{n-1}} R\). If autoscale = FALSE we instead scale such that the lower-right element of \(R^\ast\) is \(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 QR argument).

If you are interested in the prior on \(\beta\) implied by the prior on \(\theta\), we strongly recommend visualizing it as described above in the Description section, which is simpler than working it out analytically.

See Also

The priors help page and the Prior Distributions vignette.

Examples

# NOT RUN {
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)

# }