Movatterモバイル変換

Type:	Package
Title:	R Interface to Stan
Version:	2.32.7
Description:	User-facing R functions are provided to parse, compile, test, estimate, and analyze Stan models by accessing the header-only Stan library provided by the 'StanHeaders' package. The Stan project develops a probabilistic programming language that implements full Bayesian statistical inference via Markov Chain Monte Carlo, rough Bayesian inference via 'variational' approximation, and (optionally penalized) maximum likelihood estimation via optimization. In all three cases, automatic differentiation is used to quickly and accurately evaluate gradients without burdening the user with the need to derive the partial derivatives.
License:	GPL (≥ 3)
NeedsCompilation:	yes
Imports:	methods, stats4, inline (≥ 0.3.19), gridExtra (≥ 2.3), Rcpp(≥ 1.0.7), RcppParallel (≥ 5.1.4), loo (≥ 2.4.1), pkgbuild(≥ 1.2.0), QuickJSR, ggplot2 (≥ 3.3.5)
Depends:	R (≥ 3.4.0), StanHeaders (≥ 2.32.0)
LinkingTo:	Rcpp (≥ 1.0.7), RcppEigen (≥ 0.3.4.0.0), BH (≥ 1.75.0-0),StanHeaders (≥ 2.32.0), RcppParallel (≥ 5.1.4)
Suggests:	testthat (≥ 3.0.4), parallel, KernSmooth, shinystan,bayesplot, rmarkdown, rstantools, rstudioapi, Matrix, knitr,coda, V8
URL:	https://mc-stan.org/rstan/,https://discourse.mc-stan.org
BugReports:	https://github.com/stan-dev/rstan/issues/
VignetteBuilder:	knitr
SystemRequirements:	GNU make, pandoc
Encoding:	UTF-8
RoxygenNote:	7.1.2
Config/testthat/edition:	3
Packaged:	2025-03-10 04:53:43 UTC; ben
Author:	Jiqiang Guo [aut], Jonah Gabry [aut], Ben Goodrich [cre, aut], Andrew Johnson [aut], Sebastian Weber [aut], Hamada S. Badr [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]
Maintainer:	Ben Goodrich <benjamin.goodrich@columbia.edu>
Repository:	CRAN
Date/Publication:	2025-03-10 08:50:02 UTC

RStan — theR interface to Stan

Description

Stan Development Team

RStan is theR interface to theStan C++ package.The RStan interface (rstanR package) provides:

• Full Bayesian inference using the No-U-Turn sampler (NUTS),a variant of Hamiltonian Monte Carlo (HMC)

• Approximate Bayesian inference using automatic differentiationvariational inference (ADVI)

• Penalized maximum likelihood estimation using L-BFGS optimization

For documentation on Stan itself, including the manual and user guidefor the modeling language, case studies and worked examples, and othertutorial information visit the Users section of the Stan website:

• mc-stan.org/users/documentation

OtherR packages from the Stan Development Team

Various relatedR packages are also available from the Stan Development Team including these and more:

Author(s)

There are also many other important contributors to RStan(github.com/rstan).Please use 'Stan Development Team' whenever citing the R interface to Stan.A BibTex entry is available fromhttps://mc-stan.org/rstan/authorsorcitation("rstan").

See Also

• The RStan vignettes:https://mc-stan.org/rstan/articles/.

• stan for details on fitting models andstanfit for information on the fitted model objects.

• Thelookup for finding a function in the Stan languagethat corresponds to aR function or name.

• https://github.com/stan-dev/rstan/issues/ to submit a bugreport or feature request.

• https://discourse.mc-stan.org to ask aquestion on the Stan Forums.

Examples

## Not run: stanmodelcode <- "data {  int<lower=0> N;  array[N] real y;}parameters {  real mu;}model {  target += normal_lpdf(mu | 0, 10);  target += normal_lpdf(y  | mu, 1);}"y <- rnorm(20)dat <- list(N = 20, y = y);fit <- stan(model_code = stanmodelcode, model_name = "example",            data = dat, iter = 2012, chains = 3, verbose = TRUE,            sample_file = file.path(tempdir(), 'norm.csv'))print(fit)# extract samplese <- extract(fit, permuted = FALSE) # return a list of arraysstr(e)arr <- as.array(fit) # return an arraystr(arr)mat <- as.matrix(fit) # return a matrixstr(mat)## End(Not run)

Create an mcmc.list from a stanfit object

Description

Create anmcmc.list (coda) from astanfit object.

Usage

  As.mcmc.list(object, pars, include = TRUE, ...)

Arguments

Value

An object of classmcmc.list.

RStan Diagnostic plots

Description

Diagnostic plots for HMC and NUTS using ggplot2.

Usage

  stan_diag(object,             information = c("sample","stepsize", "treedepth","divergence"),             chain = 0, ...)  stan_par(object, par, chain = 0, ...)    stan_rhat(object, pars, ...)  stan_ess(object, pars, ...)  stan_mcse(object, pars, ...)

Arguments

Details

stan_rhat,stan_ess,stan_mcse

Respectively, these plots show the distribution of the Rhat statistic, the ratio of effective sample size to total sample size, and the ratio of Monte Carlo standard errorto posterior standard deviation for the estimated parameters. These plots are not intended to identify individual parameters, but rather to allowfor quickly identifying if the estimated values of these quantities aredesireable for all parameters.

stan_par

Callingstan_par generates three plots: (i) a scatterplot ofpar vs. the accumulated log-posterior (lp__), (ii) a scatterplot ofpar vs. the average Metropolis acceptance rate (accept_stat), and (iii) a violin plot showing the distribution ofpar at each of the sampled step sizes (one per chain).For the scatterplots, red points are superimposed to indicate which (if any) iterations encountered a divergent transition. Yellow points indicate a transition that hit the maximum treedepth rather than terminated its evolution normally.

stan_diag

Theinformation argument is used to specify which plotsstan_diag should generate:

• information='sample' Histograms oflp__ andaccept_stat, as well as a scatterplot showing their joint distribution.

• information='stepsize' Violin plots showing the distributions oflp__ andaccept_stat at each of the sampledstep sizes (one per chain).

• information='treedepth' Histogram oftreedepth and violin plots showing the distributions oflp__ andaccept_stat for each value oftreedepth.

• information='divergence' Violin plots showing the distributions oflp__ andaccept_stat for iterations thatencountered divergent transitions (divergent=1) and those thatdid not (divergent=0).

Value

Forstan_diag andstan_par, a list containing the ggplot objects for each of the displayed plots. Forstan_rhat,stan_ess, andstan_mcse, a single ggplot object.

Note

For details about the individual diagnostics and sampler parameters and theirinterpretations see the Stan Modeling Language User's Guide and Reference Manual athttps://mc-stan.org/docs/.

See Also

List of RStan plotting functions,Plot options

Examples

## Not run: fit <- stan_demo("eight_schools")stan_diag(fit, info = 'sample') # shows three plots togethersamp_info <- stan_diag(fit, info = 'sample') # saves the three plots in a listsamp_info[[3]] # access just the third plotstan_diag(fit, info = 'sample', chain = 1) # overlay chain 1stan_par(fit, par = "mu")## End(Not run)

ggplot2 for RStan

Description

Visual posterior analysis using ggplot2.

Usage

  stan_plot(object, pars, include = TRUE, unconstrain = FALSE, ...)  stan_trace(object, pars, include = TRUE, unconstrain = FALSE,            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,             window = NULL)  stan_scat(object, pars, unconstrain = FALSE,            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)  stan_hist(object, pars, include = TRUE, unconstrain = FALSE,            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...)  stan_dens(object, pars, include = TRUE, unconstrain = FALSE,            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,             separate_chains = FALSE)  stan_ac(object, pars, include = TRUE, unconstrain = FALSE,            inc_warmup = FALSE, nrow = NULL, ncol = NULL, ...,             separate_chains = FALSE, lags = 25, partial = FALSE)  quietgg(gg)

Arguments

Details

Forstan_plot, there are additional arguments that can be specified in.... The optional arguments and their default values are:

point_est = "median"

The point estimate to show. Either "median" or "mean".

show_density = FALSE

Should kernel density estimates be plotted above the intervals?

ci_level = 0.8

The posterior uncertainty interval to highlight.Central100*ci_level% intervals are computed from the quantiles of the posterior draws.

outer_level = 0.95

An outer interval to also draw as a line (ifshow_outer_line isTRUE) but not highlight.

show_outer_line = TRUE

Should theouter_level interval be shown or hidden? Defaults to =TRUE (to plot it).

fill_color,outline_color,est_color

Colors to override the defaults for the highlighted interval, the outer interval (and density outline), and the point estimate.

Value

Aggplot object that can be further customizedusing theggplot2 package.

Note

Because therstan plotting functions useggplot2 (and thus the resulting plots behave likeggplot objects), when calling a plotting function within a loop or when assigning a plot to a name (e.g.,graph <- plot(fit, plotfun = "rhat")),if you also want the side effect of the plot being displayed you must explicity print it (e.g.,(graph <- plot(fit, plotfun = "rhat")),print(graph <- plot(fit, plotfun = "rhat"))).

See Also

List of RStan plotting functions,Plot options

Examples

