Package Rstan'

Published on August 2022 | Categories: Documents | Downloads: 2 | Comments: 0 | Views: 58

of 50

Content

Package ‘rstan’ February Februar y 6, 2015 Type Package Title RStan: R interface to Stan Version 2.6.0 Date 2015-02-06 <[email protected]> >, Author Jiqiang Guo <[email protected] Michael Betancourt <[email protected]> <[email protected]>, Marcus Brubaker <[email protected] <[email protected]> o.edu>, Bob Carpenter <[email protected]>, Ben Goodrich <[email protected] <[email protected]> u>, Matt Hoffman <[email protected]> <[email protected]>, Daniel Lee <[email protected]> <[email protected]>, Peter Li <[email protected]> <[email protected]>, Mitzi Morris <[email protected]>, Rob Trangucci <robert.trangucci@ <[email protected]> gmail.com>, Andrew Gelman <[email protected]> <[email protected]>

Maintainer Jiqiang Guo <[email protected] <[email protected]> > Description R interface to Stan (Stan is an open-source package for obtaining Description R Bayesian inference using the No-U-Turn sampler, a variant of Hamiltonian Monte Carlo.) License GPL (>=3) Imports stats4 Depends R (>= 3.0.2), Rcpp (>= 0.9.10), utils, inline, methods LinkingTo Rcpp, RcppEigen, BH (>= 1.54) Suggests RUnit, RcppEigen, BH (>= 1.54), parallel, KernSmooth URL http://mc-stan.org

R

topics documented: rstan-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 as.array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 cppo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1

2

rstan-package

extract-methods . . . . . . . . . . . . . . . . . . . . . . log_prob-methods . . . . . . . . . . . . . . . . . . . . . makeconf_path . . . . . . . . . . . . . . . . . . . . . . monitor . . . . . . . . . . . . . . . . . . . . . . . . . . optimizing-methods . . . . . . . . . . . . . . . . . . . pairs.stanﬁt . . . . . . . . . . . . . . . . . . . . . . . . plot-methods . . . . . . . . . . . . . . . . . . . . . . . print . . . . . . . . . . . . . . . . . . . . . . . . . . . . read_rdump . . . . . . . . . . . . . . . . . . . . . . . . read_stan_csv . . . . . . . . . . . . . . . . . . . . . . rstan_options . . . . . . . . . . . . . . . . . . . . . . . sampling-methods . . . . . . . . . . . . . . . . . . . . . sﬂist2stanﬁt . . . . . . . . . . . . . . . . . . . . . . . . stan . . . . . . . . . . . . . . . . . . . . . . . . . . . . stanc . . . . . . . . . . . . . . . . . . . . . . . . . . . . stanﬁt-class . . . . . . . . . . . . . . . . . . . . . . . . stanmodel-class . . . . . . . . . . . . . . . . . . . . . . stan_demo . . . . . . . . . . . . . . . . . . . . . . . . . stan_model . . . . . . . . . . . . . . . . . . . . . . . . stan_rdump . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 10 13 13 15 17 18 20 21 22 23 24 26 28 34 36 40 41 42 44

st rt aa cne_pvleorts- imo ent h. o. d. s. .. .. .. . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..    46 46 Index

rstan-package

49

RStan — R interface to Stan

Description R

interface to Stan, which is a C++ package for obtaining Bayesian inference using the No-U-turn sampler, a variant of Hamiltonian Monte Carlo (see http://mc-stan.org/). Details Pack Packag age: e: Type: Version ersion:: Date: Li Lice cens nse: e:

rsta rstan n Package 2.6 2.6.0 .0 Oct 20, 2014 GP GPLL-3 3

The RStan package provides an interface to Stan. For more information on Stan and its modeling language, see the Stan Modeling Language User’s Guide and Reference Manual, which is available http://mc-stan.org/.

rstan-package

3

Author(s) Author: Auth or:

Jiqi Jiqiang ang Guo <guoj <guojq28@g q28@gmail mail.com> .com> Michael Betancourt <betanalpha@g <[email protected]> mail.com> Marcus Brubaker <[email protected]> Bob Carpenter <[email protected]> Ben Goodrich <[email protected]> Matt Hoffman <[email protected] <[email protected]> on.edu> Daniel Lee <[email protected]> <[email protected]> Peter Li <[email protected]> <[email protected]> Mitzi Morris <mitzi@pani <[email protected]> x.com> Rob Trangucci Trangucci <robert.tranguc <[email protected]> [email protected]> Andrew Gelman <gelman@stat <[email protected]> .columbia.edu>

Maintain Main tainer: er:

Jiqi Jiqiang ang Guo <guo <guojq28@ jq28@gmai gmail.com l.com> >

References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. See Also stan, stanfit

Examples ## Not Not run: run: library(rstan) cat("Stan cat("S tan versio version:", n:", stan_version( stan_version(), ), "\n") stanmodelcod stanmo delcode e <- " data data { int<lower=0> int<lo wer=0> N; real y[N]; } parameters { parameters real rea l mu; } model { model mu ~ nor normal mal(0, (0, 10); y ~ nor normal mal(mu (mu, , 1); }

4

as.array

" y <- rno rnorm( rm(20) 20) dat <- list(N = 20, y = y); fit <- stan(model_c stan(model_code ode = stanmo stanmodelcod delcode, e, model_name model_name = "example", "example", da data ta = da dat, t, it iter er = 20 2012 12, , chai chains ns = 3, sampl sample_ e_fi file le = norm.csv , 

print(fit)



verbos ver bose e = TRUE) TRUE)

# ext extrac ract t sam sample ples s e <- extr extrac act( t(fi fit, t, pe perm rmute uted d = TR TRUE UE) ) # re retu turn rn a li list st of ar arra rays ys mu <- e$mu e$mu m <- ext extrac ract(f t(fit, it, permuted permuted = FAL FALSE, SE, inc_warm inc_warmup up = FALSE) FALSE) # return return an array array print(dimnames(m)) # usi using ng as. as.arr array ay direct directly ly on stanfi stanfit t obj object ects s m2 <- as.arr as.array(fit ay(fit) )

## End(No End(Not t run run) )

as.array

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

Description The samples without warmup included in a stanfit object can be coerced to array, matrix, or data.frame

Usage ## S3 meth method od for for clas class s as.array(x, as.array( x, ...) ## S3 meth method od for for clas class s as.matrix(x, ...) ## S3 meth method od for for clas class s as.data.frame(x, ...) ## S3 meth method od for for clas class s is.array(x) ## S3 meth method od for for clas class s dim(x) ## S3 meth method od for for clas class s dimnames(x)









stanfit

stanfit

stanfit





stanfit













stanfit

stanfit

as.array

5

Arguments

x ...

An object of S4 class stanfit

Addit Additional ional param parameter eterss that can be passed passed to extract for extracting samples from stanfit object. For now, pars is the only additional parameter.

Details can n be ap appl plie ied d toa stanfit obj object ect to coerce coerce the sample sampless wit withou houtt war warmup mup as.array and as.matrix ca to array or matrix. The as.data.frame method ﬁrst calls as.matrix and then coerces this matrix to a data.frame. The array has three named named dimensions dimensions:: iterations, chains chains,, parameters. For as.matrix, all chains are combined, leaving a matrix of iterations by parameters. Value as.array, as.matrix, and as.data.frame return an array, matrix, or data.frame of samples respectively. dim and dimnames return the dim and dimnames of the array object that could be created. is.array returns TRUE for stanfit objects that include samples; otherwise FALSE.

When the stanfit object does not contain samples, empty objects are returned from as.array, as.matrix, as.data.frame, dim, and dimnames. See Also S4 class stanfit and its method extract Examples ## Not Not run: run: ex_model_cod ex_mod el_code e <parameters parame ters { real alpha[ alpha[2,3]; 2,3]; real beta[2 beta[2]; ]; } 

model { model for for (i in 1:2) 1:2) for (j in 1:3) 1:3) alpha[ alp ha[i, i, j] ~ normal( normal(0, 0, 1); for for (i in 1: 1:2) 2) beta[i bet a[i] ] ~ normal normal(0, (0, 2); # bet beta a ~ normal normal(0, (0, 2) // vector vectorize ized d ver versio sion n } 

## fit fit the the mo mode del l fit <- stan(m stan(mode odel_c l_code ode = ex_ ex_mod model_ el_cod code, e, chains chains = 4) dim(fit) dimnames(fit) is.array(fit)

6

cppo

a <- as.arr as.array(fit ay(fit) ) m <- as.mat as.matrix(fi rix(fit) t) d <- as.dat as.data.fram a.frame(fit) e(fit) ## End(No End(Not t run run) )

cppo

Set and get the optimization optimization level level and debug debug ﬂag for compiling compiling the C++ code

Description Set and get the optimizat optimization ion level, level, deﬁned in CXXFLAGS, CXXFLAGS, for compili compiling ng the C++ code. Also ﬂag -DDEBUG or -DNDEBUG in R_XTRA_CPPFLAGS is set depending on the optimization mode and parameter NDEBUG. All ﬂags set by set_cppo can be removed by reset_cppo to restore the default settings in R. Usage set_cppo(m set_c ppo(mode ode = c("fa c("fast", st", "pre "presenta sentation2 tion2", ", "pres "presentat entation1" ion1", , "debu "debug", g", "smal "small"), l"), NDEBUG NDE BUG = FAL FALSE) SE) get_cppo() reset_cppo()

Arguments mode

NDEBUG

A char characte acterr spec specifyi ifying ng the optim optimizat ization ion lev level: el: one of "fast", "presentation2", "presentation1", "debug", "small", correspondin corresponding g to opti optimiza mization tion level level "3", "2", "1", "0", "s"; defaults to "fast". The o orde rderr from from "fast" to "debug" generally means that the generated code runs from the fastest to the slowest; "small" means optimizing for size. See the notes below.

Logical (defaults to FALSE). If  TRUE TRUE, "-DNDEBUG" would be added to compile the generated C++ ﬁle (this is the default in R as well). However, if this is set, some index checking in Stan would be turned off, which would crash R if some indices are out of range in the model speciﬁcation. In "debug" mode, the option is neglected neglected (no "-DNDE "-DNDEBUG" BUG" is set). When NDEBUG=FALSE is speciﬁed for calling this function, a warning is issued.

Value set_cppo returns the list with element names being CXXFLAGS and R_XTRA_CPPFLAGS. Each ele-

ment is the desired ﬂag that is set if the operation is successful; if any problems is encountered, this function will stop and report an error. get_cppo returns a list. The ﬁst element is string indicating the optimization mode (that is, one of "fast", "presentation2", "presentation1", "debug"). The second element indicates if "NDE-

BUG" is set. The third element indicates if "DEBUG" is set. reset_cppo removes the compiler ﬂags set by set_cppo and restores the default settings in R.

extract-methods

7

Note Since the optimization level is set by using a ﬁle with name Makevars (or a similar ﬁle with names such as Makevars.win64, Makevars.win, Makevars-$R_PLATFROM depending on platforms) in folder .R under the user’s home directory, the side effect  is is that the optimization level set here will be used by R CMD CMD SHLI SHLIB B and possibly installing other R package from source (including installing in).. If this is not desired, desired, the creat created ed ﬁle can be rem remov oved. ed. Fo Forr the same same reaso reason, n, the rstan again) rstan aga optimization level that is set stays once set_cppo is called. called. If a differen differentt optimization optimization lev level el is needed, set_cppo needs to be called again. Generally for compiling models, what is strongly recommended is to use mode="fast". When When debugging C++ code using for example gdb , mode="debug" can be used, in which case -g ﬂag is also set in CXXFLAGS. And we recommend calling set_cppo again to set the optimization mode back to "fast" after ﬁnishing debugging. In modes other than "debug", "-DNDEBUG" is added to the ﬂags for compiling model’s C++ code if NDEBUG=TRUE. By default (NDEBUG=FALSE), there is more index checking in Stan, which might slow down the execution. execution. So if it is certain there is no problem with the indices in the model speciﬁcation, we can set NDEBUG=TRUE to recompile the model. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. help of   R CMD CMD SHLI SHLIB B. manual of  gcc gcc and clang. See Also stan and stan_model

Examples ## Not Not run: run: set_cppo("fast") get_cppo() set_cp set _cppo( po("fa "fast" st", , NDE NDEBUG BUG = FALSE) FALSE) # warning warning: : this this mig might ht disabl disable e som some e ind index ex rangerange-che checki cking ng ## End(No End(Not t run run) )

extract-methods

extract: extract samples from ﬁtted Stan model

Description Extract samples from a ﬁtted model represented by an instance of class stanfit.

8

extract-methods

Usage 



## S4 met method hod for sig signat nature ure stanfit extract(o extr act(object bject, , pars, permute permuted d = TRUE, inc_war inc_warmup mup = FALSE FALSE) )

Arguments

object pars

permuted

An object of class stanfit. An object of class "character" providing the parameter names (or other quantity names) of interest. If not speciﬁed, all parameters and other quantities are used. The log-posterior with name lp__ is also included in the samples. TRUE of  FALSE. If  TRUE TRUE, draws after the warmup period in each chain are permuted   and merged . If   FALSE, the original original order are ke kept. pt. For eac each h stanfit

object, the permutation is ﬁxed (that is, extracting samples a second time will give the same sequence of iterations as the previous). inc_warmup

TRUE of   FALSE. The argument matters only if   permuted is FALSE. If   TRUE,

warmup draws are included; otherwise excluded. Value When perm permut uted ed = TRUE TRUE, this function returns a named list, every element of which is an array representing samples for a parameter merged from all chains. When perm permute uted d = FAL FALSE SE, an array is returned; the ﬁrst dimension 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 examples below and comments in the code. Function monitor can be applied to the returned array to obtain a summary of model inference (similar to method print for stanfit). Methods extract s signat ignature(o ure(object bject = "stan "stanfit" fit") ) Extract samples for a ﬁtted model deﬁned by class stanfit. See Also S4 class stanfit, as.array.stanfit, and monitor Examples ## Not Not run: run: ex_model_cod ex_mod el_code e <parameters parame ters { real alpha[ alpha[2,3]; 2,3]; real beta[2 beta[2]; ]; } model mod el { for for (i in 1:2) 1:2) for (j in 1:3) 1:3) alpha[ alp ha[i, i, j] ~ normal( normal(0, 0, 1); for for (i in 1: 1:2) 2) 

extract-methods

9

beta bet a ~ normal normal(0, (0, 2); } 

## fit fit the the mo mode del l fit <- stan(m stan(mode odel_c l_code ode = ex_ ex_mod model_ el_cod code, e, chains chains = 4) ## extrac extract t alp alpha ha and beta with with per permut muted ed = TRUE TRUE fit_ss fit _ss <- ext extrac ract(f t(fit, it, permuted permuted = TRUE) TRUE) # fit_ss fit_ss is a list list ## list list fit fit_ss _ss should have elemen elements ts with with nam name e alpha , beta , alpha <- fit_ss$alpha fit_ss$alpha beta <- fit_ss$beta fit_ss$beta ## or ext extrac ract t alp alpha ha by just spec specify ifying ing pars = alpha alpha2 alp ha2 <- ext extrac ract(f t(fit, it, pars = alpha , per permut muted ed = TRUE)$ TRUE)$alp alpha ha 

















lp__







print(identical(alpha, alpha2)) ## get the sample samples s for alpha[ alpha[1,1 1,1] ] and beta[2 beta[2] ] alpha_ alp ha_11 11 <- alpha[ alpha[, , 1, 1] beta_2 bet a_2 <- bet beta[, a[, 2] ## extrac extract t sam sample ples s wit with h

permut per muted ed = FALSE FALSE





fit_ss fit _ss2 2 <- extrac extract(f t(fit, it, permut permuted ed = FALSE) FALSE) # fit fit_ss2 _ss2 is an array array ## the dimension dimensions s of fit_ss2 fit_ss2 should be ## "# of iter iterat atio ions ns * # of chai chains ns * # of parame paramete ters" rs" dim(fit_ss2) ## since since the third dimens dimension ion of fit_ss2 indicates ## parame parameter ters, s, the names should should be ## alpha[ alpha[1,1], 1,1], alph alpha[2,1], a[2,1], alpha[1,2 alpha[1,2], ], alpha[2,2], alpha[2,2], ## alpha[ alpha[1,3 1,3], ], alpha[ alpha[2,3] 2,3], , beta[1 beta[1], ], beta[2 beta[2], ], and lp__ ## lp__ (the log-posterior) log-posterior) is always included ## in the sampl samples. es. dimnames(fit_ss2) 







## End(No End(Not t run run) )

# Cre Create ate a sta stanfi nfit t obj object ect from readin reading g CSV files of sample samples s (sa (saved ved in rst rstan an # pac packag kage) e) gen genera erated ted by funtio funtion n sta stan n for dem demons onstrat tration ion pur purpos pose e fro from m mod model el as follow follows. s. # excode exc ode <transformed transf ormed data { real y[20]; y[1] y[1] < <- 0. 0.57 5796 96; ; y[2] y[2] <- 0.2 0.227 276; 6; y[3] y[3] <<- -0.2 -0.295 959; 9; y[4] y[4] < <- -0 -0.3 .374 742; 2; y[5] y[5] <- 0.3 0.388 885; 5; y[ y[6] 6] <<- -2.15 -2.1585 85; ; y[7] y[7] < <- 0. 0.71 7111 11; ; y[8] y[8] <- 1.4 1.442 424; 4; y[9] y[9] <<- 2.54 2.5430 30; ; y[10 y[10] ] <- 0.37 0.3746 46; ; y[11] y[11] <- 0.4773 0.4773; ; y[ y[12 12] ] <- 0.1803 0.1803; ; y[13] y[1 3] <- 0.5 0.5215 215; ; y[14] <- -1.604 -1.6044; 4; y[15] y[15] <- -0.6 -0.6703 703; ; y[16 y[16] ] <- 0.94 0.9459 59; ; y[17] y[17] <- -0.382 -0.382; ; y[ y[18 18] ] <- 0.7619 0.7619; ; y[19] y[1 9] <- 0.1006 0.1006; ; y[20 y[20] ] <- -1.746 -1.7461; 1; } parameters parame ters { 

10

log_prob-methods

real mu; real real<lower=0 real<l ower=0, , upper=10> upper=10> sigma; vector[2] vector [2] z[3]; real<lower=0 real<l ower=0> > alpha; } model mod el { y ~ nor normal mal(mu (mu, , sig sigma); ma); for for (i in 1: 1:3) 3) z[i] z[i ] ~ normal normal(0, (0, 1); alpha ~ exponential(2 exponential(2); ); } 

