rstan (version 2.8.2)

stan: Fit a model using Stan

Description

Fit a model defined in the Stan modeling language and return the fitted result as an instance of stanfit.

Usage

stan(file, model_name = "anon_model", model_code = "", 
  fit = NA, data = list(), pars = NA, chains = 4,
  iter = 2000, warmup = floor(iter/2), thin = 1, 
  init = "random", seed = sample.int(.Machine$integer.max, 1), 
  algorithm = c("NUTS", "HMC", "Fixed_param"),  control = NULL,
  sample_file = NULL, diagnostic_file = NULL, 
  save_dso = TRUE, 
  verbose = FALSE, include = TRUE,
  cores = getOption("mc.cores", 1L),
  open_progress = interactive() && !isatty(stdout()) &&
                  !identical(Sys.getenv("RSTUDIO"), "1"),
  ...,
  boost_lib = NULL,
  eigen_lib = NULL)

Arguments

file

A character string file name or a connection that Rsupports containing the text of a model specification in the Stan modeling language; a model may also be specified directly as a character string using parameter model_code or t

model_name

A character string naming the model; defaults to "anon_model". However, the model name would be derived from file or model_code (if model_code is the name of a character string object) if <

model_code

A character string either containing the model definition or the name of a character string object in the workspace. This parameter is used only if parameter file is not specified. When fit is specified, the model c

fit

An instance of S4 class stanfit derived from a previous fit; defaults to NA. If fit is not NA, the compiled model associated with the fitted result is re-used; thus the time that

data

A named list or environment providing the data for the model or a character vector for all the names of objects used as data. See the notes below.

pars

A vector of character string specifying parameters of interest; defaults to NA indicating all parameters in the model. If include = TRUE, only samples for parameters given in pars are stored in the fitted re

chains

A positive integer specifying number of chains; defaults to 4.

iter

A positive integer specifying how many iterations for each chain (including warmup). The default is 2000.

warmup

A positive integer specifying number of warmup (aka burnin) iterations. This also specifies the number of iterations used for stepsize adaptation, so warmup samples should not be used for inference. The number of warmup should not be large

thin

A positive integer specifying the period for saving sample; defaults to 1.

init

One of digit 0, string "0" or "random", a function that returns a named list, or a list of named list. "0": initialize all to be zero on the unconstrained support; "random": ran

seed

The seed, a positive integer, for random number generation of Stan. The default is generated from 1 to the maximum integer supported by Rso fixing the seed of R's random number generator can essentially fix the seed of Stan. When multiple

algorithm

One of algorithms that are implemented in Stan such as the No-U-Turn sampler (NUTS, Hoffman and Gelman 2011) and static HMC.

sample_file

A character string of file name for specifying where to write samples for all parameters and other saved quantities. If not provided, files are not created. When the folder specified is not writable, tempdir() is used.

diagnostic_file

A character string of file name for specifying where to write diagnostics data for all parameters. If not provided, files are not created. When the folder specified is not writable, tempdir() is used. When there

save_dso

Logical, with default TRUE, indicating whether the dynamic shared object (DSO) compiled from the C++ code for the model will be saved or not. If TRUE, we can draw samples from the same model in another Rsession usin

verbose

TRUE or FALSE: flag indicating whether to print intermediate output from Stan on the console, which might be helpful for model debugging.

control

a named list of parameters to control the sampler's behavior. It defaults to NULL so all the default values are used. First, the following are adaptation parameters for sampling algorithms. These are parameters used

include

Logical scalar defaulting to TRUE indicating whether to include or exclude the parameters given by the pars argument. If FALSE, only entire multidimensional parameters can be excluded, rather than partic

cores

Number of cores to use when executing the chains in parallel, which defaults to 1 but we recommend setting the mc.cores option to be as many processors as the hardware and RAM allow (up to the number of chains).

open_progress

Logical scalar that only takes effect if cores > 1 but is recommended to be TRUE in interactive use so that the progress of the chains will be redirected to a file that is automatically opened for inspection. For ver

...

Other optional parameters:

1. chain_id(integer)
2. init_r(double, positive)
3. test_grad(logical)
4. append_samples(logical)

boost_lib

The path for an alternative version of the Boost C++ to use instead of the one in the BH package.

eigen_lib

The path for an alternative version of the Eigen C++ library to the one in RcppEigen.

Value

• An object of S4 class stanfit. However, if cores > 1 and there is an error for any of the chains, then the error(s) are printed. If all chains have errors and an error occurs before or during sampling, the returned object does not contain samples. But the compiled binary object for the model is still included, so we can reuse the returned object for another sampling.

Details

stan does all of the work of fitting a Stan model and returning the results as an instance of stanfit. First, it translates the Stan model to C++ code. Second, the C++ code is compiled into a binary shared object, which is loaded into the current Rsession (an object of S4 class stanmodel is created). Finally, samples are drawn and wrapped in an object of S4 class stanfit, which provides functions such as print, summary, and plot to inspect and retrieve the results of the fitted model.

stan can also be used to sample again from a fitted model under different settings (e.g., different iter) by providing argument fit. In this case, the compiled C++ code for the model is reused.

References

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

The Stan Development Team CmdStan Interface User's Guide. http://mc-stan.org.

See Also

stanc for translating model code in Stan modeling language to C++, sampling for sampling, and stanfit for the fitted results.

see extract and as.array.stanfit for extracting samples from stanfit objects.

Examples

#### example 1 
library(rstan)
scode <- "
parameters {
  real y[2]; 
} 
model {
  y[1] ~ normal(0, 1);
  y[2] ~ double_exponential(0, 2);
} 
"
fit1 <- stan(model_code = scode, iter = 10, verbose = FALSE) 
print(fit1)
fit2 <- stan(fit = fit1, iter = 10000, verbose = FALSE) 

## extract samples as a list of arrays
e2 <- extract(fit2, permuted = TRUE)

## using as.array on the stanfit object to get samples 
a2 <- as.array(fit2)

#### example 2
#### the result of this package is included in the package 

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 = 500)
print(exfit)
plot(exfit)
## examples of specify argument `init` for function stan

## define a function to generate initial values that can
## be fed to function stan's argument `init`
# function form 1 without arguments 
initf1 <- function() {
  list(mu = 1, sigma = 4, z = array(rnorm(6), dim = c(3,2)), alpha = 1)
} 
# function form 2 with an argument named `chain_id`
initf2 <- function(chain_id = 1) {
  # cat("chain_id =", chain_id, "\n")
  list(mu = 1, sigma = 4, z = array(rnorm(6), dim = c(3,2)), alpha = chain_id)
} 

# generate a list of lists to specify initial values
n_chains <- 4
init_ll <- lapply(1:n_chains, function(id) initf2(chain_id = id))
 
exfit0 <- stan(model_code = excode, init = initf1) 
stan(fit = exfit0, init = initf2) 
stan(fit = exfit0, init = init_ll, chains = n_chains)