## Not run: example("read_stan_csv")stan_plot(fit)stan_trace(fit)library(gridExtra)fit <- stan_demo("eight_schools")stan_plot(fit)stan_plot(fit, point_est = "mean", show_density = TRUE, fill_color = "maroon")# histogramsstan_hist(fit)# suppress ggplot2 messages about default bindwidthquietgg(stan_hist(fit))quietgg(h <- stan_hist(fit, pars = "theta", binwidth = 5)) # juxtapose histograms of tau and unconstrained tau tau <- stan_hist(fit, pars = "tau")tau_unc <- stan_hist(fit, pars = "tau", unconstrain = TRUE) +             xlab("tau unconstrained")grid.arrange(tau, tau_unc)# kernel density estimatesstan_dens(fit)(dens <- stan_dens(fit, fill = "skyblue", ))dens <- dens + ggtitle("Kernel Density Estimates\n") + xlab("")dens(dens_sep <- stan_dens(fit, separate_chains = TRUE, alpha = 0.3))dens_sep + scale_fill_manual(values = c("red", "blue", "green", "black"))(dens_sep_stack <- stan_dens(fit, pars = "theta", alpha = 0.5,                             separate_chains = TRUE, position = "stack"))# traceplottrace <- stan_trace(fit)trace +  scale_color_manual(values = c("red", "blue", "green", "black"))trace +  scale_color_brewer(type = "div") +  theme(legend.position = "none")facet_style <- theme(strip.background = ggplot2::element_rect(fill = "white"),                     strip.text = ggplot2::element_text(size = 13, color = "black"))(trace <- trace + facet_style)# scatterplot(mu_vs_tau <- stan_scat(fit, pars = c("mu", "tau"), color = "blue", size = 4))mu_vs_tau +   ggplot2::coord_flip() +   theme(panel.background = ggplot2::element_rect(fill = "black"))  ## End(Not run)

Convergence and efficiency diagnostics for Markov Chains

Description

These functions are improved versions of the traditionalRhat (for convergence) and Effective Sample Size (forefficiency).

Usage

Rhat(sims)ess_bulk(sims)ess_tail(sims)

Arguments

Value