# exf exfit it <- stan(m stan(mode odel_c l_code ode = exc excode ode, , sav save_d e_dso so = FALSE, FALSE, iter iter = 200 200, , # sample_file = "rstan_doc_ex.csv") # exfit <- read_s read_stan_cs tan_csv(dir(s v(dir(system. ystem.file( file( misc , pa packa ckage ge = rstan ), pattern= rstan_doc_ex_[[:digit:]].csv , full.names full.n ames = TRUE)) 











ee1 <- extrac extract(e t(exfi xfit, t, permute permuted d = TRUE) TRUE) print(names(ee1))

for (name in names( names(ee1 ee1)) )) { cat(name, cat(na me, "\n") print(dim(ee1[[name]])) } ee2 <- extrac extract(e t(exfi xfit, t, permute permuted d = FALSE) FALSE) print(dim(ee2)) print(dimnames(ee2))

log_prob-methods

model’s log_prob and  grad_log_prob grad_log_prob functions

Description Using model’s model’s log_prob and grad_log_prob functions on the unconstrained space of model parameters rame ters.. So sometim sometimes es we need convert convert the values of para paramete meters rs from their support deﬁned in parameter block (which might be constrained, and for simplicity, we call it constrained space) to unconstrained space and vice versa. constrained_pars and unconstrain_pars can be used then. Usage ## S4 met method hod for sig signat nature ure stanfit log_prob(objec log_prob( object, t, upars upars, , adju adjust_tr st_transfo ansform rm = TRUE, gradient = FALSE FALSE) ) 







## S4 met method hod for sig signat nature ure stanfit grad_log_ grad _log_prob( prob(obje object, ct, upars upars, , adjus adjust_tra t_transfor nsform m = TRUE TRUE) )

log_prob-methods

## S4 met method hod for sig signat nature ure get_num_upars(object)









11

stanfit

## S4 met method hod for sig signat nature ure stanfit constrain_pars(object, constrain_pars(obj ect, upars) ## S4 met method hod for sig signat nature ure stanfit unconstrain_pars(object, unconstrain_pars(o bject, pars) 



Arguments

pars upars

An object of class stanfit.

object

An list specifying the values for all parameters on the constrained space.

A numeric numeric vect vector or for spec specifyi ifying ng the values values for all parameter parameterss on the unconunconstrained space.

adjust_transform

Logical to indicate whether to adjust the log density since Stan transforms pagradient

rameters to unconstrained space if it is in constrained space. Logical to indicate whether gradients are also computed as well as the log density.

Details In Stan, the parameters need be deﬁned with their supports. For example, for a variance parameter, we must deﬁne it on the posit positiv ivee real line. line. But inside Stan’s Stan’s sampler sampler,, all parameter parameterss deﬁned on the constrained space are transformed to unconstrained space, so the log density function need be adjusted (i.e., adding the log of the absolute value of the Jacobian determinant). With the transformation, Stan’s samplers work on the unconstrained space and once a new iteration is drawn, Stan transforms the parameters back to their supports. All the transformation are done inside Stan without interference from the users. 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 ﬁnding the mode of parameters on the constraine constrained d space, we then do not need the adjust adjustment ment.. For this reason reason,, there there is an argument argument named adjust_transform for functions log_prob and grad_log_prob.

Value log_prob return returnss a val value ue (up to an additiv additivee const constant) ant) the log post posterio erior. r. If  gradient gradient is TRUE, the gradients are also returned as an attribute with name gradient. grad_log_prob returns a vector of the gradients. Additionally, Additionally, the vector has an attribute name named d log_prob being the value the same as log_prob is called for the input parameters. get_num_upars returns the number of parameters on the unconstrained space. constrain_pars returns a list and unconstrain_pars returns a vector.

12

log_prob-methods

