Compile and run a Stan model and return the CmdStanFit
object.
Source: R/tar_stan_gq.R
tar_stan_gq_run.Rd
Not a user-side function. Do not invoke directly.
Usage
tar_stan_gq_run(
stan_file,
data,
fitted_params,
compile,
quiet,
stdout,
stderr,
dir,
pedantic,
include_paths,
cpp_options,
stanc_options,
force_recompile,
seed,
output_dir,
sig_figs,
parallel_chains,
threads_per_chain,
variables
)
Arguments
- stan_file
(string) The path to a
.stan
file containing a Stan program. The helper functionwrite_stan_file()
is provided for cases when it is more convenient to specify the Stan program as a string. Ifstan_file
is not specified thenexe_file
must be specified.- data
(multiple options) The data to use for the variables specified in the data block of the Stan program. One of the following:
A named list of R objects with the names corresponding to variables declared in the data block of the Stan program. Internally this list is then written to JSON for CmdStan using
write_stan_json()
. Seewrite_stan_json()
for details on the conversions performed on R objects before they are passed to Stan.A path to a data file compatible with CmdStan (JSON or R dump). See the appendices in the CmdStan guide for details on using these formats.
NULL
or an empty list if the Stan program has no data block.
- fitted_params
(multiple options) The parameter draws to use. One of the following:
A CmdStanMCMC or CmdStanVB fitted model object.
A posterior::draws_array (for MCMC) or posterior::draws_matrix (for VB) object returned by CmdStanR's
$draws()
method.A character vector of paths to CmdStan CSV output files.
NOTE: if you plan on making many calls to
$generate_quantities()
then the most efficient option is to pass the paths of the CmdStan CSV output files (this avoids CmdStanR having to rewrite the draws contained in the fitted model object to CSV each time). If you no longer have the CSV files you can usedraws_to_csv()
once to write them and then pass the resulting file paths to$generate_quantities()
as many times as needed.- compile
(logical) Do compilation? The default is
TRUE
. IfFALSE
compilation can be done later via the$compile()
method.- quiet
(logical) Should the verbose output from CmdStan during compilation be suppressed? The default is
TRUE
, but if you encounter an error we recommend trying again withquiet=FALSE
to see more of the output.- stdout
Character of length 1, file path to write the stdout stream of the model when it runs. Set to
NULL
to print to the console. Set toR.utils::nullfile()
to suppress stdout. Does not apply to messages, warnings, or errors.- stderr
Character of length 1, file path to write the stderr stream of the model when it runs. Set to
NULL
to print to the console. Set toR.utils::nullfile()
to suppress stderr. Does not apply to messages, warnings, or errors.- dir
(string) The path to the directory in which to store the CmdStan executable (or
.hpp
file if using$save_hpp_file()
). The default is the same location as the Stan program.- pedantic
(logical) Should pedantic mode be turned on? The default is
FALSE
. Pedantic mode attempts to warn you about potential issues in your Stan program beyond syntax errors. For details see the Pedantic mode chapter in the Stan Reference Manual. Note: to do a pedantic check for a model without compiling it or for a model that is already compiled the$check_syntax()
method can be used instead.- include_paths
(character vector) Paths to directories where Stan should look for files specified in
#include
directives in the Stan program.- cpp_options
(list) Any makefile options to be used when compiling the model (
STAN_THREADS
,STAN_MPI
,STAN_OPENCL
, etc.). Anything you would otherwise write in themake/local
file. For an example of using threading see the Stan case study Reduce Sum: A Minimal Example.- stanc_options
(list) Any Stan-to-C++ transpiler options to be used when compiling the model. See the Examples section below as well as the
stanc
chapter of the CmdStan Guide for more details on available options: https://mc-stan.org/docs/cmdstan-guide/stanc.html.- force_recompile
(logical) Should the model be recompiled even if was not modified since last compiled. The default is
FALSE
. Can also be set via a globalcmdstanr_force_recompile
option.- seed
(positive integer(s)) A seed for the (P)RNG to pass to CmdStan. In the case of multi-chain sampling the single
seed
will automatically be augmented by the the run (chain) ID so that each chain uses a different seed. The exception is the transformed data block, which defaults to using same seed for all chains so that the same data is generated for all chains if RNG functions are used. The only timeseed
should be specified as a vector (one element per chain) is if RNG functions are used in transformed data and the goal is to generate different data for each chain.- output_dir
(string) A path to a directory where CmdStan should write its output CSV files. For interactive use this can typically be left at
NULL
(temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in R via methods of the fitted model objects. The behavior ofoutput_dir
is as follows:If
NULL
(the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the$save_*
methods of the fitted model object (e.g.,$save_output_files()
). These temporary files are removed when the fitted model object is garbage collected (manually or automatically).If a path, then the files are created in
output_dir
with names corresponding to the defaults used by$save_output_files()
.
- sig_figs
(positive integer) The number of significant figures used when storing the output values. By default, CmdStan represent the output values with 6 significant figures. The upper limit for
sig_figs
is 18. Increasing this value will result in larger output CSV files and thus an increased usage of disk space.- parallel_chains
(positive integer) The maximum number of MCMC chains to run in parallel. If
parallel_chains
is not specified then the default is to look for the option"mc.cores"
, which can be set for an entire R session byoptions(mc.cores=value)
. If the"mc.cores"
option has not been set then the default is1
.- threads_per_chain
(positive integer) If the model was compiled with threading support, the number of threads to use in parallelized sections within an MCMC chain (e.g., when using the Stan functions
reduce_sum()
ormap_rect()
). This is in contrast withparallel_chains
, which specifies the number of chains to run in parallel. The actual number of CPU cores used isparallel_chains*threads_per_chain
. For an example of using threading see the Stan case study Reduce Sum: A Minimal Example.