R: Class 'stanfit': fitted Stan model

stanfit-class {rstan} | R Documentation

## 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.

### See Also

`stan` and `stanmodel`

### 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)
    seed <- get_seed(exfit)
    sp <- get_sampler_params(exfit)
    ml <- As.mcmc.list(exfit)
    cat(get_stancode(exfit))

[Package rstan version 2.15.1 Index]