Methods log_prob signature(obj signature(object ect = "stan "stanfit" fit") )Compute the log posterior (lp__) for the model represented by a stanfit object. signature(obje (object ct = "stan "stanfit") fit")Compute the gradients for log_prob as well grad_log_prob signature as the log posterior. The latter is returned as an attribute. signature( ture(objec object t = "sta "stanfit" nfit") )Get the number of unconstrained parameters. get_num_upars signa signature(objec object t = "sta "stanfit" nfit") )Convert values of the parameter from unconconstrain_pars signature( strained space (given as a vector) to their constrained space (returned as a named list). signature(object ct = "stan "stanfit") fit")Contrary to constrained, conert values of unconstrain_pars signature(obje the parameters from constrained to unconstrained space.

References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org. See Also stanfit

Examples ## Not Not run: run: # see see the the ex exam ampl ples es in the help for st stan anfi fit t as we well ll # do a simple simple optimi optimizat zation ion proble problem m opco opcode de <- " parameters parame ters { real rea l y; } model mod el { lp__ lp__ <- lo log( g(sq squa uare re(y (y - 5) + 1) 1); ; } " tfun <- function(y) function(y) log_prob(opfit, log_prob(opfit, y) tgrfun <- function(y) function(y) grad_log_prob(opfi grad_log_prob(opfit, t, y) or <- opt optim( im(1, 1, tfun, tfun, tgrfun, tgrfun, method method = BFGS ) print(or) 

# ret return urn the gradie gradient nt as an attrib attribute ute tfun2 tfu n2 <- functi function( on(y) y) { g <- grad_l grad_log_pro og_prob(opfit b(opfit, , y) lp <- att attr(g r(g, , "lo "log_p g_prob" rob") ) attr(l att r(lp, p, "gr "gradi adient ent") ") <- g lp } or2 <- nlm(tf nlm(tfun2 un2, , 10) or2 ## End(No End(Not t run run) )



makeconf_path

makeconf_path

13

Obtain the full path of ﬁle Makeconf

Description Obtain the full path of ﬁle Makeconf, in which, for example the ﬂags for compiling C/C++ code are conﬁgured. Usage makeconf_path()

Details The conﬁguration for compiling shared objects using R CM CMD D SH SHLI LIB B are set in ﬁle Makeconf. To change chan ge how the C++ code is comp compiled iled,, modi modify fy this ﬁle. For RStan, package package inline compiles the inline compiles C++ code using R CMD CMD SHLI SHLIB B. To speed up compiled Stan models, increase the optimization level to -O3 deﬁned in property CXXFLAGS in the ﬁle Makeconf. This ﬁle may also be modiﬁed to specify alternative C++ compilers, such as clang++ or later versions of g++. As of rstan 1.0.2, set_cppo can be used to create/change a ﬁle that can be used to deﬁne compiling ﬂags in the user’s home directoty, in which a ﬂag can be set to overwrite what is set in the system’s Makeconf ﬁle. Value An character string for the full path of ﬁle Makeconf. See Also stan, set_cppo

Examples makeconf_path()

monitor

Compute the summary for MCMC simulation samples and monitor the convergence

Description For a 3-d array (the number of iterations * the number of chains * the number of parameters) of MCMC simulation samples, this function computes the summaries such as mean, standard deviation, standard error of the mean, and quantiles. And for monitoring the convergence, split Rhat and the effective sample size are also computed. By default, half of the iterations are considered to be warmup samples and thus excluded.

14

monitor

Usage monitor(s moni tor(sims, ims, warm warmup up = floor floor(dim( (dim(sims) sims)[1]/ [1]/2), 2), probs pro bs = c(0 c(0.02 .025, 5, 0.2 0.25, 5, 0.5 0.5, , 0.7 0.75, 5, 0.9 0.975) 75), , digits dig its_su _summa mmary ry = 1, pri print nt = TRU TRUE, E, ... ...) )

Arguments

sims

A 3-dimension array of samples simulated from any MCMC algorithm. The ﬁrst dimension is for the number of iterations; the second for the number of chains; the third for the parameters.

warmup

probs

The numb number er of warm warmup up iter iteratio ations ns that would would be excl excluded uded for computin computing g the summaries; default to half of the total number of iterations. Quantiles of interest; defaults to "c(0.025,0.25,0.5, "c(0.025,0.25,0.5,0.75,0.975)" 0.75,0.975)"

digits_summary The number of signiﬁcan signiﬁcantt digits for printing out the the summary; defaul defaults ts to 1. The

effective sample size is always rounded to integers. ... print

Additional arguments for the underlying print method.

Logical; indicating whether to print the summary summary..

Details Similar to the print function for stanfit object, the function prints out a summary for the simulated samples. In particular, for monitoring the conver convergence, gence, the printout includes the split Rhat and the effective sample size. Value A summary given as a 2 dimension array for the input samples: each row is for one parameter; the columns are the mean, standard deviation, quantiles, split Rhat, the effective sample size, etc. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org. See Also S4 class stanfit and particularly its method print. Examples csvfiles csvfil es <- dir(sy dir(system.fi stem.file( le( misc , pa pack ckag age e = rstan ), patter pat tern n = rstan_doc_ex_[0-9].csv , ful full.n l.name ames s = TRU TRUE) E) fit <- read_stan_cs read_stan_csv(csvfi v(csvfiles) les) # The The foll follow owin ing g is ju just st fo for r th the e pu purp rpos ose e of gi givi ving ng an ex exam ampl ple e # sinc since e prin print t ca can n be us used ed fo for r a st stan anfi fit t ob obje ject ct. . monitor(extr monito r(extract(fi act(fit, t, permuted permuted = FALSE, inc_warmup inc_warmup = TRUE)) 











optimizing-methods

opti optimi mizi zing ng-m -met etho hods ds

15

opti optimi mizi zing ng: obt obtain ain a point point est estima imate te by max maximiz imizing ing the joint joint pos poster terior ior

Description Obtain a point Obtain point est estima imate te by max maximi imizin zing g the joi joint nt poster posterior ior fro from m the model model deﬁ deﬁned ned by class class stanmodel. This method is a generic function of the S4 class stanmodel. Usage 



## S4 met method hod for sig signat nature ure stanmodel optimizin opti mizing(obj g(object, ect, data = list( list(), ), seed = sampl sample.int e.int(.Ma (.Machine chine$inte $integer.m ger.max, ax, 1), init = random , check_data check _data = TRUE, sample_fi sample_file, le, algorithm algor ithm = c("LB c("LBFGS" FGS", , "BFGS "BFGS", ", "Newt "Newton"), on"), verbos ver bose e = FAL FALSE, SE, hessi hessian an = FAL FALSE, SE, as_ve as_vecto ctor r = TRU TRUE, E, ... ...) ) 



Arguments An object of class stanmodel.

object data

An objec objectt of class list, environment providing the data for the model, or a vector character strings for all the names of objects used as data in the working space. See the notes in stan.

seed

The seed for random number generation. The default is generated from 1 to the maximum integer supported by R on the machine. When a seed is speciﬁed by a number, as.integer will be applied to it. If  as.integer as.integer produces NA, the seed is generated generated randoml randomly y. We can also specify a seed using a chara character cter string string of digits, such as "12345", which will be converted to integer.

init

One of digit 0, string "0" or "random", a function that returns a list, or a named list of initial parameter values. "0" : initialize all to be zero on the unconstrained support; "random": randomly generated; list: a list specifying the initial values of parameters by name. function: a function that returns a list for specifying the initial values of parameters for a chain.

check_data

sample_file

algorithm verbose

Logical: Logical: if  TRUE TRUE, the data would be preprocess preprocessed; ed; otherwi otherwise se not. If the data is not checked and preprocessed, it is safe to leave it to be the default TRUE. See the notes in stan.

A chara character cter st string ring of ﬁle ﬁle name fo forr speci specifyin fying g where to to write sa sample mpless for all parameters paramete rs and other sav saved ed quantit quantities. ies. If not prov provided, ided, ﬁles are not created. created. When the folder speciﬁed is not writable, tempdir() is used. One of "Newton", "BFGS", and "LBFGS" indicating which optimization algorithm is used. The default is LBFGS. TRUE or FALSE: ﬂag indicating whether to print intermediate output from Stan on the console.

16

optimizing-methods

calculatee the Hessian (via TRUE or FALSE (the default): ﬂag indicating whether to calculat

hessian

numeric differentiation of the gradient function in the unconstrained parameter space) TRUE (the default) or FALSE: ﬂag indicating whether a vector is used to for the point estimate found. A list can be used instead by specifying it to be FALSE

as_vector

...

Other optional parameters, refer to the manuals for both CmdStan and Stan. 1. iter ( integer), the maximum number of iterations 2. save_iterations (logical), whether to save the iterations 3. refresh ( integer) 4. init_alpha (double, default to 0.001), for BFGS and LBFGS, see manual of (Cmd)Stan 5. tol_obj (double, default to 1e-12), for BFGS and LBFGS, see the manual of (Cmd)Stan 6. tol_grad (double, default to 1e-8), for BFGS and LBFGS, see the manual of (Cmd)Stan 7. tol_param ( double, default to 1e-8), for BFGS and LBFGS, see the manual of (Cmd)Stan 8. tol_rel_obj (double, default to 1e4), for BFGS and LBFGS, see the manual of (Cmd)Stan 9. tol_rel_grad (double, default to 1e7), for BFGS and LBFGS, see the manual of (Cmd)Stan 10. history_size (integer, default to 5), for LBFGS, see the manual of (Cmd)Stan

Value A list with components if the optimization is done successfully:

par value

The point esti estimate mate foun found. d. Its form (ve (vector ctor or list list)) is determin determined ed by argu argument ment as_vector.

The value of the log-posterior (up to an additiv additivee constant, the "lp__" in Stan) corresponding to par.

If the optimization is not ﬁnished for reasons such as feeding wrong data, it returns NULL. Methods signature(object ect = "stan "stanmodel model") ") optimizing signature(obj

Call Stan’s optimization methods to obtain a point estimate for the model deﬁned by S4 class stanmodel given the data, initial values, etc. See Also stanmodel

pairs.stanﬁt

17

Examples ## Not Not run: run: m <- stan_m stan_model(m odel(model_c odel_code ode = par parame ameter ters s {re {real al y;} model model {y ~ normal normal(0, (0,1); 1);} } ) f <- opt optimi imizin zing(m g(m, , hes hessian sian = TRU TRUE) E) 



## End(No End(Not t run run) )

pairs.stanfit

Create a matrix of output plots from a stanfit object

Description A pairs method that is customized for MCMC output Usage ## S3 meth method od for for clas class s stanfit pairs( pai rs(x, x, lab labels els = NUL NULL, L, pan panel el = NUL NULL, L, ... ..., , low lower. er.pan panel el = NUL NULL, L, 



upper.pan upper. panel el = NUL NULL, L, dia diag.p g.pane anel l = NUL NULL, L, tex text.p t.pane anel l = NUL NULL, L, label. lab el.pos pos = 0.5 + has has.di .diag/ ag/3, 3, cex cex.la .label bels s = NUL NULL, L, fon font.l t.labe abels ls = 1, ro row1 w1at atto top p = TRUE TRUE, , gap gap = 1, pars pars = NULL NULL, , cond condit itio ion n = NULL NULL) )

Arguments x

An object of S4 class stanfit

labels, labe ls, panel panel, , ..., lower lower.pane .panel, l, upper upper.pan .panel, el, diag. diag.panel panel

Same as in pairs syntactically but see the Details section for different default arguments text.pane text .panel, l, label label.pos, .pos, cex.lab ex.labels, els, font. font.label labels, s, row1 row1attop attop, , gap

Same as in pairs pars

condition

If not NULL, a character vector indicating which quantities to include in the plots, which is passed to extract. Thus, by default, default, all unknown qua quantit ntities ies are in

cluded, which may be far too many to visualize on a small computer screen. By default, NULL, which will plot roughly half of the chains in the lower panel and the rest in the upp upper er panel. panel. An integer integer vec vector tor can be pas passed sed to selec selectt some subset of the chains, of which roughly half will be plotted in the lower panel pan el and the rest rest in the upper pan panel. el. A lis listt of two integer integer vector vectorss can be passed, each specifying a subset of the chains to be plotted in the lower and upper panels panels resp respecti ectively vely.. A singl singlee numb number er between zero and one excl exclusi usive ve can be passed, which is interpreted as the proportion of realizations (among all chains) to plot in the lower panel starting with the ﬁrst realization in each chain, with the complement (from the end of each chain) plotted in the upper panel. A (possibly abbreviated) character vector of length one can be passed among "accept_st "acce pt_stat__" at__", , "step "stepsize_ size__", _", "tree "treedepth depth__", __", "n_le "n_leapfro apfrog__" g__" or "n_divergent__", which are the variables produced by get_sampler_params, in which case the lower panel will plot realizations that are below the median

18

plot-methods

of the indicated variable (or are zero in the case of  "n_divergent__" "n_divergent__") and the upper panel will plot realizations that are greater than or equal to the median of the indicated variable (or are one in the case of  "n_divergent__"). Finally, any logical vector whose length is equal to the product of the number of iterations and the number of chains can be passed, in which case realizations corresponding to FALSE and TRUE will be plotted in the lower and upper panel respectively. Details method in the follo following wing ways. ways. If unspeciﬁed, unspeciﬁed, the This method differs from the default pairs method smoothScatter function is used for the off-diagonal plots, rather than points, since the former is more appropriate for visualizing thousands of draws from a posterior distribution. Also, if unspeciﬁed, histograms of the marginal distribution of each quantity are placed on the diagonal of the plot, after pooling all of the chains speciﬁed by the chain_id argument. The draws from the warmup phase are always discarded before plotting.

See Also S4 class stanfit and its method extract as well as the pairs generic function Examples example(read_stan_csv) pairs(fit, pairs( fit, condition = list(1, 2:4)) pairs( pai rs(fit fit, , par pars s = c(" c("mu", mu", "sigma "sigma", ", "alpha "alpha", ", "lp__") "lp__"), , condit condition ion = 0.2 0.25) 5) pairs( pai rs(fit fit, , par pars s = c(" c("mu", mu", "sigma "sigma", ", "alpha "alpha", ", "lp__") "lp__"), , condit condition ion = "ac "acc") c") lp <- sapply sapply(get_l (get_logposte ogposterior(f rior(fit), it), FUN = function(x) function(x) tail(x, nrow(fit))) nrow(fit))) pairs( pai rs(fit fit, , par pars s = c(" c("mu", mu", "sigma "sigma", ", "alpha "alpha", ", "lp__") "lp__"), , condit condition ion = lp > median( median(lp) lp)) )

plot-methods

overview w of summa summaries ries for the ﬁtted model plot: plot an overvie

Description Drawn Draw n an ove overvie rview w of paramet parameter er summari summaries es for the ﬁtted model. In the ove overvie rview w plot, we also indicate the values of Rhats for all parameters of interest using differnt colors. In addition to all the parameters, the log-posterior is also plotted. Usage 



## S4 met method hod for sig signat nature ure stanfit,missing plot(x, plot (x, pars, disp display_p lay_parall arallel el = FALSE FALSE, , ask = TRU TRUE, E, npa npars_ rs_per per_pa _page ge = 6)

plot-methods

19

Arguments An instance of class stanfit.

x pars

A vector of character string specifying the parameters to be plotted. If not speciﬁed, all parameters are used.

display_parallel TRUE or FALSE, indicating whether to plot the intervals with one line for each chain chai n or one line for all chains chains.. The defau default lt is FALSE so that only one interval

line is drawn for each scalar parameter. TRUE or FALSE, to control (for the current device) whether the user is prompted

ask

before starting a new page of output in the case there are a lot of parameters (see devAskNewPage). npars_per_page An integer to specify the number of param parameters eters that would be plotted per page.

Value NULL

Methods sign ignatu ature( re(x x = "st "stanf anfit" it", , y = "mi "missi ssing" ng") ) Plot an overview of parameter summaries plot s for the ﬁtted model.

Examples ## Not Not run: run: library(rstan) fit <- stan(m stan(mode odel_c l_code ode = "pa "param ramete eters rs {real {real y;} mode model l {y ~ normal normal(0, (0,1); 1);}") }") plot(fit) ## End(No End(Not t run run) ) # Cre Create ate a sta stanfi nfit t obj object ect from readin reading g CSV files of sample samples s (sa (saved ved in rst rstan an # pac packag kage) e) gen genera erated ted by funtio funtion n sta stan n for dem demons onstrat tration ion pur purpos pose e fro from m mod model el as follow follows. s. # excode exc ode < 

transformed data { transformed real y[20]; y[1] y[1] < <- 0. 0.57 5796 96; ; y[2] y[2] <- 0.2 0.227 276; 6; y[4] y[4] < <- -0 -0.3 .374 742; 2; y[5] y[5] <- 0.3 0.388 885; 5; y[7] y[7] < <- 0. 0.71 7111 11; ; y[8] y[8] <- 1.4 1.442 424; 4; y[10 y[10] ] <- 0.37 0.3746 46; ; y[11] y[11] <- 0.4773 0.4773; ; y[13] y[1 3] <- 0.5 0.5215 215; ; y[14] <- -1.604 -1.6044; 4; y[16 y[16] ] <- 0.94 0.9459 59; ; y[17] y[17] <- -0.382 -0.382; ; y[19] y[1 9] <- 0.1006 0.1006; ; y[20 y[20] ] <- -1.746 -1.7461; 1; } parameters parame ters { real rea l mu; real<lower=0 real<l ower=0, , upper=10> upper=10> sigma; vector[2] vector [2] z[3]; real<lower=0 real<l ower=0> > alpha;

y[3] y[3] <<- -0.2 -0.295 959; 9; y[ y[6] 6] <<- -2.15 -2.1585 85; ; y[9] y[9] <<- 2.54 2.5430 30; ; y[ y[12 12] ] <- 0.1803 0.1803; ; y[15] y[15] <- -0.6 -0.6703 703; ; y[ y[18 18] ] <- 0.7619 0.7619; ;

20

print

} model mod el { y ~ nor normal mal(mu (mu, , sig sigma); ma); for for (i in 1: 1:3) 3) z[i] z[i ] ~ normal normal(0, (0, 1); alpha ~ exponential(2 exponential(2); ); 

}

