rstan: stanfit-class – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

stanfit-class

Class stanfit: fitted Stan model

Description

The components (slots) of a stanfit object and the various available methods are described below. When methods have their own more detailed documentation pages links are provided.

Objects from the Class

An object of class stanfit contains the output derived from fitting a Stan model as returned by the top-level function stan or the lower-level methods sampling and vb (which are defined on class stanmodel). Many methods (e.g., print, plot, summary) are provided for summarizing results and various access methods also allow the underlying data (e.g., simulations, diagnostics) contained in the object to be retrieved.

Slots

model_name:: The model name as a string.
model_pars:: A character vector of names of parameters (including transformed parameters and derived quantities).
par_dims:: A named list giving the dimensions for all parameters. The dimension for a scalar parameter is given as numeric(0).
mode:: An integer indicating the mode of the fitted model. 0 indicates sampling mode, 1 indicates test gradient mode (no sampling is done), and 2 indicates error mode (an error occurred before sampling). Most methods for stanfit objects are useful only if mode=0.
sim:: A list containing simulation results including the posterior draws as well as various pieces of metadata used by many of the methods for stanfit objects.
inits:: The initial values (either user-specified or generated randomly) for all chains. This is a list with one component per chain. Each component is a named list containing the initial values for each parameter for the corresponding chain.
stan_args:: A list with one component per chain containing the arguments used for sampling (e.g. iter, seed, etc.).
stanmodel:: The instance of S4 class stanmodel.
date:: A string containing the date and time the object was created.
.MISC:: Miscellaneous helper information used for the fitted model. This is an object of type environment. Users rarely (if ever) need to access the contents of .MISC.

Methods

Printing, plotting, and summarizing:

show: Print the default summary for the model.
print: Print a customizable summary for the model. See print.stanfit.
plot: Create various plots summarizing the fitted model. See plot,stanfit-method.
summary: Summarize the distributions of estimated parameters and derived quantities using the posterior draws. See summary,stanfit-method.
get_posterior_mean: Get the posterior mean for parameters of interest (using pars to specify a subset of parameters). Returned is a matrix with one column per chain and an additional column for all chains combined.

Extracting posterior draws:

extract: Extract the draws for all chains for all (or specified) parameters. See extract.
as.array, as.matrix, as.data.frame: Coerce the draws (without warmup) to an array, matrix or data frame. See as.array.stanfit.
As.mcmc.list: Convert a stanfit object to an mcmc.list as in package coda. See As.mcmc.list.
get_logposterior: Get the log-posterior at each iteration. Each element of the returned list is the vector of log-posterior values (up to an additive constant, i.e. up to a multiplicative constant on the linear scale) for a single chain. The optional argument inc_warmup (defaulting to TRUE) indicates whether to include the warmup period.

Diagnostics, log probability, and gradients:

get_sampler_params: Obtain the parameters used for the sampler such as stepsize and treedepth. The results are returned as a list with one component (an array) per chain. The array has number of columns corresponding to the number of parameters used in the sampler and its column names provide the parameter names. Optional argument inc_warmup (defaulting to TRUE) indicates whether to include the warmup period.
get_adaptation_info: Obtain the adaptation information for the sampler if NUTS was used. The results are returned as a list, each element of which is a character string with the info for a single chain.
log_prob: Compute the log probability density (lp__) for a set of parameter values (on the unconstrained space) up to an additive constant. The unconstrained parameters are specified using a numeric vector. The number of parameters on the unconstrained space can be obtained using method get_num_upars. A numeric value is returned. See also the documentation in log_prob.
grad_log_prob: Compute the gradient of log probability density function for a set of parameter values (on the unconstrained space) up to an additive constant. The unconstrained parameters are specified using a numeric vector with the length being the number of unconstrained parameters. A numeric vector is returned with the length of the number of unconstrained parameters and an attribute named log_prob being the lp__. See also the documentation in grad_log_prob.
get_num_upars: Get the number of unconstrained parameters of the model. The number of parameters for a model is not necessarily equal to this number of unconstrained parameters. For example, when a parameter is specified as a simplex of length K, the number of unconstrained parameters is K-1.
unconstrain_pars: Transform the parameters to unconstrained space. The input is a named list as for specifying initial values for each parameter. A numeric vector is returned. See also the documentation in unconstrain_pars.
constrain_pars: Get the parameter values from their unconstrained space. The input is a numeric vector. A list is returned. This function is contrary to unconstrain_pars. See also the documentation in constrain_pars.

Metadata and miscellaneous:

get_stancode: Get the Stan code for the fitted model as a string. The result can be printed in a readable format using cat.
get_stanmodel: Get the object of S4 class stanmodel of the fitted model.
get_elapsed_time: Get the warmup time and sample time in seconds. A matrix of two columns is returned with each row containing the warmup and sample times for one chain.
get_inits, iter = NULL: Get the initial values for parameters used in sampling all chains. The returned object is a list with the same structure as the inits slot described above. If object@mode=2 (error mode) an empty list is returned. If iter is not NULL, then the draw from that iteration is returned for each chain rather than the initial state.
get_cppo_mode: Get the optimization mode used for compilation. The returned string is one of "fast", "presentation2", "presentation1", and "debug".
get_seed: Get the (P)RNG seed used. When the fitted object is empty (mode=2), NULL might be returned. In the case that the seeds for all chains are different, use get_seeds.
get_seeds: Get the seeds used for all chains. When the fitted object is empty (mode=2), NULL might be returned.

References

The Stan Development Team Stan Modeling Language User's Guide and Reference Manual. http://mc-stan.org.

Examples

## Not run: 
showClass("stanfit")
ecode <- '
  parameters {
    real<lower=0> y[2];
  } 
  model {
    y ~ exponential(1);
  }
'
fit <- stan(model_code = ecode, iter = 10, chains = 1)
fit2 <- stan(fit = fit)
print(fit2)
plot(fit2)
traceplot(fit2)
ainfo <- get_adaptation_info(fit2)
cat(ainfo[[1]])
seed <- get_seed(fit2)
sp <- get_sampler_params(fit2)
sp2 <- get_sampler_params(fit2, inc_warmup = FALSE)
head(sp[[1]])

lp <- log_prob(fit, c(1, 2))
grad <- grad_log_prob(fit, c(1, 2))
lp2 <- attr(grad, "log_prob") # should be the same as "lp"

# get the number of parameters on the unconstrained space
n <- get_num_upars(fit)

# parameters on the positive real line (constrained space) 
y1 <- list(y = rep(1, 2)) 

uy <- unconstrain_pars(fit, y1) 
## uy should be c(0, 0) since here the log transformation is used
y1star <- constrain_pars(fit, uy)

print(y1)
print(y1star) # y1start should equal to y1 

## End(Not run)

# Create a stanfit object from reading CSV files of samples (saved in rstan
# package) generated by funtion stan for demonstration purpose from model as follows. 
# 
excode <- '
  transformed data {
    real y[20];
    y[1] <- 0.5796;  y[2]  <- 0.2276;   y[3] <- -0.2959; 
    y[4] <- -0.3742; y[5]  <- 0.3885;   y[6] <- -2.1585;
    y[7] <- 0.7111;  y[8]  <- 1.4424;   y[9] <- 2.5430; 
    y[10] <- 0.3746; y[11] <- 0.4773;   y[12] <- 0.1803; 
    y[13] <- 0.5215; y[14] <- -1.6044;  y[15] <- -0.6703; 
    y[16] <- 0.9459; y[17] <- -0.382;   y[18] <- 0.7619;
    y[19] <- 0.1006; y[20] <- -1.7461;
  }
  parameters {
    real mu;
    real<lower=0, upper=10> sigma;
    vector[2] z[3];
    real<lower=0> alpha;
  } 
  model {
    y ~ normal(mu, sigma);
    for (i in 1:3) 
      z[i] ~ normal(0, 1);
    alpha ~ exponential(2);
  } 
'

# exfit <- stan(model_code = excode, save_dso = FALSE, iter = 200, 
#               sample_file = "rstan_doc_ex.csv")
# 

exfit <- read_stan_csv(dir(system.file('misc', package = 'rstan'),
                       pattern='rstan_doc_ex_[[:digit:]].csv',
                       full.names = TRUE))

print(exfit)
## Not run: 
plot(exfit)

## End(Not run)

adaptinfo <- get_adaptation_info(exfit)
inits <- get_inits(exfit) # empty
inits <- get_inits(exfit, iter = 101)
seed <- get_seed(exfit)
sp <- get_sampler_params(exfit)
ml <- As.mcmc.list(exfit)
cat(get_stancode(exfit))

rstan

R Interface to Stan

v2.21.2

GPL (>= 3)

Authors

Jiqiang Guo [aut], Jonah Gabry [aut], Ben Goodrich [cre, aut], Sebastian Weber [aut], Daniel Lee [ctb], Krzysztof Sakrejda [ctb], Modrak Martin [ctb], Trustees of Columbia University [cph], Oleg Sklyar [cph] (R/cxxfunplus.R), The R Core Team [cph] (R/pairs.R, R/dynGet.R), Jens Oehlschlaegel-Akiyoshi [cph] (R/pairs.R), John Maddock [cph] (gamma.hpp), Paul Bristow [cph] (gamma.hpp), Nikhar Agrawal [cph] (gamma.hpp), Christopher Kormanyos [cph] (gamma.hpp), Bronder Steve [ctb]

Initial release

2020-07-27