TheRhat function produces R-hat convergence diagnostic, whichcompares the between- and within-chain estimates for model parametersand other univariate quantities of interest. If chains have not mixedwell (ie, the between- and within-chain estimates don't agree), R-hat islarger than 1. We recommend running at least four chains by default andonly using the sample if R-hat is less than 1.05. Stan reports R-hatwhich is the maximum of rank normalized split-R-hat and rank normalizedfolded-split-R-hat, which works for thick tailed distributions and issensitive also to differences in scale.

Theess_bulk function produces an estimated Bulk Effective SampleSize (bulk-ESS) using rank normalized draws. Bulk-ESS is useful measurefor sampling efficiency in the bulk of the distribution (related e.g. toefficiency of mean and median estimates), and is well defined even ifthe chains do not have finite mean or variance.

Theess_tail function produces an estimated Tail Effective SampleSize (tail-ESS) by computing the minimum of effective sample sizes for5% and 95% quantiles. Tail-ESS is useful measure for samplingefficiency in the tails of the distribution (related e.g. to efficiencyof variance and tail quantile estimates).

Both bulk-ESS and tail-ESS should be at least100 (approximately)per Markov Chain in order to be reliable and indicate that estimates ofrespective posterior quantiles are reliable.

Author(s)

Paul-Christian Burkner and Aki Vehtari

References

Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, andPaul-Christian Burkner (2019). Rank-normalization, folding, andlocalization: An improved R-hat for assessing convergence of MCMC.arXiv preprintarXiv:1903.08008.

See Also

monitor

Examples

# pretend these draws came from five actual Markov Chinssims <- matrix(rnorm(500), nrow = 100, ncol = 5)Rhat(sims)ess_bulk(sims)ess_tail(sims)

Create array, matrix, or data.frame objects from samples in astanfit object

Description

The samples (without warmup) included in astanfit object can be coerced to anarray,matrix, ordata.frame.Methods are also provided for checking and setting names and dimnames.

Usage

  ## S3 method for class 'stanfit'as.array(x, ...)   ## S3 method for class 'stanfit'as.matrix(x, ...)  ## S3 method for class 'stanfit'as.data.frame(x, ...)  ## S3 method for class 'stanfit'is.array(x)   ## S3 method for class 'stanfit'dim(x)  ## S3 method for class 'stanfit'dimnames(x)  ## S3 method for class 'stanfit'names(x)  ## S3 replacement method for class 'stanfit'names(x) <- value

Arguments

Details

as.array andas.matrix can be applied to astanfitobject to coerce the samples without warmup toarray ormatrix.Theas.data.frame method first callsas.matrix and then coercesthis matrix to adata.frame.

The array has three named dimensions: iterations, chains, parameters. Foras.matrix, all chains are combined, leaving a matrix of iterationsby parameters.

Value

as.array,as.matrix, andas.data.frame return an array,matrix, and data.frame, respectively.

dim anddimnames return the dim and dimnames of the array object that could be created, whilenames returns the thirdelement of thedimnames, which are the names of the margins of theposterior distribution. Thenames assignment method allows for assigning more interpretable names to them.

is.array returnsTRUE forstanfit objects that includesamples; otherwiseFALSE.

When thestanfit object does not contain samples, empty objectsare returned fromas.array,as.matrix,as.data.frame,dim,dimnames, andnames.

See Also

S4 classstanfit and its methodextract

Examples

## Not run: ex_model_code <- '  parameters {    array[2, 3] real alpha;    array[2] real beta;   }   model {    for (i in 1:2) for (j in 1:3)       alpha[i, j] ~ normal(0, 1);     for (i in 1:2)       beta[i] ~ normal(0, 2);     # beta ~ normal(0, 2) // vectorized version  } '## fit the model fit <- stan(model_code = ex_model_code, chains = 4) dim(fit)dimnames(fit)is.array(fit) a <- as.array(fit)m <- as.matrix(fit)d <- as.data.frame(fit)## End(Not run)

Check HMC diagnostics after sampling

Description

These functions print summaries of important HMC diagnostics or extractthose diagnostics from astanfit object. See theDetailssection, below.

Usage

check_hmc_diagnostics(object)check_divergences(object)check_treedepth(object)check_energy(object)get_divergent_iterations(object)get_max_treedepth_iterations(object)get_num_leapfrog_per_iteration(object)get_num_divergent(object)get_num_max_treedepth(object)get_bfmi(object)get_low_bfmi_chains(object)

Arguments

Details

Thecheck_hmc_diagnostics function calls the othercheck_* functions internally and prints an overall summary, but the other functions can also be called directly:

• check_divergences prints the number (and percentage) of iterations that ended with a divergence,

• check_treedepth prints the number (and percentage) of iterations that saturated the max treedepth,

• check_energy prints E-BFMI values for each chain for which E-BFMI is less than 0.2.

Theget_* functions are for programmatic access to the diagnostics.

• get_divergent_iterations andget_max_treedepth_iterations return a logical vector indicating problems for individual iterations,

• get_num_divergent andget_num_max_treedepth return the number of offending interations,

• get_num_leapfrog_per_iteration returns an integer vector with the number of leapfrog evalutions for each iteration,

• get_bfmi returns per-chain E-BFMI values andget_low_bfmi_chainsreturns the indices of chains with low E-BFMI.

The following are several of many resources that provide more information on these diagnostics:

• Brief explanations of some of the problems detected by these diagnostics can be found in theBrief Guide to Stan's Warnings.

• Betancourt (2017) provides much more depth on these diagnosticsas well as a conceptual introduction to Hamiltonian Monte Carlo in general.

• Gabry et al. (2018) and thebayesplotpackagevignettes demonstratevarious visualizations of these diagnostics that can be made inR.

References

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

Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo.https://arxiv.org/abs/1701.02434.

Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., and Gelman, A. (2018). Visualization in Bayesian workflow.Journal of the Royal Statistical Society Series A, accepted for publication.arXiv preprint: https://arxiv.org/abs/1709.01449.

Examples

## Not run: schools <- stan_demo("eight_schools")check_hmc_diagnostics(schools)check_divergences(schools)check_treedepth(schools)check_energy(schools)## End(Not run)

Expose user-defined Stan functions toR for testing and simulation

Description

The Stan modeling language allows users to define their own functions in afunctions block at the top of a Stan program. Theexpose_stan_functions utility function usessourceCpp to export those user-defined functionsto the specified environment for testing insideR or for doing posteriorpredictive simulations inR rather than in thegenerated quantities block of a Stan program.

Usage

  expose_stan_functions(stanmodel, includes = NULL,                         show_compiler_warnings = FALSE, ...)  get_rng(seed = 0L)  get_stream()

Arguments

Details

Theexpose_stan_functions function requires as much compliance withthe C++14 standard as is implemented in the RTools toolchain for Windows.On Windows, you will likely need to specifyCXX14 = g++ -std=c++1yin the file whose path isnormalizePath("~/.R/Makevars") inorder forexpose_stan_functions to work. Outside of Windows, thenecessary compiler flags are set programatically, which is likely to suffice.

There are a few special types of user-defined Stan functions for which some additional details are relevant:

(P)RNG functions

If a user-defined Stan function ends in_rng, then it canuse the Boost pseudo-random number generator used by Stan. When exposingsuch functions toR,base_rng__ andpstream__ arguments will be added to theformals. Thebase_rng__ argument shouldbe passed the result of a call toget_rng (perhaps specifying itsseed argument for reproducibility) and thepstream__ shouldbe passed the result of a call toget_stream, which can be used tosee the result ofprint andreject calls in the user-definedStan functions. These arguments default toget_stream() andget_rng() respectively.

LP functions

If a user-defined Stan function ends in_lp, then it canmodify the log-probability used by Stan to evaluate Metropolisproposals or as an objective function for optimization. When exposingsuch functions toR, alp__ argument will be added to theformals. Thislp__ argument defaults to zero, but adouble precision scalar may be passed to this argument when the function is called fromR. Such a user-defined Stan function can terminate withreturn target(); or can executeprint(target()); to verify that the calculation is correct.

Value

The names of the new functions inenv are returned invisibly.

See Also

sourceCpp and the section in the Stan User Manual onuser-defined functions

Examples

## Not run: model_code <-  '  functions {    real standard_normal_rng() {      return normal_rng(0,1);   }  }'expose_stan_functions(stanc(model_code = model_code))standard_normal_rng()PRNG <- get_rng(seed = 3)o <- get_stream()standard_normal_rng(PRNG, o)## End(Not run)

Extract samples from a fitted Stan model

Description

Extract samples from a fitted model represented by an instance of classstanfit.

Usage

  ## S4 method for signature 'stanfit'extract(object, pars, permuted = TRUE, inc_warmup = FALSE,   include = TRUE)

Arguments

Value

Whenpermuted = TRUE, this function returns a named list, every element of which is an array representing samples for a parameterwith all chains merged together.

Whenpermuted = FALSE, an array is returned; the firstdimension is for the iterations, the second for the number of chains, the third for the parameters. Vectors and arrays are expanded to one parameter (a scalar) per cell, with names indicating the third dimension.See the examples (with comments) below. Themonitor functioncan be applied to the returned array to obtain a summary (similar to theprint method forstanfit objects).

Methods

extract

signature(object = "stanfit")Extract samples from a fitted model represented by an instance of classstanfit.

See Also

S4 classstanfit,as.array.stanfit, andmonitor

Examples

## Not run: ex_model_code <- '  parameters {    array[2, 3] real alpha;    array[2] real beta;   }   model {    for (i in 1:2) for (j in 1:3)       alpha[i, j] ~ normal(0, 1);     for (i in 1:2)       beta ~ normal(0, 2);   } '## fit the model fit <- stan(model_code = ex_model_code, chains = 4) ## extract alpha and beta with 'permuted = TRUE' fit_ss <- extract(fit, permuted = TRUE) # fit_ss is a list ## list fit_ss should have elements with name 'alpha', 'beta', 'lp__'alpha <- fit_ss$alpha  beta <- fit_ss$beta ## or extract alpha by just specifying pars = 'alpha' alpha2 <- extract(fit, pars = 'alpha', permuted = TRUE)$alpha print(identical(alpha, alpha2)) ## or extract alpha by excluding beta and lp__alpha3 <- extract(fit, pars = c('beta', 'lp__'),                   permuted = TRUE, include = FALSE)$alphaprint(identical(alpha, alpha3))## get the samples for alpha[1,1] and beta[2] alpha_11 <- alpha[, 1, 1] beta_2 <- beta[, 2] ## extract samples with 'permuted = FALSE' fit_ss2 <- extract(fit, permuted = FALSE) # fit_ss2 is an array  ## the dimensions of fit_ss2 should be  ## "# of iterations * # of chains * # of parameters"dim(fit_ss2) ## since the third dimension of `fit_ss2` indicates ## parameters, the names should be ##  alpha[1,1], alpha[2,1], alpha[1,2], alpha[2,2], ##  alpha[1,3], alpha[2,3], beta[1], beta[2], and lp__ ## `lp__` (the log-posterior) is always included ## in the samples.  dimnames(fit_ss2) ## 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 {    array[20] real y;    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))ee1 <- extract(exfit, permuted = TRUE)print(names(ee1))for (name in names(ee1)) {  cat(name, "\n")  print(dim(ee1[[name]]))}ee2 <- extract(exfit, permuted = FALSE)print(dim(ee2))print(dimnames(ee2))

Extract the compressed representation of a sparse matrix

Description

Create a list of vectors that represents a sparse matrix.

Usage

extract_sparse_parts(A)

Arguments

Details

The Stan Math Library has a function calledcsr_matrix_times_vector,which inputs a matrix in compressed row storage form and a dense vector andreturns their product without fillin. To use thecsr_matrix_times_vector function with a largesparse matrix, it is optimal in terms of memory to simply pass the three vectorsthat characterize the compressed row storage form of the matrix to thedata block of the Stan program. Theextract_sparse_parts function provides a convenient means of obtaining these vectors.

Value

A named list with components

1. w A numeric vector containing the non-zero elements ofA.

2. v An integer vector containing the column indices of the non-zeroelements ofA.

3. u An integer vector indicating where inw a given row'snon-zero values start.

Examples

  A <- rbind(    c(19L, 27L,  0L,  0L),    c( 0L,  0L,  0L,  0L),    c( 0L,  0L,  0L, 52L),    c(81L,  0L, 95L, 33L)  )  str(extract_sparse_parts(A))

Draw samples of generated quantities from a Stan model

Description

Draw samples from the generated quantities block of astanmodel.

Usage

  ## S4 method for signature 'stanmodel'gqs(object, data = list(), draws,     seed = sample.int(.Machine$integer.max, size = 1L))

Arguments

Value

An object of S4 classstanmodel representingthe fitted results.

Methods

object

signature(object = "stanmodel") Evaluate the generated quantities block of a Stan programby supplyingdata and thedraws output from aprevious Stan program.

See Also

stanmodel,stanfit,stan

Examples

## Not run: m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')f <- sampling(m, iter = 300)mc <-'parameters {real y;}generated quantities {real y_rep = normal_rng(y, 1);}'m2 <- stan_model(model_code = mc)f2 <- gqs(m2, draws = as.matrix(f))f2## End(Not run)

log_prob andgrad_log_prob functions

Description

Using model'slog_prob andgrad_log_prob take values from theunconstrained space of model parameters and (by default) return values in the same space. Sometimes we need to convert the values of parameters from their support defined in the parameters block (which might be constrained, and for simplicity, we call it the constrained space) to the unconstrained space and vice versa. Theconstrain_pars andunconstrain_pars functions are used for this purpose.

Usage

    ## S4 method for signature 'stanfit'log_prob(object, upars, adjust_transform = TRUE, gradient = FALSE)    ## S4 method for signature 'stanfit'grad_log_prob(object, upars, adjust_transform = TRUE)    ## S4 method for signature 'stanfit'get_num_upars(object)    ## S4 method for signature 'stanfit'constrain_pars(object, upars)    ## S4 method for signature 'stanfit'unconstrain_pars(object, pars)

Arguments

Details

Stan requires that parameters be defined along with their support.For example, for a variance parameter, we must define it on the positive real line. But inside Stan's samplers all parametersdefined on the constrained space are transformed to an unconstrainedspace amenable to Hamiltonian Monte Carlo. Because of this, Stan adjusts the log density function by adding the log absolute value of the Jacobian determinant. Once a new iteration is drawn, Stan transforms the parameters back to the original constrained space withoutrequiring interference from the user. However, when using the log density function for a model exposed to R, we need to be careful.For example, if we are interested in finding the mode of parameters on the constrained space, we then do not need the adjustment. For this reason, thelog_prob andgrad_log_prob functions accept anadjust_transform argument.

Value

log_prob returns a value (up to an additive constant) the log posterior. Ifgradient isTRUE, the gradients are also returned as anattribute with namegradient.

grad_log_prob returns a vector of the gradients. Additionally, the vectorhas an attribute namedlog_prob being the value the same aslog_probis called for the input parameters.

get_num_upars returns the number of parameters on the unconstrained space.

constrain_pars returns a list andunconstrain_pars returns a vector.

Methods

log_prob

signature(object = "stanfit")Computelp__, the log posterior (up to an additive constant)for the model represented by astanfit object. Note that,by default,log_prob returns the log posterior in theunconstrained space Stan works in internally.setadjust_transform = FALSE to make the values match Stan's output.

grad_log_prob

signature(object = "stanfit") Compute the gradientsforlog_prob as well as the log posterior. The latter is returned as an attribute.

get_num_upars

signature(object = "stanfit") Get the numberof unconstrained parameters.

constrain_pars

signature(object = "stanfit") Convert valuesof the parameter from unconstrained space (given as a vector) to theirconstrained space (returned as a named list).

unconstrain_pars

signature(object = "stanfit") Contrary toconstrained, conert values of the parameters from constrainedto unconstrained space.

References

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

See Also

stanfit

Examples

## Not run: # see the examples in the help for stanfit as well# do a simple optimization problem opcode <- "parameters {  real y;}model {  target += log(square(y - 5) + 1);}"opfit <- stan(model_code = opcode, chains = 0)tfun <- function(y) log_prob(opfit, y)tgrfun <- function(y) grad_log_prob(opfit, y)or <- optim(1, tfun, tgrfun, method = 'BFGS')print(or)# return the gradient as an attributetfun2 <- function(y) {   g <- grad_log_prob(opfit, y)   lp <- attr(g, "log_prob")  attr(lp, "gradient") <- g  lp} or2 <- nlm(tfun2, 10)or2 ## End(Not run)

Approximate leave-one-out cross-validation

Description

Aloo method that is customized for stanfit objects.Theloo method for stanfit objects —a wrapper around thearraymethod forloo in theloo package — computes PSIS-LOO CV,approximate leave-one-out cross-validation using Pareto smoothed importancesampling (Vehtari, Gelman, and Gabry, 2017a,2017b).

Usage

  ## S3 method for class 'stanfit'loo(x,    pars = "log_lik",    save_psis = FALSE,    cores = getOption("mc.cores", 1),    moment_match = FALSE,    k_threshold = 0.7,    ...)

Arguments

Details

Stan does not automatically compute and store the log-likelihood. Itis up to the user to incorporate it into the Stan program if it is to beextracted after fitting the model. In a Stan program, the pointwise loglikelihood can be coded as a vector in the transformed parameters block(and then summed up in the model block) or it can be coded entirely in thegenerated quantities block. We recommend using the generated quantitiesblock so that the computations are carried out only once per iterationrather than once per HMC leapfrog step.

For example, the following is thegenerated quantities block forcomputing and saving the log-likelihood for a linear regression model withN data points, outcomey, predictor matrixX (includingcolumn of 1s for intercept), coefficientsbeta,and standard deviationsigma:

vector[N] log_lik;

for (n in 1:N) log_lik[n] = normal_lpdf(y[n] | X[n, ] * beta, sigma);

This function automatically uses Pareto k diagnostics for assessingthe accuracy of importance sampling for each observation. When thediagnostics indicate that importance sampling for certain observationsis inaccurate, a moment matching algorithm can be used, which canimprove the accuracy (Paananen et al., 2020).

Value

A list with classc("psis_loo", "loo"), as detailed in theloo documentation.

References

Vehtari, A., Gelman, A., and Gabry, J. (2017a).Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC.Statistics and Computing. 27(5), 1413-1432.doi:10.1007/s11222-016-9696-4.https://arxiv.org/abs/1507.04544,https://link.springer.com/article/10.1007/s11222-016-9696-4

Vehtari, A., Gelman, A., and Gabry, J. (2017b).Pareto smoothed importance sampling. arXiv preprint:https://arxiv.org/abs/1507.02646

Yao, Y., Vehtari, A., Simpson, D., and Gelman, A. (2018).Using stacking to average Bayesian predictive distributions.Bayesian Analysis, advance publication,doi:10.1214/17-BA1091.

Paananen, T., Piironen, J., Buerkner, P.-C., Vehtari, A. (2020).Implicitly Adaptive Importance Sampling.arXiv preprint:https://arxiv.org/abs/1906.08850.

See Also

• Theloo package documentation, including the vignettes formany examples (https://mc-stan.org/loo/).

• loo_moment_match for the moment matching algorithm.

• loo_model_weights for model averaging/weighting viastacking or pseudo-BMA weighting.

Examples

## Not run: # Generate a dataset from N(0,1)N <- 100y <- rnorm(N, 0, 1)# Suppose we have three models for y:#  1) y ~ N(-1, sigma)#  2) y ~ N(0.5, sigma)#  3) y ~ N(0.6,sigma)#stan_code <- "data {  int N;  vector[N] y;  real mu_fixed;}  parameters {  real<lower=0> sigma;}model {  sigma ~ exponential(1);  y ~ normal(mu_fixed, sigma);}generated quantities {  vector[N] log_lik;  for (n in 1:N) log_lik[n] = normal_lpdf(y[n]| mu_fixed, sigma);}"mod <- stan_model(model_code = stan_code)fit1 <- sampling(mod, data=list(N=N, y=y, mu_fixed=-1))fit2 <- sampling(mod, data=list(N=N, y=y, mu_fixed=0.5))fit3 <- sampling(mod, data=list(N=N, y=y, mu_fixed=0.6))# use the loo method for stanfit objectsloo1 <- loo(fit1, pars = "log_lik")print(loo1)# which is equivalent toLL <- as.array(fit1, pars = "log_lik")r_eff <- loo::relative_eff(exp(LL))loo1b <- loo::loo.array(LL, r_eff = r_eff)print(loo1b)# compute loo for the other modelsloo2 <- loo(fit2)loo3 <- loo(fit3)# stacking weightswts <- loo::loo_model_weights(list(loo1, loo2, loo3), method = "stacking")print(wts)# use the moment matching for loo with a stanfit objectloo_mm <- loo(fit1, pars = "log_lik", moment_match = TRUE)print(loo_mm)## End(Not run)

Moment matching for efficient approximate leave-one-out cross-validation (LOO)

Description

Aloo_moment_match method thatis customized for stanfit objects.Theloo_moment_match method for stanfit objects —a wrapper around theloo_moment_match (loo package)— updatesa loo object using moment matching (Paananen et al., 2020).

Usage

## S3 method for class 'stanfit'loo_moment_match(x,    loo = loo,    ...)

Arguments

Value

Theloo_moment_match() methods return an updatedloo object.

References

Paananen, T., Piironen, J., Buerkner, P.-C., Vehtari, A. (2020).Implicitly Adaptive Importance Sampling.preprint arXiv:1906.08850

See Also

loo(),loo_moment_match()

Look up the Stan function that corresponds to aR function or name.

Description

This function helps to map between R functions and Stan functions.

Usage

  lookup(FUN, ReturnType = character())

Arguments

Value

Ordinarily, a data.frame with rows equal to the number of partial matches and four columns:

1. StanFunction Character string for the Stan function's name.

2. Arguments Character string indicating the arguments to that Stan function.

3. ReturnType Character string indicating the return type of that Stan function.

4. Page Integer indicating the page of the Stan reference manual where that Stan function is defined.

If there are no matching Stan functions, a character string indicating so is returned.

References

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

The Stan Development TeamCmdStan Interface User's Guide.https://mc-stan.org.

Examples

lookup(dnorm)      # Stan equivalents for the normal PDF (in log form)lookup("foo")      # failslookup("Student")  # succeeds even though there is no such R functionlookup("^poisson") # every Stan function that starts with poisson

Obtain the full path of fileMakeconf

Description

Obtain the full path of fileMakeconf, in which, for examplethe flags for compiling C/C++ code are configured.

Usage

makeconf_path()

Details

The configuration for compiling shared objects usingR CMD SHLIB are set in fileMakeconf. To change how the C++ code iscompiled, modify this file. For RStan, packageinline compiles the C++ code usingR CMD SHLIB. To speed up compiledStan models, increase the optimization level to-O3 definedin propertyCXXFLAGS in the fileMakeconf.This file may also be modified to specify alternative C++ compilers,such as clang++ or later versions of g++.

Value

An character string for the full path of fileMakeconf.

See Also

stan

Examples

makeconf_path()

Compute summaries of MCMC draws and monitor convergence

Description

Similar to theprint method forstanfit objects, butmonitortakes an array of simulations as its argument rather than astanfitobject. For a 3-D array (iterations * chains * parameters) of MCMC draws,monitor computes means, standard deviations, quantiles, Monte Carlo standard errors, split Rhats, and effective sample sizes. By default, half of the iterations are considered warmup and are excluded.

Usage

monitor(sims, warmup = floor(dim(sims)[1]/2),         probs = c(0.025, 0.25, 0.5, 0.75, 0.975),         digits_summary = 1, print = TRUE, ...)## S3 method for class 'simsummary'print(x, digits = 3, se = FALSE, ...)## S3 method for class 'simsummary'x[i, j, drop = if (missing(i)) TRUE else length(j) == 1]

Arguments

Value

A 2-D array with rows corresponding to parameters and columns to the summary statistics that can be printed and subset.

References

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

See Also

S4 classstanfit and particularly itsprint method.

Examples

csvfiles <- dir(system.file('misc', package = 'rstan'),                pattern = 'rstan_doc_ex_[0-9].csv', full.names = TRUE)fit <- read_stan_csv(csvfiles)# The following is just for the purpose of giving an example# since print can be used for a stanfit object.monitor(extract(fit, permuted = FALSE, inc_warmup = TRUE))

Created named lists

Description

Create a named list using specified names or, if names are omitted, using the names of the objects in the list. The code ]list(a = a, b = b) becomesnlist(a,b) andlist(a = a, b = 2) becomesnlist(a, b = 2), etc. This is convenient when creating the list of data to pass to Stan.

Usage

  nlist(...)

Arguments

Value

A named list.

Examples

# All variables already definedx <- 1y <- 2nlist(x, y)# Define some variables in the call and take the rest from the environmentnlist(x, y, z = 3)

Obtain a point estimate by maximizing the joint posterior

Description

Obtain a point estimate by maximizing the joint posterior from the model defined by classstanmodel.

Usage

    ## S4 method for signature 'stanmodel'optimizing(object, data = list(),     seed = sample.int(.Machine$integer.max, 1), init = 'random',     check_data = TRUE, sample_file = NULL,     algorithm = c("LBFGS", "BFGS", "Newton"),    verbose = FALSE, hessian = FALSE, as_vector = TRUE,     draws = 0, constrained = TRUE, importance_resampling = FALSE, ...)

Arguments

Value

A list with components:

If the optimization is not completed for reasons such as feeding wrong data,it returnsNULL.

Methods

optimizing

signature(object = "stanmodel")Call Stan's optimization methods to obtain a point estimate for the model defined by S4 classstanmodel given the data, initial values, etc.

See Also

stanmodel

Examples

## Not run: m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')f <- optimizing(m, hessian = TRUE)## End(Not run)

Create a matrix of output plots from astanfit object

Description

Apairs method that is customized for MCMC output

Usage

  ## S3 method for class 'stanfit'pairs(x, labels = NULL, panel = NULL, ...,     lower.panel = NULL,     upper.panel = NULL, diag.panel = NULL, text.panel = NULL,     label.pos = 0.5 + 1/3, cex.labels = NULL, font.labels = 1,     row1attop = TRUE, gap = 1, log = "", pars = NULL, include = TRUE,    condition = "accept_stat__")

Arguments

Details

This method differs from the defaultpairs method in the followingways. If unspecified, thesmoothScatter function is used for theoff-diagonal plots, rather thanpoints, since the former is moreappropriate for visualizing thousands of draws from a posterior distribution.Also, if unspecified, histograms of the marginal distribution of each quantityare placed on the diagonal of the plot, after pooling all of the chains specifiedby thechain\_id argument.

The draws from the warmup phase are always discarded before plotting.

By default, the lower (upper) triangle of the plot contains draws with below(above) median acceptance probability. Also, ifcondition is not"divergent__", red points will be superimposed onto the smootheddensity plots indicating which (if any) iterations encountered a divergent transition. Otherwise, yellow points indicate a transition that hit themaximum treedepth rather than terminated its evolution normally.

You may very well want to specify thelog argument for non-negativeparameters. However, thepairs function will drop (with a message)parameters that are either constant or duplicative with previous parameters.For example, if a correlation matrix is included amongpars, then neither its diagonal elements (which are always 1) nor its upper triangularelements (which are the same as the corresponding lower triangular elements)will be included. Thus, iflog is an integer vector, it needs topertain to the parameters after constant and duplicative ones are dropped.It is perhaps easiest to specifylog = TRUE, which will utilizelogarithmic axes for all non-negative parameters, exceptlp__ andany integer valued quantities.

See Also

S4 classstanfit and its methodextract aswell as thepairs generic function. Also, seeget_sampler_params andget_logposterior.

Examples

example(read_stan_csv)pairs(fit, pars = c("mu", "sigma", "alpha", "lp__"), log = TRUE, las = 1)# sigma and alpha will have logarithmic axes

Plots for stanfit objects

Description

The default plot shows posterior uncertainty intervals and point estimates for parameters and generated quantities. Theplot method can also be used to call the otherrstan plotting functions via theplotfun argument (see Examples).

Usage

  ## S4 method for signature 'stanfit,missing'plot(x, ..., plotfun)

Arguments

Value

Aggplot object that can be further customizedusing theggplot2 package.

Note

Because therstan plotting functions useggplot2 (and thus the resulting plots behave likeggplot objects), when calling a plotting function within a loop or when assigning a plot to a name (e.g.,graph <- plot(fit, plotfun = "rhat")),if you also want the side effect of the plot being displayed you must explicity print it (e.g.,(graph <- plot(fit, plotfun = "rhat")),print(graph <- plot(fit, plotfun = "rhat"))).

See Also

List of RStan plotting functions,Plot options

Examples

## Not run: library(rstan)fit <- stan_demo("eight_schools")plot(fit)plot(fit, show_density = TRUE, ci_level = 0.5, fill_color = "purple")plot(fit, plotfun = "hist", pars = "theta", include = FALSE)plot(fit, plotfun = "trace", pars = c("mu", "tau"), inc_warmup = TRUE)plot(fit, plotfun = "rhat") + ggtitle("Example of adding title to plot")## End(Not run)

Print a summary for a fitted model represented by astanfit object

Description

Print basic information regarding the fitted model and a summary for the parameters of interest estimated by the samples includedin astanfit object.

Usage

  ## S3 method for class 'stanfit'print(x, pars = x@sim$pars_oi,       probs = c(0.025, 0.25, 0.5, 0.75, 0.975),      digits_summary = 2, include = TRUE, ...)

Arguments

Details

The information regarding the fitted model includes the number of iterations,the number of chains, the total number of saved iterations, the estimation algorithm used, and the timestamp indicating when sampling finished.

The parameter summaries computed include means, standard deviations (sd), quantiles, Monte Carlo standard errors (se_mean), split Rhats, and effective sample sizes (n_eff). The summaries are computed after dropping the warmup iterations and merging together the draws from all chains.

In addition to the model parameters, summaries for the log-posterior (lp__) are also reported.

See Also

S4 classstanfit and particularly its methodsummary, which is used to obtain the values that are printed.

Read data in anR dump file to a list

Description

Create anR list from anR dump file

Usage

read_rdump(f, keep.source = FALSE, ...)

Arguments

Details

TheR dump file can be read directly byR functionsource, whichby default would read the data into the user's workspace (the global environment). This function instead read the data to a list, making it convenient to prepare data for thestan model-fitting function.

Value

A list containing all the data defined in the dump file withkeys corresponding to variable names.

See Also

stan_rdump;dump

Examples

x <- 1; y <- 1:10; z <- array(1:10, dim = c(2,5)) stan_rdump(ls(pattern = '^[xyz]'), file.path(tempdir(), "xyz.Rdump"))l <- read_rdump(file.path(tempdir(), 'xyz.Rdump'))print(l)unlink(file.path(tempdir(), "xyz.Rdump"))

Read CSV files of samples generated by (R)Stan into astanfit object

Description

Create astanfit object from the saved CSV files that arecreated by Stan or RStan and that include the samples drawn from thedistribution of interest to facilitate analysis of samples using RStan.

Usage

read_stan_csv(csvfiles, col_major = TRUE)

Arguments

Details

Stan and RStan could save the samples to CSV files. This functionreads the samples and using the comments (beginning with"#")to create astanfit object. The model name is derived from the first CSV file.

col_major specifies how array parameters are ordered in each row ofthe CSV files. For example, parameter"a[2,2]" would be ordered as"a[1,1], a[2,1], a[1,2], a[2,2]" if col_major isTRUE.

Value

Astanfit object (with invalidstanmodel slot). Thisstanfitobject cannot be used to re-run the sampler.

See Also

stanfit

Examples

csvfiles <- dir(system.file('misc', package = 'rstan'),                pattern = 'rstan_doc_ex_[0-9].csv', full.names = TRUE)fit <- read_stan_csv(csvfiles)

Internal Functions and Methods

Description

These functions are not intended to be called directly. In the case ofmethods, they are documented elsewhere, either with the associated genericfunction or with the class of the object for which the method is defined.

RStan Plotting Functions

Description

List of RStan plotting functions that return ggplot objects

RStan plotting functions

Posterior intervals and point estimates

stan_plot

Traceplots

stan_trace

Histograms

stan_hist

Kernel density estimates

stan_dens

Scatterplots

stan_scat

Diagnostics for Hamiltonian Monte Carlo and the No-U-Turn Sampler

stan_diag

Rhat

stan_rhat

Ratio of effective sample size to total posterior sample size

stan_ess

Ratio of Monte Carlo standard error to posterior standard deviation

stan_mcse

Autocorrelation

stan_plot

See Also

Plot options

Create a Skeleton for a New Source Package with Stan Programs

Description

This function has been removed fromrstan. Please use the newrstan_package_skeleton function in therstantools package.

Set default appearance options

Description

Set default appearance options

Usage

  rstan_gg_options(...)    rstan_ggtheme_options(...)

Arguments

See Also

List of RStan plotting functions

Examples

rstan_ggtheme_options(panel.background = ggplot2::element_rect(fill = "gray"),                      legend.position = "top")rstan_gg_options(fill = "skyblue", color = "skyblue4", pt_color = "red")

Set and read options used in RStan

Description

Set and read options used in RStan. Some settings as options can be controlled by the user.

Usage

rstan_options(...)

Arguments

Details

The available options are:

1. plot_rhat_breaks: The cut off points for Rhat for which wewould indicate using a different color. This is a numeric vector,defaulting toc(1.1, 1.2, 1.5, 2).The value for this option will be sorted in ascending order,so for exampleplot_rhat_breaks = c(1.2, 1.5) is equivalent toplot_rhat_breaks = c(1.5, 1.2).

2. plot_rhat_cols: A vector of the same length asplot_rhat_breaks that indicates the colors for thebreaks.

3. plot_rhat_nan_col: The color for Rhat when it isInf orNaN.

4. plot_rhat_large_col: The color for Rhat when it is larger than the largest value ofplot_rhat_breaks.

5. rstan_alert_col: The color used in methodplotof S4 classstanfit to show that the vector/arrayparameters are truncated.

6. rstan_chain_cols: The colors used in methodsplotandtraceplot of S4 classstanfit for coloring different chains.

7. rstan_warmup_bg_col: The background color for the warmup area in the traceplots.

8. boost_lib: The path for the Boost C++ library usedto compile Stan models. This option is valid for the wholeR session if not changed again.

9. eigen_lib: The path for the Eigen C++ library usedto compile Stan models. This option is valid for the wholeR session if not changed again.

10. auto_write: A logical scalar (defaulting toFALSE) thatcontrols whether a compiled instance of astanmodel-classis written to the hard disk in the same directory as the.stanprogram.

11. threads_per_chain: A positive integer (defaulting to1).If the model was compiled with threading support, the number ofthreads to use in parallelized sections _within_ an MCMC chain (e.g., whenusing the Stan functions 'reduce_sum()' or 'map_rect()'). The actual number of CPU coresused is 'chains * threads_per_chain' where 'chains' is the number of parallel chains.For an example of using threading, see the Stan case study [Reduce Sum: A MinimalExample](https://mc-stan.org/users/documentation/case-studies/reduce_sum_tutorial.html).

Value

The values as alist for existing options andNA for non-existent options.When only one option is specified, its old value is returned.

Draw samples from a Stan model

Description

Draw samples from the model defined by classstanmodel.

Usage

    ## S4 method for signature 'stanmodel'sampling(object, data = list(), pars = NA,     chains = 4, iter = 2000, warmup = floor(iter/2), thin = 1,    seed = sample.int(.Machine$integer.max, 1),     init = 'random', check_data = TRUE,     sample_file = NULL, diagnostic_file = NULL, verbose = FALSE,     algorithm = c("NUTS", "HMC", "Fixed_param"),    control = NULL, include = TRUE,     cores = getOption("mc.cores", 1L),    open_progress = interactive() && !isatty(stdout()) &&                    !identical(Sys.getenv("RSTUDIO"), "1"),    show_messages = TRUE, ...)

Arguments

Value

An object of S4 classstanfit representingthe fitted results. Slotmode for this objectindicates if the sampling is done or not.

Methods

sampling

signature(object = "stanmodel")Call a sampler (NUTS, HMC, or Fixed_param depending on parameters) to draw samples from the model defined by S4 classstanmodel given the data, initial values, etc.

See Also

stanmodel,stanfit,stan

Examples

## Not run: m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')f <- sampling(m, iter = 100)## End(Not run)

Simulation Based Calibration (sbc)

Description

Check whether a model is well-calibrated with respect to theprior distribution and hence possibly amenable to obtaininga posterior distribution conditional on observed data.

Usage

  sbc(stanmodel, data, M, ..., save_progress, load_incomplete=FALSE)  ## S3 method for class 'sbc'plot(x, thin = 3, ...)  ## S3 method for class 'sbc'print(x, ...)

Arguments

Details

This function assumes adherence to the following conventions in theunderlying Stan program:

1. Realizations of the unknown parameters are drawn in thetransformed datablock of the Stan program and are postfixed with an underscore, such astheta_. These are considered the “true” parameters being estimated bythe corresponding symbol declared in theparameters block, whichshould have the same name except for the trailing underscore, such astheta.

2. The realizations of the unknown parameters are then conditioned on when drawing fromthe prior predictive distribution, also in thetransformed data block.There is no restriction on the symbol name that holds the realizations fromthe prior predictive distribution but for clarity, it should not end witha trailing underscore.

3. The realizations of the unknown parameters should be copied into avectorin thegenerated quantities block namedpars_.

4. The realizations from the prior predictive distribution should be copiedinto an object (of the same type) in thegenerated quantities blocknamedy_. Technically, this step is optional and could be omittedto conserve RAM, but inspecting the realizations from the prior predictive distributionis a good way to judge whether the priors are reasonable.

5. Thegenerated quantities block must contain an integer array namedranks_ whose only values are zero or one, depending on whether the realization of aparameter from the posterior distribution exceeds the corresponding “true”realization, such astheta > theta_;. These are not actually "ranks"but can be used afterwards to reconstruct (thinned) ranks.

6. Thegenerated quantities block may contain a vector namedlog_likwhose values are the contribution to the log-likelihood by each observation. Thisis optional but facilitates calculating Pareto k shape parameters to judge whetherthe posterior distribution is sensitive to particular observations.

Although the user can pass additional arguments tosampling through the ...,the following arguments are hard-coded and should not be passed through the ...:

1. pars = "ranks_" because nothing else needs to be stored for each posterior draw

2. include = TRUE to ensure that"ranks_" is included rather than excluded

3. chains = 1 because only one chain is run for each integer less thanM

4. seed because a sequence of seeds is used across theM runs to preserveindependence across runs

5. save_warmup = FALSE because the warmup realizations are not relevant

6. thin = 1 because thinning can and should be done after the Markov Chain isfinished, as is done by thethin argument to theplot method in order tomake the histograms consist of approximately independent realizations

Other arguments will take the default values used bysampling unlesspassed through the .... Specifyingrefresh = 0 is recommended to avoid printinga lot of intermediate progress reports to the screen. It may be necessary to pass alist to thecontrol argument ofsampling with elementsadapt_deltaand / ormax_treedepth in order to obtain adequate results.

Ideally, users would want to see the absence of divergent transitions (which is shownby theprint method) and other warnings, plus an approximately uniform histogramof the ranks for each parameter (which are shown by theplot method). See thevignette for more details.

Value

Thesbc function outputs a list of S3 class"sbc", which contains thefollowing elements:

1. ranks A list ofM matrices, each with number ofrows equal to the number of saved iterations and number of columns equal tothe number of unknown parameters. These matrices contain the realizationsof theranks_ object from thegenerated quantities block of theStan program.

2. Y If present, a matrix of realizations from the prior predictivedistribution whose rows are equal to the number of observations and whose columnsare equal toM, which are taken from they_ object in thegenerated quantities block of the Stan program.

3. pars A matrix of realizations from the prior distribution whose rowsare equal to the number of parameters and whose columns are equal toM,which are taken from thepars_ object in thegenerated quantitiesblock of the Stan program.

4. pareto_k A matrix of Pareto k shape parameter estimates orNULLif there is nolog_lik symbol in thegenerated quantities blockof the Stan program

5. sampler_params A three-dimensional array that results from combiningcalls toget_sampler_params for each oftheM runs. The resulting matrix has rows equal to the number ofpost-warmup iterations, columns equal to six, andM floors. The columnsare named"accept_stat__","stepsize__","treedepth__","n_leapfrog__","divergent__", and"energy__". The mostimportant of which is"divergent__", which should be all zeros andperhaps"treedepth__", which should only rarely get up to the valueofmax_treedepth passed as an element of thecontrol listtosampling or otherwise defaults to10.

Theprint method outputs the number of divergent transitions andreturnsNULL invisibly.Theplot method returns aggplot objectwith histograms whose appearance can be further customized.

References

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

Talts, S., Betancourt, M., Simpson, D., Vehtari, A., and Gelman, A. (2018).Validating Bayesian Inference Algorithms with Simulation-Based Calibration.arXiv preprint arXiv:1804.06788.https://arxiv.org/abs/1804.06788

See Also

stan_model andsampling

Examples

scode <- "data {  int<lower = 1> N;  real<lower = 0> a;  real<lower = 0> b;}transformed data { // these adhere to the conventions above  real pi_ = beta_rng(a, b);  int y = binomial_rng(N, pi_);}parameters {  real<lower = 0, upper = 1> pi;}model {  target += beta_lpdf(pi | a, b);  target += binomial_lpmf(y | N, pi);}generated quantities { // these adhere to the conventions above  int y_ = y;  vector[1] pars_;  int ranks_[1] = {pi > pi_};  vector[N] log_lik;  pars_[1] = pi_;  for (n in 1:y) log_lik[n] = bernoulli_lpmf(1 | pi);  for (n in (y + 1):N) log_lik[n] = bernoulli_lpmf(0 | pi);}"

Defunct function to set the compiler optimization level

Description

This function returns nothing and does nothing except throw a warning. Seehttps://cran.r-project.org/doc/manuals/r-release/R-admin.html#Customizing-package-compilation for information on customizing the compiler options, but doing so should be unnecessary for normal useage.

Usage

  set_cppo(...)

Arguments

Value

An invisibleNULL

Merge a list of stanfit objects into one

Description

This function takes a list ofstanfit objects and returns aconsolidatedstanfit object. Thestanfit objects to be mergedneed to have the same configuration of iteration, warmup, and thin, besidesbeing from the same model. This could facilitate some parallel usage of RStan.For example, if we callstan by parallel and it returns a list ofstanfit objects, this function can be used to create onestanfitobject from the list.

Usage

  sflist2stanfit(sflist)

Arguments

Value

An S4 object ofstanfit consolidated from all the inputstanfitobjects.

Note

This function should be called in rare circumstances becausesampling has acores argument that allows multiplechains to be executed in parallel. However, if you need to depart from that,the best practice is to usesflist2stanfit on a list ofstanfitobjects created with the sameseed but differentchain_id (seeexample below). Using the same seed but different chain_id can make sure the random number generations for all chains are not correlated.

This function would do some check to see if thestanfit objects in the input list can be merged. But the check is not sufficient. So generally, it is theuser's responsibility to make sure the input is correct so that the mergingmakes sense.

The date in the newstanfit object is when it is merged.

get_seed function for the new consolidatedstanfit object only returnsthe seed used in the first chain of the new object.

The sampler such as NUTS2 that is displayed in the printout byprint is the sampler used for the first chain. Theprint method assumes the samplersare the same for all chains.

The includedstanmodel object, which includes the compiled model, in the newstanfit object is from the first element of the input list.

References

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

See Also

stan

Examples

## Not run: library(rstan)scode <- "data {  int<lower=1> N;} parameters {  array[N] real y1;  array[N] real y2; } model {  y1 ~ normal(0, 1);  y2 ~ double_exponential(0, 2);} "seed <- 123 # or any other integer foo_data <- list(N = 2)foo <- stan(model_code = scode, data = foo_data, chains = 1, iter = 1)f1 <- stan(fit = foo, data = foo_data, chains = 1, seed = seed, chain_id = 1) f2 <- stan(fit = foo, data = foo_data, chains = 2, seed = seed, chain_id = 2:3) f12 <- sflist2stanfit(list(f1, f2)) ## parallel stan call for unix-like OSlibrary(parallel)if (.Platform$OS.type == "unix") {sflist1 <-   mclapply(1:4, mc.cores = 2,            function(i) stan(fit = foo, data = foo_data, seed = seed,                     chains = 1, chain_id = i, refresh = -1))f3 <- sflist2stanfit(sflist1)}if (.Platform$OS.type == "windows") { # also works on non-WindowsCL <- makeCluster(2)clusterExport(cl = CL, c("foo_data", "foo", "seed")) sflist1 <- parLapply(CL, 1:4, fun = function(cid) {    require(rstan)  stan(fit = foo, data = foo_data, chains = 1,        iter = 2000, seed = seed, chain_id = cid)})fit <- sflist2stanfit(sflist1)print(fit)stopCluster(CL)} # end example for Windows ## End(Not run)

Fit a model with Stan

Description

Fit a model defined in the Stan modeling language andreturn the fitted result as an instance ofstanfit.

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

Details

Thestan function does all of the work of fitting a Stan model andreturning the results as an instance ofstanfit. The steps areroughly as follows:

1. Translate the Stan model to C++ code. (stanc)

2. Compile the C++ code into a binary shared object, whichis loaded into the currentR session (an objectof S4 classstanmodel is created). (stan_model)

3. Draw samples and wrap them in an object of S4 classstanfit. (sampling)

The returned object can be used with methods such asprint,summary, andplot to inspect and retrieve the results ofthe fitted model.

stan can also be used to sample again from a fitted model underdifferent settings (e.g., differentiter,data, etc.) byusing thefit argument to specify an existingstanfit object.In this case, the compiled C++ code for the model is reused.

Value

An object of S4 classstanfit. However, ifcores > 1and there is an error for any of the chains, then the error(s) are printed. Ifall chains have errors and an error occurs before or during sampling, the returnedobject does not contain samples. But the compiled binary object for themodel is still included, so we can reuse the returned object for anothersampling.

Passing data to Stan

The data passed tostan are preprocessed before being passed to Stan.Ifdata is not a character vector, the data block of the Stan programis parsed andR objects of the same name are searched starting from thecalling environment. Then, ifdata is list-like but not adata.framethe elements ofdata take precedence. This behavior is similar to howaformula is evaluated by thelm function whendata issupplied. In general, eachR object being passed to Stan should be either a numericvector (including the special case of a 'scalar') or a numeric array (matrix).The first exception is that an element can be a logical vector:TRUE'sare converted to 1 andFALSE's to 0.An element can also be a data frame or a specially structured list (seedetails below), both of which will be converted into arrays in thepreprocessing. Using a specially structured list is notencouraged though it might be convenient sometimes; and when in doubt, justuse arrays.

This preprocessing for each element mainly includes the following:

1. Change the data of type fromdoubletointeger if no accuracy is lost. The mainreason is that by default,R usesdoubleas data type such as ina <- 3. But Stanwill not read data of typeint fromrealand it reads data fromint if the datatype is declared asreal.

2. Check if there isNA in the data.Unlike BUGS, Stan does not allow missing data. AnyNA valuesin supplied data will cause the function to stop and report an error.

3. Check data types. Stan allows only numeric data, that is,doubles, integers, and arrays of these. Data of other types (forexample, characters and factors) are not passed to Stan.

4. Check whether there are objects in the data list with duplicated names.Duplicated names, if found, will cause the function to stop andreport an error.

5. Check whether the names of objects in the data list are legalStan names. If illegal names are found, it will stop andreport an error. See (Cmd)Stan's manual for the rules of variable names.

6. When an element is of typedata.frame, it will be converted tomatrix by functiondata.matrix.

7. When an element is of typelist, it is supposed to make iteasier to pass data for those declared in Stan code such as"vector[J] y1[I]" and"matrix[J,K] y2[I]". Using the latteras an example, we can use a list fory2 if the list has "I" elements,each of which is an array (matrix) of dimension "J*K". However, it isnot possible to pass a list for data declared such as"vector[K] y3[I,J]"; the only way for it is to use an array withdimension "I*J*K". In addition, technically adata.frame in R isalso a list, but it should not be used for the purpose here since adata.frame will be converted to a matrix as described above.

Stan treats a vector of length 1 in R as a scalar. So technicallyif, for example,"array[1] real y;" is defined in the data block, an arraysuch as"y = array(1.0, dim = 1)" in R should be used. Thisis also the case for specifying initial values since the sameunderlying approach for reading data from R in Stan is used, in whichvector of length 1 is treated as a scalar.

In general, the higher the optimization level is set, the faster thegenerated binary code for the model runs, which can be set in a Makevars file.However, the binary code generated for the model runs fast by using a higheroptimization level at the cost of longer times to compile the C++ code.

References

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

The Stan Development TeamCmdStan Interface User's Guide.https://mc-stan.org.

See Also

• The package vignettes for an example of fitting a model and accessingthe contents ofstanfit objects (https://mc-stan.org/rstan/articles/).

• stanc for translating model code in Stan modeling language to C++,sampling for sampling, andstanfit for thefitted results.

• as.array.stanfit andextract for extractingsamples fromstanfit objects.

Examples

## Not run: #### example 1library(rstan)scode <- "parameters {  array[2] real y;}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)## using as.array on the stanfit object to get samplesa2 <- as.array(fit2)## extract samples as a list of arrayse2 <- extract(fit2, permuted = FALSE)#### example 2#### the result of this package is included in the packageexcode <- '  transformed data {    array[20] real y;    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)## End(Not run)## Not run: ## 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 argumentsinitf1 <- 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 valuesn_chains <- 4init_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)## End(Not run)

Demonstrate examples included in Stan

Description

Stan includes a variety of examples and most of the BUGS example models that are translated into Stan modeling language. One example is chosen from a listcreated from matching user input and gets fitted in the demonstration.

Usage

  stan_demo(model = character(0),             method = c("sampling", "optimizing", "meanfield", "fullrank"), ...)

Arguments

Value

An S4 object ofstanfit, unlessmodel = 0, in which case a character vector of paths to available models is returned.

References

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

See Also

sampling,optimizing

Examples

  ## Not run:      dogsfit <- stan_demo("dogs") # run the dogs model     fit1 <- stan_demo(1) # run model_names[1]  ## End(Not run)

Construct a Stan model

Description

Construct an instance of S4 classstanmodel from a modelspecified in Stan's modeling language. Astanmodel objectcan then be used to draw samples from the model. The Stan program(the model expressed in the Stan modeling language) is first translated toC++ code and then the C++ code for the model plus other auxiliarycode is compiled into a dynamic shared object (DSO) and then loaded.The loaded DSO for the model can be executed to draw samples, allowinginference to be performed for the model and data.

Usage

  stan_model(    file, model_name = "anon_model",    model_code = "", stanc_ret = NULL,    boost_lib = NULL, eigen_lib = NULL,    save_dso = TRUE, verbose = FALSE,    auto_write = rstan_options("auto_write"),    obfuscate_model_name = TRUE,    allow_undefined = isTRUE(getOption("stanc.allow_undefined", FALSE)),    allow_optimizations = isTRUE(getOption("stanc.allow_optimizations", FALSE)),    standalone_functions = isTRUE(getOption("stanc.standalone_functions", FALSE)),    use_opencl = isTRUE(getOption("stanc.use_opencl", FALSE)),    warn_pedantic = isTRUE(getOption("stanc.warn_pedantic", FALSE)),    warn_uninitialized = isTRUE(getOption("stanc.warn_uninitialized", FALSE)),    includes = NULL,    isystem = c(if (!missing(file)) dirname(file), getwd()))

Arguments

Details

If a previously compiledstanmodel exists on the hard drive, its validityis checked and then returned without recompiling. The most common form ofinvalidity seems to be Stan code that ends with a} rather than a blankline, which causes the hash checker to think that the current model is differentthan the one saved on the hard drive. To avoid reading previouslycompiledstanmodels from the hard drive, supply thestanc_retargument rather than thefile ormodel_code arguments.

There are three ways to specify the model's code forstan_model:

1. parametermodel_code: a character string containing theStan model specification,

2. parameterfile: a file name (or a connection) fromwhich to read the Stan model specification, or

3. parameterstanc_ret: a list returned bystancto be reused.

Value

An instance of S4 classstanmodel that can bepassed to thesampling,optimizing, andvb functions.

References

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

See Also

stanmodel for details on the class.

sampling,optimizing, andvb,which take astanmodel object as input, for estimating the modelparameters.

More details on Stan, including the full user's guide and referencemanual, can be found athttps://mc-stan.org/.

Examples

## Not run: stancode <- 'data {real y_mean;} parameters {real y;} model {y ~ normal(y_mean,1);}'mod <- stan_model(model_code = stancode, verbose = TRUE)fit <- sampling(mod, data = list(y_mean = 0))fit2 <- sampling(mod, data = list(y_mean = 5))## End(Not run)

Dump the data for a Stan model toR dump filein the limited format that Stan can read.

Description

This function takes a vector of names ofR objects and outputstext representations of the objects to a file or connection.The file created bystan_rdump is typically used as data input of the Stan package (https://mc-stan.org/) orsourced into anotherR session. The usage of this function is very similar todump inR.

Usage

stan_rdump(list, file = "", append = FALSE,           envir = parent.frame(),          width = options("width")$width,           quiet = FALSE)

Arguments

Value

An invisible character vector containing the names of the objectsthat were dumped.

Note

stan_rdump only dumps numeric data, which first can be a scalar, vector, matrix, or (multidimensional) array. Additional typessupported arelogical (TRUE andFALSE),factor,data.frame and a specially structuredlist.

The conversion for logical variables is to mapTRUE to 1andFALSE to 0. Forfactor variable, functionas.integer is used to do the conversion (If we want to transform afactorf to approximately its original numeric values, see the help offunctionfactor and do the transformation before callingstan_rdump). In the case ofdata.frame, functiondata.matrix is applied to the data frame beforedumping. See the notes instan for the speciallystructuredlist, which will be converted toarray before dumping.

stan_rdump will check whether the names of objectsare legal variable names in Stan. If an illegal name is found, data will be dumped with a warning. However, passing the name checking does not necessarily mean that the name is legal. More details regarding rules of variable names in Stan canbe found in Stan's manual.

If objects with specified names are not found, a warning willbe issued.

References

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

See Also

dump

Examples

# set variables in global environmenta <- 17.5b <- c(1,2,3)# write variables a and b to file ab.data.R in temporary directorystan_rdump(c('a','b'), file.path(tempdir(), "ab.data.R"))unlink(file.path(tempdir(), "ab.data.R"))x <- 1; y <- 1:10; z <- array(1:10, dim = c(2,5)) stan_rdump(ls(pattern = '^[xyz]'), file.path(tempdir(), "xyz.Rdump"))cat(paste(readLines(file.path(tempdir(), "xyz.Rdump")), collapse = '\n'), '\n')unlink(file.path(tempdir(), "xyz.Rdump"))

Obtain the version of Stan

Description

The stan version is in form ofmajor.minor.patch; thefirst version is 1.0.0, indicating major version 1, minor version0 and patch level 0. Functionality only changes with minor versionsand backward compatibility will only be affected by major versions.

Usage

  stan_version()

Value

A character string giving the version of Stan used in this version of RStan.

References

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

See Also

stan andstan_model

Examples

  stan_version()

Translate Stan model specification to C++ code

Description

Translate a model specification in Stan code to C++ code, which canthen be compiled and loaded for sampling.

Usage

  stanc(    file, model_code = '', model_name = "anon_model", verbose = FALSE,    obfuscate_model_name = TRUE,    allow_undefined = isTRUE(getOption("stanc.allow_undefined", FALSE)),    allow_optimizations = isTRUE(getOption("stanc.allow_optimizations", FALSE)),    standalone_functions = isTRUE(getOption("stanc.standalone_functions", FALSE)),    use_opencl = isTRUE(getOption("stanc.use_opencl", FALSE)),    warn_pedantic = isTRUE(getOption("stanc.warn_pedantic", FALSE)),    warn_uninitialized = isTRUE(getOption("stanc.warn_uninitialized", FALSE)),    isystem = c(if (!missing(file)) dirname(file), getwd()))  stanc_builder(    file, isystem = c(dirname(file), getwd()),    verbose = FALSE, obfuscate_model_name = FALSE,    allow_undefined = isTRUE(getOption("stanc.allow_undefined", FALSE)),    allow_optimizations = isTRUE(getOption("stanc.allow_optimizations", FALSE)),    standalone_functions = isTRUE(getOption("stanc.standalone_functions", FALSE)),    use_opencl = isTRUE(getOption("stanc.use_opencl", FALSE)),    warn_pedantic = isTRUE(getOption("stanc.warn_pedantic", FALSE)),    warn_uninitialized = isTRUE(getOption("stanc.warn_uninitialized", FALSE)))

Arguments

Details

Thestanc_builder function supports the standard C++ convention ofspecifying something like#include "my_includes.txt" on an entire linewithin the file named by thefile argument. In other words,stanc_builder would look for"my_includes.txt" in (or under) thedirectories named by theisystem argument and — if found — insert itscontents verbatim at that position before callingstanc on the resultingmodel_code. This mechanism reduces the need to copy common chunks of codeacross Stan programs. It is possible to include such files recursively.

Note that line numbers referred to in parser warnings or errors refer to thepostprocessed Stan program rather thanfile. In the case of a parsererror, the postprocessed Stan program will be printed after the error message.Line numbers referred to in messages while Stan is executing also refer tothe postprocessed Stan program which can be obtained by callingget_stancode.

Value

A list with named entries:

1. model_name Character string for the model name.

2. model_code Character string for the model's Stan specification.

3. cppcode Character string for the model's C++ code.

4. status Logical indicating success/failure (alwaysTRUE)of translating the Stan code.

Note

UnlikeR, in which variable identifiers may contain dots (e.g.a.1),Stan prohibits dots from occurring in variable identifiers. Furthermore,C++ reserved words and Stan reserved words may not be used for variable names;see the Stan User's Guide for a complete list.

References

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

The Stan Development TeamCmdStan Interface User's Guide.https://mc-stan.org.

See Also

stan_model andstan

Examples

stanmodelcode <- "data {  int<lower=0> N;  array[N] real y;}parameters {  real mu;}model {  mu ~ normal(0, 10);  y ~ normal(mu, 1);}"r <- stanc(model_code = stanmodelcode, model_name = "normal1")str(r)

Classstanfit: fitted Stan model

Description

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

Objects from the Class

An object of classstanfit contains theoutput derived from fitting a Stan model as returned by the top-level functionstan or the lower-level methodssampling andvb (which are defined on classstanmodel).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 asnumeric(0).

mode:

An integer indicating the mode of the fitted model.0 indicates sampling mode,1 indicates test gradient mode (no sampling is done), and2 indicates error mode (an error occurredbefore sampling). Most methods forstanfit objects are useful only ifmode=0.

sim:

A list containing simulation results including the posterior draws as well as various pieces of metadata used by many of the methods forstanfit objects.

inits:

The initial values (either user-specified or generatedrandomly) for all chains. This is a list with one component per chain. Eachcomponent is a named list containing the initial values for each parameterfor 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 classstanmodel.

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 typeenvironment. 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. Seeprint.stanfit.

plot

Create various plots summarizing the fitted model. Seeplot,stanfit-method.

summary

Summarize the distributions of estimated parameters and derived quantities using the posterior draws. Seesummary,stanfit-method.

get_posterior_mean

Get the posterior mean for parameters of interest (usingparsto 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. Seeextract.

as.array,as.matrix,as.data.frame

Coerce the draws (without warmup) to an array, matrix or data frame. Seeas.array.stanfit.

As.mcmc.list

Convert astanfit object to anmcmc.list as in packagecoda. SeeAs.mcmc.list.

get_logposterior

Get the log-posterior at each iteration.Each element of the returnedlist is the vector of log-posteriorvalues (up to an additive constant, i.e. up to a multiplicative constant on the linear scale) for a single chain.The optional argumentinc_warmup (defaulting toTRUE) indicates whether to include the warmup period.

Diagnostics, log probability, and gradients:

get_sampler_params

Obtain the parameters used for the sampler such asstepsize andtreedepth. The results are returnedas a list with one component (an array) per chain.The array has number of columns corresponding to the numberof parameters used in the sampler and its column names provide the parameter names. Optional argumentinc_warmup (defaulting toTRUE) 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 theunconstrained 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 methodget_num_upars. A numeric value is returned. See alsothe documentation inlog_prob.

grad_log_prob

Compute the gradient of log probability density function for a set of parameter values (on theunconstrained space) up to an additive constant.The unconstrained parameters are specified using a numeric vectorwith 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 namedlog_prob beingthelp__. See also the documentation ingrad_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 isreturned. See also the documentation inunconstrain_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 tounconstrain_pars. See also the documentation inconstrain_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 usingcat.

get_stanmodel

Get the object of S4 classstanmodel 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 warmupand 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 theinits slot described above. Ifobject@mode=2 (error mode) an empty list is returned. Ifiter is notNULL, then the draw from thatiteration 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, useget_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 TeamStan Modeling Language User's Guide and Reference Manual.https://mc-stan.org.

See Also

stan andstanmodel

Examples

## Not run: showClass("stanfit")ecode <- '  parameters {    array[2] real<lower=0> y;  }   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 spacen <- 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 usedy1star <- 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 {    array[20] real y;    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) # emptyinits <- get_inits(exfit, iter = 101)seed <- get_seed(exfit)sp <- get_sampler_params(exfit)ml <- As.mcmc.list(exfit)cat(get_stancode(exfit))

Class representing model compiled from C++

Description

Astanmodel object represents the model compiled from C++ code. Thesampling method defined in this class may be used to draw samples from the model andoptimizing method is forobtaining a point estimate by maximizing the log-posterior.

Objects from the Class

Instances ofstanmodel are usually created by calling functionstan_model or functionstan.

Slots

model_name:

The model name, an object of typecharacter.

model_code:

The Stan model specification, an object of typecharacter.

model_cpp:

Object of typelistthat includes the C++ code for the model.

mk_cppmodule:

A function to return a RCpp module. This function will becalled in functionsampling andoptimzing with oneargument (the instance ofstanmodel itself).

dso:

Object of S4 classcxxdso. The container for the dynamic shared objects compiled from the C++ code of the model, returned from functioncxxfunction in packageinline.

Methods

show

signature(object = "stanmodel"): print the Stan model specification.

vb

signature(object = "stanmodel"): use the variational Bayes algorithms.

sampling

signature(object = "stanmodel"): draw samples forthe model (seesampling).

optimizing

signature(object = "stanmodel"): obtain a point estimate by maximizing the posterior (seeoptimizing).

get_cppcode

signature(object = "stanmodel"): returns the C++ code for the modelas a character string. This is part of the C++ code that is compiled to the dynamic shared object for the model.

get_stancode

signature(object = "stanmodel"): returns the Stan code forthe model as a character string

get_cxxflags

signature(object = "stanmodel"): return theCXXFLAGS used for compiling the model. The returned string is likeCXXFLAGS = -O3.

Note

Objects of classstanmodel can be saved for use acrossR sessions only ifsave_dso = TRUE is set during callingfunctions that createstanmodel objects (e.g.,stan andstan_model).

Even ifsave_dso = TRUE, the model cannot be loaded ona platform (operating system, 32 bits or 64 bits, etc.) that differs fromthe one on which it was compiled.

See Also

stan_model,stancsampling,optimizing,vb

Examples

showClass("stanmodel")

Summary method for stanfit objects

Description

Summarize the distributions of estimated parameters and derived quantities using the posterior draws.

Usage

  ## S4 method for signature 'stanfit'summary(object, pars, probs = c(0.025, 0.25, 0.50, 0.75, 0.975),  use_cache = TRUE, ...)

Arguments

Value

Thesummary method returns a named list with elementssummary andc_summary, which contain summaries for for all chains merged and individual chains, respectively.Included in the summaries are quantiles, means, standard deviations (sd),effective sample sizes (n_eff), and split Rhats (the potential scalereduction derived from all chains after splitting each chain in half andtreating the halves as chains). For the summary of all chains merged, Monte Carlo standard errors (se_mean) are also reported.

See Also

• monitor, which computes similar summaries but accepts an array of MCMC draws as its input rather than astanfit object.

• The RStan vignettes for more example usage.

Examples

## Not run: ecode <- '  parameters {    array[2] real<lower=0> y;  }   model {    y ~ exponential(1);  }'fit <- stan(model_code = ecode)s <- summary(fit, probs = c(0.1, 0.9))s$summary  # all chaines mergeds$c_summary  # individual chains## End(Not run)

Markov chain traceplots

Description

Draw the traceplot corresponding to one or moreMarkov chains, providing a visual way to inspect sampling behaviorand assess mixing across chains and convergence.

Usage

    ## S4 method for signature 'stanfit'traceplot(object, pars, include = TRUE, unconstrain = FALSE,           inc_warmup = FALSE, window = NULL, nrow = NULL, ncol = NULL, ...)

Arguments

Value

Aggplot object that can be further customizedusing theggplot2 package.

Methods

traceplot

signature(object = "stanfit") Plot the sampling paths for all chains.

See Also

List of RStan plotting functions,Plot options

Examples

## 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 {    array[20] real y;    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)traceplot(exfit)traceplot(exfit, size = 0.25)traceplot(exfit, pars = "sigma", inc_warmup = TRUE)trace <- traceplot(exfit, pars = c("z[1,1]", "z[3,1]"))trace + scale_color_discrete() + theme(legend.position = "top")## End(Not run)

Run Stan's variational algorithm for approximate posterior sampling

Description

Approximately draw from a posterior distribution using variational inference.

This is still considered an experimental feature.We recommend callingstan orsampling for final inferences and only usingvb to get a rough idea of the parameterdistributions.

Usage

    ## S4 method for signature 'stanmodel'vb(object, data = list(), pars = NA, include = TRUE,    seed = sample.int(.Machine$integer.max, 1),     init = 'random', check_data = TRUE,     sample_file = tempfile(fileext = '.csv'),    algorithm = c("meanfield", "fullrank"),     importance_resampling = FALSE, keep_every = 1,    ...)

Arguments

Value

An object ofstanfit-class.

Methods

vb

signature(object = "stanmodel")Call Stan's variational Bayes methodsfor the model defined by S4 classstanmodel given the data, initial values, etc.

References

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

The Stan Development TeamCmdStan Interface User's Guide.https://mc-stan.org.

See Also

stanmodel

The manuals of CmdStan and Stan.

Examples

## Not run: m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')f <- vb(m)## End(Not run)