# exf exfit it <- stan(m stan(mode odel_c l_code ode = exc excode ode, , sav save_d e_dso so = FALSE, FALSE, iter iter = 200 200, , # sample_file = "rstan_doc_ex.csv") # exfit <- read_s read_stan_cs tan_csv(dir(s v(dir(system. ystem.file( file( misc , pa packa ckage ge = rstan ), pattern= rstan_doc_ex_[[:digit:]].csv , full.names full.n ames = TRUE)) 











print(exfit) plot(exfit)

print

Print a summary for a ﬁtted model repr represented esented by a stanfit object

Description Print basic information regarding the ﬁtted model and a summary for the parameters of interest estimated by the samples included in a stanfit object.

Usage 



## S3 meth method od for for clas class s stanfit print(x, prin t(x, pars = x@sim x@sim$par $pars_oi, s_oi, probs pro bs = c(0 c(0.02 .025, 5, 0.2 0.25, 5, 0.5 0.5, , 0.7 0.75, 5, 0.9 0.975) 75), , digits_sum digit s_summary mary = 2, ...)

Arguments x

An object of S4 class stanfit.

pars

Parameter Parameterss in which the summaries are interest; defaults to all parameters for which samples are saved.

probs

Quantiles of interest; defaults to "c(0.025,0.25,0.5, "c(0.025,0.25,0.5,0.75,0.975)" 0.75,0.975)"

signiﬁcantt digits for printing out the the summary; defaul defaults ts to 1. The digits_summary The number of signiﬁcan effective sample size is always rounded to integers. ...

Additional arguments that would be passed to method summary of  stanfit stanfit.

read_rdump

21

Details The information regarding the ﬁtted model includes the number of iterations, the number of chains, the number of iterations that are saved in the stanfit object (including warmup); which sampler of NUTS1, NUTS2, HMC is used; and when the sampling is ﬁnished. The summary about parameters includes the mean, the standard error of the mean (se_mean), the standard stan dard deviati deviation on (sd), quantiles quantiles,, the eff effecti ective ve samp sample le size (n_eff) (n_eff),, and the spli splitt Rhat. The summary summary is computed based on merging samples without warmup iterations from all chains. In addition to parameters, the log-posterior ( lp__) is also treated like a parameter in the printout. See Also S4 class stanfit and particularly its method summary, which is used to obtain the values that are printed out.

read_rdump

Read data in an R dump ﬁle to a list

Description Create an R list from an R dump ﬁle Usage read_rdump(f)

Arguments f

A character string providing the dump ﬁle name.

Details The R dump ﬁle can be read directly by R function source, which by default would read the data into the user’s user’s works workspace pace (the global envir environme onment). nt). This functi function on instead read the data to a list, list, making it convenient to prepare data for the stan model-ﬁtting function. Value A list containing all the data deﬁned in the dump ﬁle with keys corresponding to variable names. See Also stan_rdump; dump

