tar_stan_vb | R Documentation |
Targets to run a Stan model once with variational Bayes and save multiple outputs.
tar_stan_vb(
name,
stan_files,
data = list(),
compile = c("original", "copy"),
quiet = TRUE,
stdout = NULL,
stderr = NULL,
dir = NULL,
pedantic = FALSE,
include_paths = NULL,
cpp_options = list(),
stanc_options = list(),
force_recompile = FALSE,
seed = NULL,
refresh = NULL,
init = NULL,
save_latent_dynamics = FALSE,
output_dir = NULL,
algorithm = NULL,
iter = NULL,
grad_samples = NULL,
elbo_samples = NULL,
eta = NULL,
adapt_engaged = NULL,
adapt_iter = NULL,
tol_rel_obj = NULL,
eval_elbo = NULL,
output_samples = NULL,
sig_figs = NULL,
variables = NULL,
variables_fit = NULL,
summaries = list(),
summary_args = list(),
return_draws = TRUE,
return_summary = TRUE,
draws = NULL,
summary = NULL,
tidy_eval = targets::tar_option_get("tidy_eval"),
packages = targets::tar_option_get("packages"),
library = targets::tar_option_get("library"),
format = "qs",
format_df = "fst_tbl",
repository = targets::tar_option_get("repository"),
error = targets::tar_option_get("error"),
memory = targets::tar_option_get("memory"),
garbage_collection = targets::tar_option_get("garbage_collection"),
deployment = targets::tar_option_get("deployment"),
priority = targets::tar_option_get("priority"),
resources = targets::tar_option_get("resources"),
storage = targets::tar_option_get("storage"),
retrieval = targets::tar_option_get("retrieval"),
cue = targets::tar_option_get("cue"),
description = targets::tar_option_get("description")
)
name |
Symbol, base name for the collection of targets. Serves as a prefix for target names. |
stan_files |
Character vector of Stan model files. If you
supply multiple files, each model will run on the one shared dataset
generated by the code in |
data |
(multiple options) The data to use for the variables specified in the data block of the Stan program. One of the following:
|
compile |
(logical) Do compilation? The default is |
quiet |
(logical) Should the verbose output from CmdStan during
compilation be suppressed? The default is |
stdout |
Character of length 1, file path to write the stdout stream
of the model when it runs. Set to |
stderr |
Character of length 1, file path to write the stderr stream
of the model when it runs. Set to |
dir |
(string) The path to the directory in which to store the CmdStan
executable (or |
pedantic |
(logical) Should pedantic mode be turned on? The default is
|
include_paths |
(character vector) Paths to directories where Stan
should look for files specified in |
cpp_options |
(list) Any makefile options to be used when compiling the
model ( |
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
|
force_recompile |
(logical) Should the model be recompiled even if was
not modified since last compiled. The default is |
seed |
(positive integer(s)) A seed for the (P)RNG to pass to CmdStan.
In the case of multi-chain sampling the single |
refresh |
(non-negative integer) The number of iterations between
printed screen updates. If |
init |
(multiple options) The initialization method to use for the variables declared in the parameters block of the Stan program. One of the following:
|
save_latent_dynamics |
(logical) Should auxiliary diagnostic information
about the latent dynamics be written to temporary diagnostic CSV files?
This argument replaces CmdStan's |
output_dir |
(string) A path to a directory where CmdStan should write
its output CSV files. For MCMC there will be one file per chain; for other
methods there will be a single file. For interactive use this can typically
be left at
|
algorithm |
(string) The algorithm. Either |
iter |
(positive integer) The maximum number of iterations. |
grad_samples |
(positive integer) The number of samples for Monte Carlo estimate of gradients. |
elbo_samples |
(positive integer) The number of samples for Monte Carlo estimate of ELBO (objective function). |
eta |
(positive real) The step size weighting parameter for adaptive step size sequence. |
adapt_engaged |
(logical) Do warmup adaptation? The default is |
adapt_iter |
(positive integer) The maximum number of adaptation iterations. |
tol_rel_obj |
(positive real) Convergence tolerance on the relative norm of the objective. |
eval_elbo |
(positive integer) Evaluate ELBO every Nth iteration. |
output_samples |
(positive integer) Use |
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 |
variables |
(character vector) The variables to include. |
variables_fit |
Character vector of variables to include in the
big |
summaries |
Optional list of summary functions passed to |
summary_args |
Optional list of summary function arguments passed to
|
return_draws |
Logical, whether to create a target for posterior draws.
Saves |
return_summary |
Logical, whether to create a target for
|
draws |
Deprecated on 2022-07-22. Use |
summary |
Deprecated on 2022-07-22. Use |
tidy_eval |
Logical, whether to enable tidy evaluation
when interpreting |
packages |
Character vector of packages to load right before
the target runs or the output data is reloaded for
downstream targets. Use |
library |
Character vector of library paths to try
when loading |
format |
Character of length 1, storage format of the data frame
of posterior summaries. We recommend efficient data frame formats
such as |
format_df |
Character of length 1, storage format of the data frame
targets such as posterior draws. We recommend efficient data frame formats
such as |
repository |
Character of length 1, remote repository for target storage. Choices:
Note: if |
error |
Character of length 1, what to do if the target stops and throws an error. Options:
|
memory |
Character of length 1, memory strategy. Possible values:
For cloud-based dynamic files
(e.g. |
garbage_collection |
Logical: |
deployment |
Character of length 1. If |
priority |
Numeric of length 1 between 0 and 1. Controls which
targets get deployed first when multiple competing targets are ready
simultaneously. Targets with priorities closer to 1 get dispatched earlier
(and polled earlier in |
resources |
Object returned by |
storage |
Character string to control when the output of the target
is saved to storage. Only relevant when using
|
retrieval |
Character string to control when the current target
loads its dependencies into memory before running.
(Here, a "dependency" is another target upstream that the current one
depends on.) Only relevant when using
|
cue |
An optional object from |
description |
Character of length 1, a custom free-form human-readable
text description of the target. Descriptions appear as target labels
in functions like |
Most of the arguments are passed to the $compile()
,
$variational()
, and $summary()
methods of the CmdStanModel
class.
If you previously compiled the model in an upstream tar_stan_compile()
target, then the model should not recompile.
tar_stan_vb()
returns a list of target objects.
See the "Target objects" section for
background.
The target names use the name
argument as a prefix, and the individual
elements of stan_files
appear in the suffixes where applicable.
As an example, the specific target objects returned by
tar_stan_vb(name = x, stan_files = "y.stan", ...)
are as follows.
x_file_y
: reproducibly track the Stan model file. Returns
a character vector with paths to
the model file and compiled executable.
x_lines_y
: read the Stan model file for safe transport to
parallel workers. Omitted if compile = "original"
.
Returns a character vector of lines in the model file.
x_data
: run the R expression in the data
argument to produce
a Stan dataset for the model. Returns a Stan data list.
x_vb_y
: run variational Bayes on the model and the dataset.
Returns a cmdstanr
CmdStanVB
object with all the results.
x_draws_y
: extract draws from x_vb_y
.
Omitted if draws = FALSE
.
Returns a tidy data frame of draws.
x_summary_y
: extract compact summaries from x_vb_y
.
Returns a tidy data frame of summaries.
Omitted if summary = FALSE
.
Most stantargets
functions are target factories,
which means they return target objects
or lists of target objects.
Target objects represent skippable steps of the analysis pipeline
as described at https://books.ropensci.org/targets/.
Please read the walkthrough at
https://books.ropensci.org/targets/walkthrough.html
to understand the role of target objects in analysis pipelines.
For developers, https://wlandau.github.io/targetopia/contributing.html#target-factories explains target factories (functions like this one which generate targets) and the design specification at https://books.ropensci.org/targets-design/ details the structure and composition of target objects.
Other variational Bayes:
tar_stan_vb_rep_draws()
,
tar_stan_vb_rep_summary()
if (Sys.getenv("TAR_LONG_EXAMPLES") == "true") {
targets::tar_dir({ # tar_dir() runs code from a temporary directory.
targets::tar_script({
library(stantargets)
# Do not use temporary storage for stan files in real projects
# or else your targets will always rerun.
path <- tempfile(pattern = "", fileext = ".stan")
tar_stan_example_file(path = path)
list(
tar_stan_vb(
your_model,
stan_files = path,
data = tar_stan_example_data(),
variables = "beta",
summaries = list(~quantile(.x, probs = c(0.25, 0.75))),
stdout = R.utils::nullfile(),
stderr = R.utils::nullfile()
)
)
}, ask = FALSE)
targets::tar_make()
})
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.