Examples x <- 1; y <- 1:10; 1:10; z <- array( array(1: 1:10 10, , di dim m = c( c(2, 2,5) 5)) ) stan_rdump(l stan_r dump(ls(patt s(pattern ern = ^[xyz] ), "xyz.R "xyz.Rdump") dump") l <- rea read_r d_rdum dump( p( xyz.Rdump ) print(l) 







22

read_stan_csv

read_stan_csv

Read CSV ﬁles of samples generated by (R)Stan into a stanfit object

Description Create a stanfit object from the saved CSV ﬁles that are created by Stan or RStan and that include the samples drawn from the distribution of interest to facilitate analysis of samples using RStan.

Usage read_stan read _stan_csv( _csv(csvf csvfiles, iles, col_ col_major major = TRUE)

Arguments csvfiles col_major

A character vector providing CSV ﬁle names

The order for array parameters; default to TRUE

Details Stan and RStan could save the samples to CSV ﬁles. This function reads the samples and using the comments (beginning with "#" ) to create a stanfit object object.. The model name is derived derived from the ﬁrst CSV ﬁle. col_major speciﬁes how array parameters are ordered in each row of the CSV ﬁles. For example, parameter "a[2,2]" would be ordered as "a[1,1], "a[1,1], a[2,1 a[2,1], ], a[1,2 a[1,2], ], a[2, a[2,2]" 2]" if col_major is TRUE.

Value A stanfit object (with invalid stanmodel slot). This stanfit object cannot be used to re-run the sampler. See Also stanfit

Examples csvfiles csvfil es <- dir(sy dir(system.fi stem.file( le( misc , pa pack ckag age e = rstan ), patter pat tern n = rstan_doc_ex_[0-9].csv , ful full.n l.name ames s = TRU TRUE) E) fit <- read_stan_cs read_stan_csv(csvfi v(csvfiles) les) 











rstan_options

rstan_options

23

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

Arguments of the form opt = val val set option opt to value val . Arguments of the form opt set the function to return option opt’s value. Each argument must be a character string.

Details The available options are: 1. plot_rhat_breaks: The cut off points for Rhat for which we would indicate using a different color.. This is a nume color numeric ric vector, vector, defaul defaulting ting to c(1. c(1.1, 1, 1.2, 1.2, 1.5, 1.5, 2). The v valu aluee for th this is option will be sorted in ascending order, so for example plot_rhat plot_rhat_brea _breaks ks = c(1.2 c(1.2, , 1.5) is equivalent to plot_rhat_ plot_rhat_brea breaks ks = c(1.5 c(1.5, , 1.2). 2. plot_rhat_cols: A vector of the same length as plot_rhat_breaks that indicates the colors for the breaks. 3. plot_rhat_nan_col: The color for Rhat when it is Inf or NaN. 4. plot_rhat_large_col: The colo colorr for for Rhat Rhat when when it is la larg rger er than than the the la larg rges estt val alue ue of plot_rhat_breaks. 5. rstan_alert_col: The color color used in method method plot of S4 class stanfit to show that the vector/array parameters are truncated. 6. rstan_chain_cols: The colors colors used in methods plot and traceplot of S4 class stanfit for coloring different chains. 7. rstawarmup_bg_col: The background color for the warmup area in the traceplots. 8. boost_lib: The path for the Boost C++ library used to compile Stan models. This option is valid for the whole R session if not changed again. 9. eigen_lib: The path for the Eigen C++ library used to compile Stan models. This option is valid for the whole R session if not changed again. Value The values as a list for existing options and NA for non-existent options. When only one option is speciﬁed, its old value is returned.

24

sa samp mpl linging-me met tho hod ds

sampling-methods

samp sampli lin ng: draw samples from Stan model

Description Draw samples from the model deﬁned by class stanmodel. This method method is a gener generic ic function function of the S4 class stanmodel. Usage ## S4 met method hod for sig signat nature ure stanmodel sampli sam pling( ng(obj object ect, , dat data a = lis list() t(), , par pars s = NA, ch chai ains ns = 4, iter iter = 2000 2000, , wa warm rmup up = floo floor( r(it iter er/2 /2), ), thin thin = 1, seed = sampl sample.int e.int(.Ma (.Machine chine$inte $integer.m ger.max, ax, 1), init = random , check_data check _data = TRUE, sample_f sample_file, ile, diagnosti diagnostic_fi c_file, le, verbo verbose se = FALSE FALSE, , algorithm algor ithm = c("NU c("NUTS", TS", "HMC" "HMC", , "Fixe "Fixed_pa d_param") ram"), , contro con trol l = NUL NULL, L, 







...)

Arguments

object

An object of class stanmodel.

data

An objec objectt of class list, environment providing the data for the model, or a vector character strings for all the names of objects used as data in the working space. See the notes in stan.

pars

A vect vector or of chara character cter strings strings speci specifyin fying g para paramete meters rs of interest interest;; defaults defaults to NA indicati indi cating ng all parameter parameterss in the model. model. Only sample sampless for paramet parameters ers given in pars are stored in the ﬁtted results.

chains iter

A posit positiv ivee inte integer ger spec specifyi ifying ng how man many y iter iteratio ations ns for each chai chain n (incl (including uding warmup). The default is 2000.

warmup

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

A positiv positivee integer specifying the number of warmup (aka burnin) iterations. If step-size adaptation is on (which it is by default), this also controls the number of iterations for which adaptation is run (and hence the samples should not be used for inference). The number of warmup should not be larger than iter and the default is iter/2.

thin

A positiv positivee integer specifying the period for saving samples; defaults to 1.

seed

The seed for random number generation. The default is generated from 1 to the maximum integer supported by R on the mach machine. ine. Even if multi multiple ple chain chainss are used, only one seed is needed, with other chains having seeds derived from that of the ﬁrst chain to avoid avoid dependent dependent sample samples. s. When a seed is speciﬁe speciﬁed d by a number, as.integer will be applied to it. If  as.integer as.integer produces NA, the seed is generated generated randoml randomly y. We can also specify a seed using a chara character cter string string of digits, such as "12345", which is converted to integer.

sampling-methods

init

25

One of digit 0, string "0" or "random", a function that returns a list, or a list of initial parameter values with which to indicate how the initial values of parameters are speciﬁed. "0": initiali initialize ze all to be zero on the uncon unconstra strained ined support; support; "random": randomly generated; list: a list of lists equal in length to the number of chains (parameter chains), where each list in the list of lists speciﬁes the initial values of parameters by name for the corresponding chain. function: a function that returns a list for specifying the initial values of parameters for a chain. The function can take an optional parameter chain_id.

check_data

Logical: Logical: if  TRUE preprocessed; ed; otherwi otherwise se not. If the data is TRUE, the data would be preprocess not checked and preprocessed, it is safe to leave it to be the default TRUE. See the notes in stan.

sample_file

A chara character cter st string ring of ﬁle ﬁle name fo forr speci specifyin fying g where to to write sa sample mpless for all paramete para meters rs and other sav saved ed quantit quantities. ies. If not prov provided, ided, ﬁles are not created. created. When the folder speciﬁed is not writable, tempdir() is used. When the there re are multiple chains, an underscore and chain number are appended to the ﬁle name.

diagnostic_file

A character string of ﬁle name for specifying where to write diagnostics data for all parameters. If not provided, ﬁles are not created. When the folder speciﬁed is not writable, tempdir() is used. When there are multiple chains, an underscore and chain number are appended to the ﬁle name. TRUE or FALSE: ﬂag indicating whether to print intermediate output from Stan

verbose

on the console, which might be helpful for model debugging.

algorithm

control

...

One of algorithms that are implemente implemented d in Stan such as the No-U-Tur No-U-Turn n sampler (NUTS, Hoffman and Gelman 2011), static HMC, or Fixed_param. See the argument control of function stan. Additional arguments can be chain_id, init_r, test_grad, append_samples, refresh. See the document document in stan.

Value An object of S4 class stanfit representing the ﬁtted results. Slot mode for this object indicates if the sampling is done or not. Methods signature(object ct = "stan "stanmodel model") ") sampling signature(obje

Call a sampler (NUTS, HMC, or Fixed_param depending on parameters) to draw samples from the model deﬁned by S4 class stanmodel given the data, initial values, etc. See Also stanmodel, stanfit, stan

Examples ## Not Not run: run: m <- stan_m stan_model(m odel(model_co odel_code de =

parame par ameter ters s {re {real al y;} model model {y ~ normal normal(0, (0,1); 1);} } )





26

sﬂist2stanﬁt

f <- samp sampli ling ng(m (m, , it iter er = 10 100) 0) ## End(No End(Not t run run) )

sflist2stanfit

Merge a list of stanﬁt objects into one

Description This function takes a list of   stanfit objects and returns a consolidated stanfit object object.. The stanfit objects to be merged need to have the same conﬁguration of iteration, warmup, and thin, besides being from the same model. This could facilitate some parallel usage of RStan. For exam stanfit objects, this function can be used to ple, if we call stan by parallel and it returns a list of  stanfit create one stanfit object from the list. Usage sflist2stanfit(sflist)

Arguments sflist

A list of  stanfit stanfit objects.

Value An S4 object of  stanfit stanfit consolidated from all the input stanfit objects. Note The best practice is to use sflist2stanfit on a list of  stanfit stanfit objects created with the same seed but different chain_id (see example 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 the stanfit objects in the input list can be merged. But the check is not sufﬁcient. So generally, it is the user’s responsibility to make sure the input is correct so that the merging makes sense. The date in the new stanfit object is when it is merged. get_seed function for the new consolidated stanfit object only returns the seed used in the ﬁrst

chain of the new object. The sampler such as NUTS2 that is displayed in the printout by print is the sampler used for the ﬁrst chain. The print method assumes the samplers are the same for all chains. The included stanmodel object, which includes the compiled model, in the new stanfit object is from the ﬁrst element of the input list. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/.

sﬂist2stanﬁt

See Also stan

Examples ## Not Not run: run: library(rstan) scod scode e <- " data data { int<lower=1> int<lo wer=1> N; } parameters parame ters { real y1[N]; real y2[N]; } model mod el { y1 ~ nor normal mal(0, (0, 1); y2 ~ double double_expon _exponential( ential(0, 0, 2); } " seed seed <- 123 123 # or any ot other her integ integer er foo_data foo_da ta <- lis list(N t(N = 2) foo foo <- stan stan(m (mod odel el_c _cod ode e = scod scode, e, da data ta = fo foo_ o_da data ta, , chain chains s = 1, it iter er = 0) f1 <- stan stan(f (fit it = fo foo, o, data data = fo foo_ o_da data ta, , ch chai ains ns = 1, se seed ed = se seed ed, , ch chai ain_ n_id id = 1) f2 <- stan stan(f (fit it = fo foo, o, data data = fo foo_ o_da data ta, , ch chai ains ns = 2, se seed ed = se seed ed, , ch chai ain_ n_id id = 2:3 2:3) ) f12 <- sflist2stanf sflist2stanfit(list it(list(f1, (f1, f2)) ## parall parallel el sta stan n cal call l for unix-l unix-like ike OS library(parallel) ## this this may may no not t wo work rk on Wi Wind ndow ows s sflist1 sflist 1 <mclapply(1:4 mclapp ly(1:4, , mc.cores mc.cores = 4, functi fun ction( on(i) i) stan(fi stan(fit t = foo, foo, dat data a = foo_dat foo_data, a, seed seed = seed, seed, ch chain ains s = 1, ch chai ain_ n_id id = i, re refre fresh sh = -1 -1)) )) f3 <- sflist sflist2stanf 2stanfit(sfli it(sflist1) st1) ## for Window Windows s (th (this is works on Unix-l Unix-like ike OS as well) CL = makeCl makeCluster( uster(4) 4) clusterExpor cluste rExport(cl t(cl = CL, c("foo_data", c("foo_data", "foo", "seed")) "seed")) sflist sfl ist1 1 <- parLap parLapply ply(CL (CL, , 1:4 1:4, , fun = fun functi ction( on(cid cid) ) { require(rstan) stan(f sta n(fit it = foo foo, , dat data a = foo_da foo_data, ta, chains chains = 1, iter iter = 20 2000 00, , se seed ed = se seed ed, , ch chai ain_ n_id id = ci cid) d) }) fit <- sflist2stanf sflist2stanfit(sfli it(sflist1) st1) print(fit) stopCluster(CL) ## end example example for Windows Windows

27

28

stan

## End(No End(Not t run run) )

stan

Fit a model using Stan

Description Fit a model deﬁned in the Stan modeling language and return the ﬁtted result as an instance of stanfit. Usage stan(file, stan(file , model model_name _name = "ano "anon_mod n_model", el", mode model_cod l_code e = "", fi fit t = NA NA, , data data = li list st() (), , pars pars = NA NA, , ch chai ains ns = 4, iter ite r = 200 2000, 0, war warmup mup = flo floor( or(ite iter/2 r/2), ), thi thin n = 1, init = "rand "random", om", seed = sampl sample.in e.int(.Ma t(.Machine chine$int $integer. eger.max, max, 1), algorithm algor ithm = c("N c("NUTS", UTS", "HMC "HMC", ", "Fix "Fixed_pa ed_param") ram"), , contro con trol l = NUL NULL, L, sample_file, diagnostic_file, save_d sav e_dso so = TRU TRUE, E, verbos ver bose e = FAL FALSE, SE, ... ..., , boost_lib boost _lib = NULL NULL, , eigen_lib eigen _lib = NULL NULL) )

Arguments A character string ﬁle name or a connection that R supports containing the text of a model speciﬁcation in the Stan modeling language; a model may also be speciﬁed directly as a character string using parameter model_code or through a previous ﬁt using parameter fit . When When fit is speciﬁed, parameter file is ignored.

file

model_name

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

model_code

fit

data

A character character string either containing the m model odel d deﬁnition eﬁnition or th thee name name of a char char-acterr stri acte string ng object in the worksp workspace. ace. This param parameter eter is used only if para paramete meterr file is not speciﬁed. When fit is speciﬁed, the model compiled previously is used so specifying model_code is ignored. An inst instance ance of S4 class class stanfit derived from a previous ﬁt; defaults to NA . If fit is not NA, the compiled model associated with the ﬁtted result is re-used; thus the time that would otherwise be spent recompiling the C++ code for the model can be saved.

An obje object ct of clas classs list, environment providing the data for the model, or a vector of character strings for all the names of objects used as data in the working space. See the notes below.

stan pars

iter

A vector vector of char characte acterr stri string ng speci specifyin fying g para paramete meters rs of inter interest; est; defa defaults ults to NA indicating indicati ng all parameter parameterss in the model. model. Only sample sampless for paramet parameters ers given in pars are stored in the ﬁtted results.

chains

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

A posit positiv ivee inte integer ger spec specifyi ifying ng how man many y iter iteratio ations ns for each chai chain n (incl (including uding warmup). The default is 2000.

warmup

29

A positiv positivee integer specifying number of warmup (aka burnin) iterations. This also speciﬁes the number of iterations used for stepsize adaptation, so warmup samples should not be used for inference. The number of warmup should not be larger than iter and the default is iter/2.

thin

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

init

One of digit 0 , string "0" or "random", a function that returns a named list, or a list of named list. "0": initialize all to be zero on the unconstrained support; "random": randomly generated by Stan: the seed of the random number generator in Stan can be speciﬁed by argument seed. So if seed for Stan is ﬁxed, the same initial values are used. Additionally Additionally,, optional parameter init_r controls the range for randomly generating the initial values for parameters in terms of their unconstrained support; list: a list of lists equal in length length to the number number of chains (parameter chains), where each named list (an element of the list of lists) speciﬁes the initial values for parameters by names for a chain. function: a function that returns a list for specifying the initial values of parameters for a chain. The functi function on can take an option optional al parame parameter ter chain_id for which the chain_id if speciﬁed or the integers from 1 to chains will be supplied respectively tively to the function function for generat generating ing initia initiall val values. ues. See the examples examples below of deﬁning such functions and using a list of lists for specify initial values. Additionally, see below notes on that RStan treats a vector of length 1 as a scalar.

seed

The seed, a positive positive integer integer,, for random number generation of Stan. The default is generated from 1 to the maximum integer supported by R so ﬁxing the seed of   R’s random random number gener generator ator can essent essentiall ially y ﬁx the seed of Stan. When multiple chains are used, only one seed is needed, with other chains’ seeds being generated from the ﬁrst chain’s seed to prevent dependency among the random number streams for the chains. When a seed is speciﬁed by a number, as.integer will be applied to it. If  as.integer as.integer produces NA , the seed is generated randomly. randomly. We can also specify a seed using a character string of digits, such as "12345", which is converted to integer.

algorithm sample_file

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

A chara character cter st string ring of ﬁle ﬁle name fo forr speci specifyin fying g where to to write sa sample mpless for all paramete para meters rs and other sav saved ed quantit quantities. ies. If not prov provided, ided, ﬁles are not created. created. When the folder speciﬁed is not writable, tempdir() is used. When the there re are multiple chains, an underscore and chain number are appended to the ﬁle name.

diagnostic_file

A character string of ﬁle name for specifying where to write diagnostics data for all parameters. If not provided, ﬁles are not created. When the folder speciﬁed is not writable, tempdir() is used. When there are multiple chains, an underscore and chain number are appended to the ﬁle name.

30

save_dso

stan

Logical, with default TRUE, indicating whether the dynamic shared object (DSO) compiled from the C++ code for the model will be saved or not. If  TRUE, we can draw samples from the same model in another R session using the saved DSO (i.e., without compiling the C++ code again). This parameter only takes effect if fit is not used; with fit deﬁned, the DSO from the previous run is used. When save_dso=TRUE

, the ﬁtted object can be is loaded what is platform, saved previously and used for sampling, if the compiling done from on the same that is, same operating system and same architecture (32bits or 64bits). TRUE or FALSE: ﬂag indicating whether to print intermediate output from Stan

verbose

on the console, which might be helpful for model debugging.

control

a nam named ed list of par parame ameter terss to con contro troll the sam sample pler’ r’ss behav behavior ior.. It defaul defaults ts to NULL so all the default values are used. First, the following are adaptation parameters for sampling algorithms. These are parameters used in Stan with similar names here. 1. adapt_engaged ( logical) 2. adapt_gamma ( double, positive, defaults to 0.05) 3. adapt_delta ( double, between 0 and 1, defaults to 0.8) 4. adapt_kappa ( double, positive, defaults to 0.75) 5. adapt_t0 ( double, positive, defaults to 10) 6. adapt_init_buffer ( integer, positive, defaults to 75) 7. adapt_term_buffer ( integer, positive, defaults to 50) 8. adapt_window ( integer, positive, defaults to 25) In addition, algorithm HMC (called ’static HMC’ in Stan) and NUTS share the following parameters: 1. stepsize ( double, positive) positive) 2. stepsize_jitter ( double, [0,1]) 3. metric ( string, one of "unit_e", "diag_e", "dense_e") For algorithm HMC, we can also set 1. int_time ( double, positive) positive) For algorithm NUTS, we can set 1. max_treedepth ( integer, positive) positive) For test_grad mode, the following parameters can be set 1. epsilon ( double, defaults to 1e-6) 2. error ( double, defaults to 1e-6)

...

Other optional parameters: 1. chain_id ( integer) 2. init_r ( double, positive) positive) 3. test_grad ( logical) 4. append_samples ( logical) 5. refresh(integer)

stan

31

chain_id can be a vector to specify the chain_id for all chains or an integer. For

the former case, they should be unique. For the latter, the sequence of integers starting from the given chain_id are used for all chains. speciﬁed, d, the initi initial al values values are init_r is only valid for init="random". If speciﬁe simulated from [-init_r, init_r] rather than using the default interval (see the manual of (cmd)Stan). Argument refresh (integer) can can be used used to cont contro roll ho how w to indi indica cate te the the pr prog ogre ress ss during duri ng sampling sampling (i.e. show show the progress ev every ery refresh it itera erati tions ons). ). By default, ref progress indic indicator ator is turne turned d off if refres resh h = max max(it (iter/ er/10, 10, 1). The progress refres ref resh h <= 0. Another parameter is test_grad (TRUE or FALSE). If  test_grad=TRUE test_grad=TRUE, Stan will not do any sampling. Instead, the gradient calculation is tested and printed out and the ﬁtted stanfit object is in test gradient mode. By default, it is FALSE. When a new model is ﬁtted starting from Stan model code, ... is passed to stan_model and thus stanc. boost_lib

The path path fo forr an alternati alternative ve version of tthe he Boos Boostt C++ to us usee instead instead o off the one in the BH the BH package. package.

eigen_lib

Th Thee pa path th for for an al alte tern rnat ativ ivee ve vers rsio ion n of the the Ei Eige gen n C+ C++ + li libr brar ary y to the the on onee in RcppEigen RcppEigen..

Details stan does all of the work of ﬁtting a Stan model and returning the results as an instance of  stanfit stanfit. First, it tran First, translat slates es the Stan mode modell to C++ code. Secon Second, d, the C++ code is comp compiled iled into a binary binary shared object, which is loaded into the current R session (an object of S4 class stanmodel is created). ated ). Finally Finally,, sample sample are drawn and wrapp wrapped ed in an object of S4 clas classs stanfit, which provides functions such as print, summary, and plot to inspect and retrieve the results of the ﬁtted model. stan can also be used to sample again from a ﬁtted model under different settings (e.g., different iter) by providing argument fit. In this case, the compiled C++ code for the model is reused.

Value Fitted results as an object of S4 class stanfit. If error occurs occurs before or during samp sampling ling,, and if test_grad test _grad = TRUE, the returned object would not contain samples. But the compiled binary object for the model is still included, so we can reuse the returned object for another sampling. Note The data passed to stan are preprocessed before passing to Stan. In general, each element of data should be either a numeric vector (including special case ’scalar’) or a numeric array (matrix). The ﬁrst exception is that an element can be a logical vector: TRUE’s are converted to 1 and FALSE’s to 0. An element can also be a data frame frame or a speciall specially y structu structured red list (see detail detailss below), both of which whic h will be conver converted ted into arrays in the preproc preprocessi essing. ng. Usin Using g a speciall specially y structured structured list is not encouraged though it might be convenient sometimes; and when in doubt, just use arrays. This preprocessing for each element mainly includes the following: 1. Change Change the data of typ typee from double to integer if no accuracy accuracy is lost. The main reas reason on is that by default, R uses double as data type such as in a << - 3. But Stan will not read data of type int from real and it reads data from int if the data type is declared as real.

32

stan

2. Check Check if there there is NA in the data. Unlike Unlike BUGS, Stan does not allo allow w missing missing data. Any NA values in supplied data will cause the function to stop and report an error. 3. Check data types. Stan allows only num numeric eric data, that is is,, doubles, integers, and arrays arrays of these. Data of other types (for examples, characters) are not passed to Stan. 4. Check whether there are ob objects jects in the data list with with duplicated names. names. Duplicated names, names, if found, will cause the function to stop and report an error. 5. Check whether whether the names of object objectss in the data list are legal legal Stan names. If illeg illegal al names are found, it will stop and report an error. See (Cmd)Stan’ (Cmd)Stan’ss manual for the rules of variable names. 6. When When an el elem emen entt is of type type data.frame, it will will be con conve verte rted d to matrix by func function tion data.matrix. 7. W Whe hen n an el elem emen entt is of type type list, it is supp suppos osed ed to make make it easi easier er to pa pass ss da data ta fo forr thos thosee de decl clar ared ed in Stan code such as "vecto "vector[J] r[J] y1[I] y1[I]" " and "matrix "matrix[J,K [J,K] ] y2[I] y2[I]" ". Using the the latte latterr as an example, we can use a list for y2 if the list has "I" elements, each of which is an array (matrix) of dimension "J*K". However, it is not possible to pass a list for data declared such as "vec "vector[K tor[K] ] y3[I y3[I,J]" ,J]"; the only way for it is to use an array with dimension "I*J*K". In addition, technically a data frame in R is also a list, but it should not be used for the purpose here since a data frame will be converted to a matrix as described above. y[1];" ;" is Stan treats treats a vector vector of length 1 in R as a scalar scalar.. So techni technicall cally y if, for example, example, "real y[1] deﬁned in the data block, an array such as "y = arra array( y(1. 1.0, 0, di dim m = 1) 1)" " in R should be used. This is also the case for specifying initial values since the same underlying approach for reading data from R in Stan is used, in which vector of length 1 is treated as a scalar.

The returned S4 class stanfit includes the compiled model if option save_dso is TRUE, so the compiled model can be saved for using in future R sessions. The function accepts a previously ﬁtted instance of  stanfit through parameter fit in order to reuse the compiled model; other conﬁguration may change. The optimization level for compiling the C++ code generated for the model can be set by set_cppo. In general, the higher the optimization level is set, the faster the generated binary code for the model runs. However, the binary code generated for the model runs fast by using higher optimization level is at the cost of long time to compile the C++ code. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org.

The Stan Development Team CmdStan Interface User’s Guide. http://mc-stan.org. See Also stanc for translating model code in Stan modeling language to C++, sampling for sampling, and stanfit for the ﬁtted results.

see extract and as.array.stanfit for extracting samples from stanfit objects. see set_cppo for setting higher optimization level for compiling the C++ code.

stan Examples

## Not Not run: run: #### ### # exa exampl mple e 1 library(rstan) scod scode e <- " parameters parame ters { real y[2]; } model mod el { y[1] y[1 ] ~ nor normal mal(0, (0, 1); y[2] ~ double double_expon _exponential( ential(0, 0, 2); } " fit1 fit 1 <- stan(m stan(mode odel_c l_code ode = sco scode, de, iter = 10, verbose verbose = FALSE) FALSE) print(fit1) fit2 fit2 <- stan stan(f (fit it = fi fit1 t1, , iter iter = 10 1000 000, 0, ve verb rbos ose e = FALSE FALSE) ) ## extr extrac act t sa samp mple les s as a li list st of ar arra rays ys e2 <- ext extrac ract(f t(fit2 it2, , per permute muted d = TRU TRUE) E) ## using using as. as.arr array ay on the stanfit stanfit object object to get samples samples a2 <- as.arr as.array(fit ay(fit2) 2) #### exa #### exampl mple e 2 #### ### # the resul result t of this this pac packag kage e is includ included ed in the package package excode <excode transformed transf ormed data { real y[20]; y[1] y[1] < <- 0. 0.57 5796 96; ; y[2] y[2] <- 0.2 0.227 276; 6; y[4] y[4] < <- -0 -0.3 .374 742; 2; y[5] y[5] <- 0.3 0.388 885; 5; y[7] y[7] < <- 0. 0.71 7111 11; ; y[8] y[8] <- 1.4 1.442 424; 4; y[10 y[10] ] <- 0.37 0.3746 46; ; y[11] y[11] <- 0.4773 0.4773; ; y[13] y[1 3] <- 0.5 0.5215 215; ; y[14] <- -1.604 -1.6044; 4; y[16 y[16] ] <- 0.94 0.9459 59; ; y[17] y[17] <- -0.382 -0.382; ; y[19] y[1 9] <- 0.1006 0.1006; ; y[20 y[20] ] <- -1.746 -1.7461; 1; } parameters parame ters { real rea l mu; real<lower=0 real<l ower=0, , upper=10> upper=10> sigma; vector[2] vector [2] z[3]; real<lower=0 real<l ower=0> > alpha; } model mod el { y ~ nor normal mal(mu (mu, , sig sigma); ma); for for (i in 1: 1:3) 3) z[i] z[i ] ~ normal normal(0, (0, 1); alpha ~ exponential(2 exponential(2); ); } 

y[3] y[3] <<- -0.2 -0.295 959; 9; y[ y[6] 6] <<- -2.15 -2.1585 85; ; y[9] y[9] <<- 2.54 2.5430 30; ; y[ y[12 12] ] <- 0.1803 0.1803; ; y[15] y[15] <- -0.6 -0.6703 703; ; y[ y[18 18] ] <- 0.7619 0.7619; ;



exfit exf it <- stan(m stan(mode odel_c l_code ode = exc excode ode, , sav save_d e_dso so = FALSE, FALSE, iter iter = 500) 500)

33

34

stanc

print(exfit) plot(exfit) ## End(No End(Not t run run) ) ## Not Not run: run: ## exampl examples es of specif specify y argu argumen ment t

init for fun functi ction on stan stan





## define define a fun functi ction on to genera generate te initia initial l val values ues that can ## be fed fed to func functi tion on stan stan s argume argument nt init # fun functi ction on for form m 1 wit without hout arguments arguments initf1 ini tf1 <- fun functi ction( on() ) { list list(m (mu u = 1, si sigm gma a = 4, z = ar arra ray( y(rn rnor orm( m(6) 6), , di dim m = c( c(3, 3,2) 2)), ), al alph pha a = 1) } # fun functi ction on form 2 with with an argume argument nt named chain_id initf2 ini tf2 <- fun functi ction( on(cha chain_i in_id d = 1) { # cat("c cat("chai hain_i n_id d =", chai chain_i n_id, d, "\n") "\n") list list(m (mu u = 1, si sigm gma a = 4, z = ar arra ray( y(rn rnor orm( m(6) 6), , di dim m = c( c(3, 3,2) 2)), ), al alph pha a = ch chai ain_ n_id) id) } 









# gen genera erate te a list list of lists lists to specif specify y ini initia tial l val values ues n_chains n_chai ns <- 4 init_ll init_l l <- lapply lapply(1:n_c (1:n_chains, hains, function(id) function(id) initf2 initf2(chain_ (chain_id id = id)) exfit0 <- sta exfit0 stan(m n(mode odel_c l_code ode = exc excode ode, , ini init t = initf1 initf1) ) stan(f sta n(fit it = exfit0 exfit0, , ini init t = ini initf2 tf2) ) stan(f sta n(fit it = exfit0 exfit0, , ini init t = ini init_l t_ll, l, chains chains = n_c n_chain hains) s) ## End(No End(Not t run run) )

stanc

Tra Translate nslate Stan model speciﬁcation to C++ code

Description Translate Stan model speciﬁcation to C++ code, which can then be compiled and loaded for sampling. Usage stanc(fil stanc (file, e, mode model_cod l_code e =

, mod model_ el_nam name e = "an "anon_ on_mod model" el", , ver verbos bose e = FAL FALSE, SE, ... ...) )



Arguments file

A char characte acterr stri string ng or a conne connectio ction n that R supports specifying the Stan model speciﬁcation in Stan’s modeling language.

model_code

A character character string either containing a Sta Stan n model model spec speciﬁcation iﬁcation or the the nam namee of a character string object in the workspace. This parameter is used only if parameter file is not speciﬁed, so it defaults to empty string.

stanc model_name

A character string naming the model. The default is "anon_model". However, However, the model name would be derived from file or model_code (if  model_code model_code is the name of a character string object) if  model_name model_name is not speciﬁed. TRUE print out more intermediate information during the translation procedure; FALSE otherwise. The default is FALSE.

verbose ...

35

optional parameters including 1. obfuscate_model_name (logical), TRUE if not not speci speciﬁe ﬁed. d. If   FALSE, the model name in the generated C++ code would not contain randomly generated character string so that if model names are given the same, the generated C++ code will have the same class names deﬁning the model, and the same Rcpp module names, which is used for R to execute the C++ code for sampling. Generally, it is recommended not to specify this parameter or set it to TRUE.

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 speciﬁcation. 3. cppcode Character string for the model’s C++ code. 4. status Logical indicating success/failure (TRUE/FALSE) of translating the Stan code. Note Unlike R, in which variable identiﬁers may contain dots (e.g. a.1 ), Stan prohibits dots from occurring in variable identiﬁers. Further, 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 Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. The Stan Development Team CmdStan Interface User’s Guide. http://mc-stan.org. See Also stan_model and stan

Examples ## Not Not run: run: stanmodelcod stanmo delcode e <- " data data { int<lower=0> int<lo wer=0> N; real y[N]; }

36

stanﬁt-class

parameters { parameters real rea l mu; } model { model mu ~ nor normal mal(0, (0, 10); y ~ nor normal mal(mu (mu, , 1); } " r <- stanc( stanc(model_ model_code code = stanmodelcod stanmodelcode, e, model_name model_name = "normal1") "normal1") names(r) cat(r$cppcode) ## End(No End(Not t run run) )

stanfit-class

Class stanfit: ﬁtted Stan mode modell

Description The output derived from ﬁtting a Stan model, including the samples, as returned by the top-level function stan or the lower-level sampling method sampling deﬁned on class stanmodel. print and plot and other methods are provided for the summaries of the ﬁtted results. Access methods allow the underlying data making up a ﬁt to be retrieved. There are three modes; sampling mode, test gradient mode, error mode (no samples included). The model’s functions for computing the log probability density lp__ and the gradient are also exposed for a stanﬁt object. Objects from the Class Object Obj ectss sho should uld be cre create ated d by eit either her cal callin ling g fun functi ction on stan or sampling meth method od in S4 cl clas asss stan_model. Slots model_name: The model name, object of type character model_pars: The names of parameters (or transformed parameters, derived quantities), object of type character par_dims: The dimensions for all parameters, object of type list mode: Th Thee mode mode of the the ﬁt ﬁtte ted d mode model, l, o obj bjec ectt of type type integer. 0 indi indicate catess sampling sampling mode; mode; 1 indicates test gradient mode for which no sampling is done; 2 ; error error occurred before before samp sampling. ling. Most methods for stanfit are useful only for mode=0 sim: Simulation results including samples for the model, object of type list inits: The initial values either speciﬁed speciﬁed or generated randomly for all chains, object of type list

containing named lists corresponding to initial values in the chains. stan_args: The arguments used for sampling all chains, object of type list stanmodel: The instance of S4 class stanmodel date: The date the object is created .MISC: Miscellaneous helper information used for the ﬁtted model, object of type environment

stanﬁt-class

37

Methods show signa signature( ture(objec object t = "sta "stanfit" nfit") ): print the default summary for the model. plot plot signa signatu ture re(x (x = "sta "stanf nfit it", ", y = "mis "missi sing ng") "): plot an overvie overview w of summ summarie ariess for all parameters (see plot). summary summ ary signa signature( ture(objec object t = "stan "stanfit") fit"): summarizes the distributions of quantities using the

samples: the quantiles (for example, 2.5%, 50%, 97.5%, which can be speciﬁed by using parameter probs), the mean, the standard deviation (sd), the effective sample size (n_eff), and the split Rhat (i.e., potential scale reduction derived from all chains after splitting each chain in half and treating treating the halv halves es as chai chains). ns). Retu Returned rned is a name named d list with element elementss such as summary and c_summary, summaries for all chains merged without warmup and individual chains. chai ns. For the summary of all chai chains ns merged merged,, we also have se_mean, the standard error of the mean. In addition to parameters, parameters, the log-posterior (lp__) is also a quantity of interest in the summary. To specify parameters of interest, use parameter pars. The default for pars is all the parameters saved in the ﬁtted results as well as the log-posterior. Another argument for summary is use_cache, which defaults to TRUE. When use_cache=TRUE, the summary quantities for all parameters are computed and cached for future use. So use_cache=FALSE can be used to avoid the computing of all parameters if  pars is given as some speciﬁc parameters. extract extr act signa signature( ture(objec object t = "stan "stanfit" fit") ): get the samples for all chains for all (or speciﬁed)

see as.array.stanﬁt as.array.stanﬁt for for coercing samples without warmup to parameters. (see extract). Also see arrays or matrices. as.mcmc.list signature(object = "stanfit"): rret etur urn n a li list st of al alll the the chai chains ns that that can can be tr trea eate ted d package coda.. Parameter of interest can be speciﬁed using pars. The as an mcmc.list as in package coda

warmup samples are discarded. traceplot trac eplot signa signature( ture(objec object t = "stan "stanfit") fit"): plot the trace of chains (see traceplot). get_poste get_ posterior_ rior_mean mean signa signature ture(obje (object ct = "sta "stanfit" nfit") ): get the posterior mean for parameters of interest (using pars to specify) among all parameters. get_stanc get_ stancode ode signa signature( ture(objec object t = "stan "stanfit") fit"): get the Stan code for the ﬁtted model. get_cppo_ get_ cppo_mode mode signature(o signature(object bject = "stan "stanfit") fit"): get the optimizat optimization ion mode used for compiling pili ng the model associa associated ted with this ﬁtted resul results. ts. The returned returned string is one of   "fast", "presentation2", "presentation1", and "debug". get_stanm get_ stanmodel odel sign signature ature(obje (object ct = "stan "stanfit") fit"): get the object of S4 class stanmodel of the

ﬁtted model. get_inits get_ inits signa signature( ture(objec object t = "sta "stanfit" nfit") ): get the initial values for parameters used in sampling all chains. For mode=2, it returns an empty list. get_seed get_ seed signa signature ture(obje (object ct = "stan "stanfit") fit"): get the seed seed that used fo forr sampl sampling ing.. Whe When n the ﬁtted object is empty ( mode=2), NULL might be returned. returned. In the case the seeds for all chains are different, use get_seeds. get_seeds get_ seeds signa signature( ture(objec object t = "sta "stanfit" nfit") ): get the seeds that used for all chains. When the ﬁtted object is empty (mode=2), NULL might be returned. get_logpo get_ logposteri sterior or signa signature( ture(objec object t = "sta "stanfit" nfit") ): get the log-posterio log-posteriorr (up to an additi additive ve

constant, which is up to a mult constant, multipli iplicati cative ve constant constant on the linear scal scale) e) for all chains. chains. Each element of the returned list is the log-posterior for a chain. Optional parameter inc_warmup indicates whether to include the warmup period.

38

stanﬁt-class

get_adaptation_info get_adaptation_inf o signature(object = "stanfit"): obtain the adaptation information for

sampler, which now only NUTS2 has. The results are returned as a list, each element of which is a character string for a chain. obtain the paramet parameters ers used for the get_sampl get_ sampler_pa er_params rams signat signature(o ure(object bject = "stan "stanfit") fit"): obtain sampler such as stepsize and treedepth. The results are returned as a list, each element of wh whic ich h is an arra array y for for a chai chain. n. Th Thee arra array y ha hass nu numb mber er of colu column mnss co corr rres espo pond ndin ing g to the the nu numb mber er of parameters used in the sampler and its column names provide the parameter names. Optional parameter inc_warmup indicates whether to include the warmup period. log_prob log_ prob signature signature(obje (object ct = "stan "stanfit", fit", "nume "numeric" ric") ): compute the log probability density (lp__) for a set of parameter values (on the unconstrained  space) space) up to an additive constant.

The unconstrained parameters are speciﬁed using a numeric vector. vector. The number of parameters on the unconstrained space can be obtained using method get_num_upars. A numeric value is returned. grad_log_ grad _log_prob prob signature(obj signature(object ect = "sta "stanfit" nfit", , "nume "numeric" ric") ): compute compute the gradient gradient of log probability density function for a set of parameter values (on the unconstrained  space) space) up to

an additive constant. The unconstrained parameters are speciﬁed using a numeric vector with the length being the number of unconstrained parameters. A numeric vector is returned with the length of the number of unconstrained parameters and an attribute named log_prob being the lp__. get_num_u get_ num_upars pars sign signature ature(obje (object ct = "stan "stanfit" fit") ): 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 speciﬁed as a simplex of length K, the number of unconstrained parameters is K-1. unconstra unco nstrain_pa in_pars rs signa signature( ture(objec object t = "stan "stanfit", fit", "list "list") "): transform the parameter to un-

constrained space. The input is a named list as for specifying initial values for each parameter. A numeric vector is returned. constrain cons train_pars _pars signa signature( ture(objec object t = "stan "stanfit", fit", "nume "numeric") ric"): get the param paramete eterr value valuess fr from om

theirr unconstr thei unconstraine ained d space. The input is a nume numeric ric vector. vector. A list is returned. returned. This function function is contrary to unconstrain_pars. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org.

See Also stan and stanmodel

Examples ## Not Not run: run: showClass("stanfit") ecode eco de <parameters parame ters { real<lower=0 real<l ower=0> > y[2]; } model mod el { 

stanﬁt-class y ~ expone exponential( ntial(1); 1); } 

fit fit <- stan stan(m (mod odel el_c _cod ode e = ecod ecode, e, it iter er = 10 10, , ch chai ains ns = 1) fit2 fit 2 <- stan(f stan(fit it = fit fit) ) print(fit2) plot(fit2) traceplot(fit2) ainfo <- get_ad get_adaptati aptation_info on_info(fit2) (fit2) cat(ainfo[[1]]) seed <- get_se get_seed(fit ed(fit2) 2) sp <- get_sa get_sampler_ mpler_params( params(fit2) fit2) sp2 <- get_sampler_ get_sampler_params( params(fit2, fit2, inc_warmup = FALSE) head(sp[[1]]) lp <- log log_pr _prob( ob(fit fit, , c(1 c(1, , 2)) grad <- grad_l grad grad_log_ og_pro prob(f b(fit, it, c(1, c(1, 2)) lp2 <- attr(g attr(grad rad, , "lo "log_pr g_prob" ob") ) # sho should uld be the same as "lp" "lp" # get the number number of par paramet ameters ers on the unconstra unconstrained ined space n <- get_nu get_num_upar m_upars(fit) s(fit) # par parame ameter ters s on the pos positiv itive e rea real l lin line e (co (const nstrai rained ned space) space) y1 <- list list(y (y = re rep( p(1, 1, 2)) uy <- uncons unconstrain_ train_pars(fi pars(fit, t, y1) ## uy shou should ld be c( c(0, 0, 0) si sinc nce e he here re th the e lo log g tr tran ansf sform ormat atio ion n is us used ed y1star <- constrain_pa constrain_pars(fit, rs(fit, uy) print(y1) print( pri nt(y1s y1star tar) ) # y1star y1start t sho should uld equ equal al to y1 ## End(No End(Not t run run) ) # Cre Create ate a sta stanfi nfit t obj object ect from readin reading g CSV files of sample samples s (sa (saved ved in rst rstan an # pac packag kage) e) gen genera erated ted by funtio funtion n sta stan n for dem demons onstrat tration ion pur purpos pose e fro from m mod model el as follow follows. s. # excode exc ode < 

transformed data { transformed real y[20]; y[1] y[1] < <- 0. 0.57 5796 96; ; y[2] y[2] <- 0.2 0.227 276; 6; y[4] y[4] < <- -0 -0.3 .374 742; 2; y[5] y[5] <- 0.3 0.388 885; 5; y[7] y[7] < <- 0. 0.71 7111 11; ; y[8] y[8] <- 1.4 1.442 424; 4; y[10 y[10] ] <- 0.37 0.3746 46; ; y[11] y[11] <- 0.4773 0.4773; ; y[13] y[1 3] <- 0.5 0.5215 215; ; y[14] <- -1.604 -1.6044; 4; y[16 y[16] ] <- 0.94 0.9459 59; ; y[17] y[17] <- -0.382 -0.382; ; y[19] y[1 9] <- 0.1006 0.1006; ; y[20 y[20] ] <- -1.746 -1.7461; 1; } parameters parame ters { real rea l mu; real<lower=0 real<l ower=0, , upper=10> upper=10> sigma; vector[2] vector [2] z[3]; real<lower=0 real<l ower=0> > alpha;

y[3] y[3] <<- -0.2 -0.295 959; 9; y[ y[6] 6] <<- -2.15 -2.1585 85; ; y[9] y[9] <<- 2.54 2.5430 30; ; y[ y[12 12] ] <- 0.1803 0.1803; ; y[15] y[15] <- -0.6 -0.6703 703; ; y[ y[18 18] ] <- 0.7619 0.7619; ;

39

40

stanmodel-class

} model mod el { y ~ nor normal mal(mu (mu, , sig sigma); ma); for for (i in 1: 1:3) 3) z[i] z[i ] ~ normal normal(0, (0, 1); alpha ~ exponential(2 exponential(2); ); } 

# exf exfit it <- stan(m stan(mode odel_c l_code ode = exc excode ode, , sav save_d e_dso so = FALSE, FALSE, iter iter = 200 200, , # sample_file = "rstan_doc_ex.csv") # exfit <- read_s read_stan_cs tan_csv(dir(s v(dir(system. ystem.file( file( misc , pa packa ckage ge = rstan ), pattern= rstan_doc_ex_[[:digit:]].csv , full.names full.n ames = TRUE)) 











print(exfit) plot(exfit) adaptinfo <- get_adaptatio adaptinfo get_adaptation_info n_info(exfit (exfit) ) seed <- get_se get_seed(exf ed(exfit) it) sp <- get_sa get_sampler_ mpler_params( params(exfit) exfit)

stanmodel-class

Class repr representing esenting model compiled from C++

Description A stanmodel object represents the model compiled from C++ code. The sampling method deﬁned in this class may be used to draw samples from the model and optimizing method is for obtaining a point estimate by maximizing the log-posterior.

Objects from the Class Instances of  stanmodel stanmodel are usually created by calling function stan_model or function stan.

Slots model_name: The model name, an object of type character. model_code: The Stan model speciﬁcation, an object of type character. model_cpp: Object of type list that includes the C++ code for the model. dso: Object of S4 class cxxdso. The container for the dynamic shared objects compiled from the C++ code of the model, returned from function cxxfunction in package inline package inline..

stan_demo

41

Methods show signa signature( ture(objec object t = "sta "stanmode nmodel") l"): print the Stan model speciﬁcation. sampling samp ling signature signature(obje (object ct = "stan "stanmodel model") "): draw samples for the model (see sampling). optimizin opti mizing g signa signature( ture(obje object ct = "stan "stanmodel model") "): obtain obtain a point estimate estimate by maximi maximizing zing the posterior (see optimizing). get_cppco get_ cppcode de signature(o signature(object bject = "stan "stanmode model") l"): ret return urn the C++ C++ code for the mod model el as a

character string. character string. This is part of the C++ code that is compiled compiled to the dynam dynamic ic shared objec objectt for the model. return the CXXFLAGS used for compiling get_cxxfl get_ cxxflags ags signature(obje signature(object ct = "sta "stanmode nmodel") l"): return the model. The returned string is like CXXFLA CXXFLAGS GS = -O3.

Note Objects of class stanmodel can be saved for use across R sessions only if   s save ave_ds _dso o = TRU TRUE E is set during calling functions that create stanmodel objects (e.g., stan and stan_model). Even if   save save_ds _dso o = TRU TRUE E, the model cannot be loaded on a platform (operating system, 32 bits or 64 bits, etc.) that differs from the one on which it was compiled. See Also stanc

Examples showClass("stanmodel")

stan_demo

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 list created from matching user input and gets ﬁtted in the demonstration.

Usage stan_demo stan_ demo(mode (model l = chara character( cter(0), 0), metho method d = c("sa c("sampli mpling", ng", "opti "optimizi mizing"), ng"), ...)

42

stan_model

Arguments

model

Whether to call sampling (the default) or call optimizing for the demonstration

method ...

A character character stri string ng for mode modell name to specify specify which mode modell will be used for demonstration. The default is an empty string, which prompts the user to select one the availa available ble models. models. If   model = 0, a character vector of all models is returned without any user intervention. If   mod model el = i where i > 0, then the ith available model is chosen without user intervention, which is useful for testing.

Further arguments passed to method.

Value An S4 object of  stanfit stanfit, unless mod model el = 0, in which case a character vector of paths to available models is returned. References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. See Also sampling, optimizing

Examples model_names <- gsub(".stan$" model_names gsub(".stan$", , "", basename(sta basename(stan_demo( n_demo(0))) 0))) print(model_names) ## Not Not run: run: dogsfi dog sfit t <- stan_d stan_demo( emo("do "dogs" gs") ) # run the dog dogs s mode model l fit1 fit 1 <- stan_d stan_demo emo(1) (1) # run mod model_ el_nam names[ es[1] 1] ## End(No End(Not t run run) )

stan_model

Construct a Stan model

Description Construct an instance of S4 class stanmodel from a model speciﬁed in Stan’s modeling language. A stanmodel can be used to draw samp samples les from the model. If the model is supplied in the Stan modeling mode ling language language,, it is ﬁrst transl translated ated to C++ code. The C++ code for the model plus oth other er auxiliary code is compiled into a dynamic shared object (DSO) and then loaded. The loaded DSO for the model can be executed to draw samples, allowing inference to be performed for the model and data.

stan_model

43

Usage stan_mode stan_ model(fil l(file, e, model model_nam _name e = "anon "anon_mode _model", l", model_ mod el_cod code e = "", sta stanc_ nc_ret ret = NUL NULL, L, boost_ boo st_lib lib = NUL NULL, L, eig eigen_ en_lib lib = NUL NULL, L, save_d sav e_dso so = TRU TRUE, E, ver verbos bose e = FAL FALSE, SE, ... ...) )

Arguments A char characte acterr stri string ng or a conne connectio ction n that R supports specifying the Stan model speciﬁcation in Stan’s modeling language.

file

model_name

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

model_code

A character character sstrin tring g eith either er containin containing g the mod model el spec speciﬁca iﬁcation tion or the the name of of a character string object in the workspace; an alternative is to specify the model with parameters file or stanc_ret.

stanc_ret

A named named list returned returned from a pr previ evious ous call to function function stanc. The list list ccan an be used to specify the model instead of using parameter file or model_code.

boost_lib

The path path to a ver version sion of th thee Boost Boost C++ library library to use instea instead d of the the one in the the package. BH package. BH

eigen_lib

The path path to a ver version sion of th thee Eigen Eigen C++ libr library ary to to use instea instead d of the the one in the package. RcppEigen package. RcppEigen

save_dso

Logical with the default of  TRUE TRUE: indication of whether the dynamic shared ob ject (DSO) compiled from the C++ code for the model will be saved or not. If TRUE, we can draw samples from the same model in another R session using the saved DSO (i.e., without compiling the C++ code again). TRUE or FALSE: indication of whether to report intermediate output to the con-

verbose

sole, which might be helpful for debugging. ...

passed to stanc.

Details More details of Stan, including the full user’s guide and reference manual can be found at http:

//mc-stan.org/.

There are three ways to specify the model’s code for stan_model. 1. paramete parameterr model_code, containing character string to whose value is the Stan model speciﬁcation, 2. paramete parameterr file, indicating a ﬁle (or a connection) from which to read the Stan model speciﬁcation, or 3. paramete parameterr stanc_ret, indicating the re-use of a model generated in a previous call to stanc. Value An instance of S4 class stanmodel, which can be used later for drawing samples by calling its sampling function.

44

stan_rdump

References The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. See Also stanmodel and stan

Examples ## Not Not run: run: stan_model(m stan_m odel(model_c odel_code ode =

parame par ameter ters s {re {real al y;} mod model el {y ~ normal normal(0, (0,1); 1);} } )





## End(No End(Not t run run) )

stan_rdump

Dump the data for a Stan model to R dump ﬁle in the limited format that Stan can read.

Description This function takes a vector of names of   R objects and outputs text representations of the objects to a ﬁle or connecti connection. on. The ﬁle creat created ed by stan_rdump is typically used as data input of the Stan package ( package ( http://mc-stan.org/) or sourced into another R session. The usage of this function is very similar to dump in R. Usage stan_r sta n_rdum dump(l p(list ist, , fil file e = "", app append end = FAL FALSE, SE, envir = paren parent.fra t.frame(), me(), width = optio options("w ns("width" idth")$wid )$width, th, quiet qui et = FAL FALSE) SE)

Arguments list

A vector of character string: the names of one or more R objects to be dumped. See the note below.

file

Either a character string naming a ﬁle or a connection connection.. "" indicates output to the console.

append

Logical: if  TRUE TRUE and file is a character string, output will be appended to file; otherwise, it will overwrite the contents of  file file.

envir

The environm environment ent to search for objects.

width

The width for maxi maximum mum chara character cterss on a line line.. The outp output ut is broken broken into lines lines with width.

quiet

Whether Whether to suppress suppress warning warning mess messages ages that would appe appear ar when a var variabl iablee is not found or not supported for dumping (not being numeric or it would not be converted to numeric) or a variable name is not allowed in Stan.

stan_rdump

45

Value An invisible character vector containing the names of the objects that were dumped.

Note stan_rdump only dumps numeric data, which ﬁrst can be a scalar, vector, matrix, or (multidimensional) array. Additional types supported are logical ( TRUE and FALSE), factor, data.frame and a specially structured list.

The conversion for logical variables is to map TRUE to 1 and FALSE to 0. For factor variable, function as.integer is used to do the conversion (If we want to transform a factor f to approximately its original numeric values, see the help of function factor and do the transformation before calling stan_rdump). In the case of  data.frame data.frame, function data.matrix is applied to the data frame before dumping. See the notes in stan in stan for for the specially structured list, which will be converted to array before dumping. stan_rdump will check whether the names of objects are 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 can be found in Stan’s manual. If objects with speciﬁed names are not found, a warning will be issued.

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

See Also dump

Examples # set var variab iables les in global global enviro environme nment nt a <- 17. 17.5 5 b <- c(1 c(1,2, ,2,3) 3) # wri write te var variab iables les a and b to file file ab. ab.dat data.R a.R in working working director directory y stan_rdump(c( a , b ), "ab.dat "ab.data.R") a.R") 







x <- 1; y <- 1:10; 1:10; z <- array( array(1: 1:10 10, , di dim m = c( c(2, 2,5) 5)) ) stan_rdump(l stan_r dump(ls(patt s(pattern ern = ^[xyz] ), "xyz.R "xyz.Rdump") dump") cat(paste(re cat(pa ste(readLine adLines("xyz. s("xyz.Rdump" Rdump"), ), collapse collapse = \n ), unlink("xyz.Rdump") 







\n )





46

stan_version

traceplot-methods

Obtain the version of Stan

Description The stan version is in form of  major.minor.patch; the ﬁrst version version is 1.0.0, indicati indicating ng major version 1, minor version 0 and patch level 0. Functionality only changes with minor versions versions and 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 Team Stan Modeling Language User’s Guide and Reference Manual. http: //mc-stan.org/. See Also stan and stan_model

Examples stan_version()

tr trac acep eplo lott-me meth thod ods s

tr trac acep eplo lot t: draw the trac traces es of the sampl samplee

Description Draw the traceplot corresponding to one or more Markov chains, providing a visual way to inspect sampling behavior and assess mixing across chains and convergence. Usage 



## S4 met method hod for sig signat nature ure stanfit tracep tra ceplot lot(ob (objec ject, t, par pars, s, inc inc_wa _warmu rmup p = TRU TRUE, E, ask = FAL FALSE, SE, nr nrow ow = 4, ncol = 2, win windo dow w = NULL NULL, , ...) ...)

traceplot-methods

47

Arguments

object

pars

An instance of class stanfit. A vector of character string specifying the parameters to be plotted. TRUE or FALSE, indicating whether the warmup sample are included in the trace

inc_warmup

plot; defaults to TRUE TRUE or FALSE, to control (for the current device) whether the user is prompted before starting a new page of output in the case there are a lot of parameters (see devAskNewPage).

ask

nrow

To specify the layout for the traceplots for multiple quantities: number of rows on every page. Together with ncol, the layout would be nrow * ncol. The layout by specifying nrow and ncol takes effects only when the total number is larger than nrow times ncol.

ncol

To spe specif cify y the layout layout for the tracep traceplot lotss for multip multiple le quanti quantitie ties: s: number number of col column umnss on every page.

window

To specify a window of all the iterations for plotting. Default of NULL means plotting all iterations. window needs to be an integer vector of at least length 1; smaller one speciﬁes the starting iteration and the bigger one the last iteration. When there iswindow: only one window=100 integer, it just indicates the starting iteration. Examples of specifying and . window=c(100,1500)

...

Additional parameters passed to the underlying function plot.

Value NULL

Methods traceplot signature(obj signature(object ect = "stan "stanfit") fit") Plot the traces of sample for all chains. See Also devAskNewPage

Examples ## Not Not run: run: library(rstan) fit <- stan(m stan(mode odel_c l_code ode = "pa "param ramete eters rs {real {real y;} mode model l {y ~ normal normal(0, (0,1); 1);}") }") traceplot(fit) ## End(No End(Not t run run) )

# Cre Create ate a sta stanfi nfit t obj object ect from readin reading g CSV files of sample samples s (sa (saved ved in rst rstan an # pac packag kage) e) gen genera erated ted by funtio funtion n sta stan n for dem demons onstrat tration ion pur purpos pose e fro from m mod model el as follow follows. s. # excode exc ode <transformed transf ormed data { 

48

real y[20]; y[1] y[1] < <- 0. 0.57 5796 96; ; y[4] y[4] < <- -0 -0.3 .374 742; 2; y[7] y[7] < <- 0. 0.71 7111 11; ; y[10 y[10] ] <- 0.37 0.3746 46; ; y[13] y[1 3] <- 0.5 0.5215 215; ; y[16 y[16] ] <- 0.94 0.9459 59; ; y[19] y[1 9] <- 0.1006 0.1006; ;

y[2] y[2] y[5] y[5] y[8] y[8] y[11] y[11] y[14] y[17] y[17] y[20 y[20] ]

<<<<<<<-

0.2 0.227 276; 6; 0.3 0.388 885; 5; 1.4 1.442 424; 4; 0.4773 0.4773; ; -1.604 -1.6044; 4; -0.382 -0.382; ; -1.746 -1.7461; 1;

traceplot-methods

y[3] y[3] <<- -0.2 -0.295 959; 9; y[ y[6] 6] <<- -2.15 -2.1585 85; ; y[9] y[9] <<- 2.54 2.5430 30; ; y[ y[12 12] ] <- 0.1803 0.1803; ; y[15] y[15] <- -0.6 -0.6703 703; ; y[ y[18 18] ] <- 0.7619 0.7619; ;

} parameters parame ters { real rea l mu; real<lower=0 real<l ower=0, , upper=10> upper=10> sigma; vector[2] vector [2] z[3]; real<lower=0 real<l ower=0> > alpha; } model mod el { y ~ nor normal mal(mu (mu, , sig sigma); ma); for for (i in 1: 1:3) 3) z[i] z[i ] ~ normal normal(0, (0, 1); alpha ~ exponential(2 exponential(2); ); } 

# exf exfit it <- stan(m stan(mode odel_c l_code ode = exc excode ode, , sav save_d e_dso so = FALSE, FALSE, iter iter = 200 200, , # sample_file = "rstan_doc_ex.csv") # exfit <- read_s read_stan_cs tan_csv(dir(s v(dir(system. ystem.file( file( misc , pa packa ckage ge = rstan ), pattern= rstan_doc_ex_[[:digit:]].csv , full.names full.n ames = TRUE)) 











print(exfit) ## only only pri print nt some some par paramet ameters ers print(exfit, print( exfit, pars = c("sigma", c("sigma", "alpha")) "alpha")) traceplot(exfit) traceplot(ex tracep lot(exfit, fit, pars = "sigma") "sigma") ## make make tra tracep ceplot lots s of z[1,1], z[1,1], z[1 z[1,2] ,2], , z[2 z[2,1] ,1], , z[2 z[2,2] ,2] tracep tra ceplot lot(ex (exfit fit, , par pars s = pas paste0 te0("z ("z[", [", c(1, 1, 2, 2), ",", c(1, c(1, 2, 1, 2), "]"))

Index Topic classes

get_adaptation_info ( stanfit-class), 36 get_adaptation_info,stanfit-method (stanfit-class), 36 get_cppcode ( stanmodel-class), 40 get_cppcode,stanmodel-method (stanmodel-class), 40 get_cppo ( cppo), 6 get_cppo_mode ( stanfit-class), 36 get_cppo_mode,stanfit-method (stanfit-class), 36 get_cxxflags ( stanmodel-class), 40 get_cxxflags,stanmodel-method (stanmodel-class), 40 get_inits ( stanfit-class), 36 get_inits,stanfit-method (stanfit-class), 36 get_logposterior ( stanfit-class), 36 get_logposterior,stanfit,logical-method (stanfit-class), 36 get_num_upars ( log_prob-methods), 10 get_num_upars,stanfit-method (log_prob-methods), 10 get_posterior_mean ( stanfit-class), 36 get_posterior_mean,stanfit-method (stanfit-class), 36

∗

stanfit-class, 36 stanmodel-class, 40

Topic methods

∗

extract-methods, 7 plot-methods, 18 traceplot-methods, 46

Topic package

∗

rstan-package, 2 ∗Topic rstan

makeconf_path, 13 read_rdump, 21 rstan-package, 2 rstan_options, 23 stan, 28 stan_model, 42 stan_rdump, 44 stan_version, 46 as.array, 4 as.array.stanfit, 8 , 32 , 37 as.data.frame.stanfit ( as.array), 4 as.matrix.stanfit ( as.array), 4 connection, 44 constrain_pars ( log_prob-methods), 10 constrain_pars,stanfit-method (log_prob-methods), 10 cppo, 6

get_sampler_params, 17 get_sampler_params ( stanfit-class), 36 get_sampler_params,stanfit,logical-method (stanfit-class), 36 get_seed ( stanfit-class), 36 get_seed,stanfit-method (stanfit-class), 36 get_seeds ( stanfit-class), 36 get_seeds,stanfit-method (stanfit-class), 36 get_stancode ( stanfit-class), 36 get_stancode,stanfit-method (stanfit-class), 36 get_stanmodel ( stanfit-class), 36

devAskNewPage, 19 , 47 dim.stanfit ( as.array), 4 dimnames.stanfit ( as.array), 4 dump, 21 , 45 extract, 5 , 17  , , 18 18 , 32 , 37 extract ( extract-methods), 7 extract,stanfit-method (extract-methods), 7 extract-methods, 7

49

50

INDEX

get_stanmodel,stanfit-method (stanfit-class), 36 grad_log_prob ( log_prob-methods), 10 grad_log_prob,stanfit-method (log_prob-methods), 10

smoothScatter, 18 source, 44 28 , 35 , 38 , 44 – 44 – 4 stan, 3 , 7 , 13 , 15 , 24 24 – – 2 27 7 , 28, 46 6 stan_demo, 41 stan_model, 7 , 35 , 42, 42 , 46

is.array.stanfit ( as.array), 4

stan_rdump, 21 , 44 stan_version, 46 stanc, 32 , 34, 34 , 41 stanfit, 3 – 3 – 5, 8 , 11 , 11 , 12 12 , 14 , 18  , , 19 19 , 21 – 21 – 2 23 3, 25 , 32, 47 stanfit-class, 36 stanmodel, 15 , 15 , 16 16 , 24 , 25 , 38 , 43 43 , , 44 44 24 , 25 stanmodel-class, 40 summary,stanfit-method ( stanfit-class),

log_prob ( log_prob-methods), 10 log_prob,stanfit-method (log_prob-methods), 10 log_prob-methods, 10 makeconf_path, 13 mcmc.list, 37 monitor, 8 , 13 optimizing, 41 , 41 , 42 42 optimizing ( optimizing-methods), 15 optimizing,stanmodel-method (optimizing-methods), 15 optimizing-methods, 15 pairs, 17  , 18 , 18 pairs.stanfit, 17 plot, 37 plot,stanfit,missing-method (plot-methods), 18 plot-methods, 18 points, 18 print, 20 read_rdump, 21 read_stan_csv, 22 reset_cppo ( cppo), 6 rstan ( rstan-package), 2 rstan-package, 2 rstan_options, 23 sampling, 32 , 41 , 42 41 , 42 sampling ( sampling-methods), 24 sampling,stanmodel-method (sampling-methods), 24 sampling-methods, 24 set_cppo, 13 , 32 set_cppo ( cppo), 6 sflist2stanfit, 26 show,stanfit-method ( stanfit-class), 36 show,stanmodel-method (stanmodel-class), 40

36 traceplot, 37 traceplot ( traceplot-methods), 46 traceplot,stanfit-method (traceplot-methods), 46 traceplot-methods, 46 unconstrain_pars ( log_prob-methods), 10 unconstrain_pars,stanfit-method (log_prob-methods), 10

Package Rstan'

Comments

Content

Sponsor Documents

Recommended