Multiple optimization runs per model with summaries
Source:R/tar_stan_mle_rep_summary.R
tar_stan_mle_rep_summary.Rd
tar_stan_mle_rep_summaries()
creates targets
to run maximum likelihood multiple times per model and
save the MLEs in a long-form summary-like data frame.
Usage
tar_stan_mle_rep_summary(
name,
stan_files,
data = list(),
batches = 1L,
reps = 1L,
combine = TRUE,
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,
init_alpha = NULL,
iter = NULL,
tol_obj = NULL,
tol_rel_obj = NULL,
tol_grad = NULL,
tol_rel_grad = NULL,
tol_param = NULL,
history_size = NULL,
sig_figs = NULL,
data_copy = character(0),
variables = NULL,
summaries = list(),
summary_args = list(),
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")
)
Arguments
- name
Symbol, base name for the collection of targets. Serves as a prefix for target names.
- stan_files
Character vector of paths to known existing Stan model files created before running the pipeline.
- 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.
- batches
Number of batches. Each batch is a sequence of branch targets containing multiple reps. Each rep generates a dataset and runs the model on it.
- reps
Number of replications per batch.
- combine
Logical, whether to create a target to combine all the model results into a single data frame downstream. Convenient, but duplicates data.
- 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.- refresh
(non-negative integer) The number of iterations between printed screen updates. If
refresh = 0
, only error messages will be printed.- init
(multiple options) The initialization method to use for the variables declared in the parameters block of the Stan program. One of the following:
A real number
x>0
. This initializes all parameters randomly between[-x,x]
on the unconstrained parameter space.;The number
0
. This initializes all parameters to0
;A character vector of paths (one per chain) to JSON or Rdump files containing initial values for all or some parameters. See
write_stan_json()
to write R objects to JSON files compatible with CmdStan.A list of lists containing initial values for all or some parameters. For MCMC the list should contain a sublist for each chain. For other model fitting methods there should be just one sublist. The sublists should have named elements corresponding to the parameters for which you are specifying initial values. See Examples.
A function that returns a single list with names corresponding to the parameters for which you are specifying initial values. The function can take no arguments or a single argument
chain_id
. For MCMC, if the function has argumentchain_id
it will be supplied with the chain id (from 1 to number of chains) when called to generate the initial values. See Examples.A
CmdStanMCMC
,CmdStanMLE
,CmdStanVB
,CmdStanPathfinder
, orCmdStanLaplace
fit object. If the fit object's parameters are only a subset of the model parameters then the other parameters will be drawn by Stan's default initialization. The fit object must have at least some parameters that are the same name and dimensions as the current Stan model. For thesample
andpathfinder
method, if the fit object has fewer draws than the requested number of chains/paths then the inits will be drawn using sampling with replacement. Otherwise sampling without replacement will be used. When aCmdStanPathfinder
fit object is used as the init, if .psis_resample
was set toFALSE
andcalculate_lp
was set toTRUE
(default), then resampling without replacement with Pareto smoothed weights will be used. Ifpsis_resample
was set toTRUE
orcalculate_lp
was set toFALSE
then sampling without replacement with uniform weights will be used to select the draws. PSIS resampling is used to select the draws forCmdStanVB
, andCmdStanLaplace
fit objects.A type inheriting from
posterior::draws
. If the draws object has less samples than the number of requested chains/paths then the inits will be drawn using sampling with replacement. Otherwise sampling without replacement will be used. If the draws object's parameters are only a subset of the model parameters then the other parameters will be drawn by Stan's default initialization. The fit object must have at least some parameters that are the same name and dimensions as the current Stan model.
- save_latent_dynamics
(logical) Should auxiliary diagnostic information about the latent dynamics be written to temporary diagnostic CSV files? This argument replaces CmdStan's
diagnostic_file
argument and the content written to CSV is controlled by the user's CmdStan installation and not CmdStanR (for some algorithms no content may be written). The default isFALSE
, which is appropriate for almost every use case. To save the temporary files created whensave_latent_dynamics=TRUE
see the$save_latent_dynamics_files()
method.- 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
NULL
(temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in R via methods of the fitted model objects. This can be set for an entire R session usingoptions(cmdstanr_output_dir)
. 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()
.
- algorithm
(string) The optimization algorithm. One of
"lbfgs"
,"bfgs"
, or"newton"
. The control parameters below are only available for"lbfgs"
and"bfgs
. For their default values and more details see the CmdStan User's Guide. The default values can also be obtained by runningcmdstanr_example(method="optimize")$metadata()
.- init_alpha
(positive real) The initial step size parameter.
- iter
(positive integer) The maximum number of iterations.
- tol_obj
(positive real) Convergence tolerance on changes in objective function value.
- tol_rel_obj
(positive real) Convergence tolerance on relative changes in objective function value.
- tol_grad
(positive real) Convergence tolerance on the norm of the gradient.
- tol_rel_grad
(positive real) Convergence tolerance on the relative norm of the gradient.
- tol_param
(positive real) Convergence tolerance on changes in parameter value.
- history_size
(positive integer) The size of the history used when approximating the Hessian. Only available for L-BFGS.
- 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.- data_copy
Character vector of names of scalars in
data
. These values will be inserted as columns in the output data frame for each rep. To join more than just scalars, include a.join_data
element of your Stan data list with names and dimensions corresponding to those of the model. For details, read https://docs.ropensci.org/stantargets/articles/simulation.html.- variables
(character vector) Optionally, the names of the variables (parameters, transformed parameters, and generated quantities) to read in.
If
NULL
(the default) then all variables are included.If an empty string (
variables=""
) then none are included.For non-scalar variables all elements or specific elements can be selected:
variables = "theta"
selects all elements oftheta
;variables = c("theta[1]", "theta[3]")
selects only the 1st and 3rd elements.
- summaries
Optional list of summary functions passed to
...
inposterior::summarize_draws()
through$summary()
on theCmdStanFit
object.- summary_args
Optional list of summary function arguments passed to
.args
inposterior::summarize_draws()
through$summary()
on theCmdStanFit
object.- tidy_eval
Logical, whether to enable tidy evaluation when interpreting
command
andpattern
. IfTRUE
, you can use the "bang-bang" operator!!
to programmatically insert the values of global objects.- packages
Character vector of packages to load right before the target runs or the output data is reloaded for downstream targets. Use
tar_option_set()
to set packages globally for all subsequent targets you define.- library
Character vector of library paths to try when loading
packages
.- format
Character of length 1, storage format of the data frame of posterior summaries. We recommend efficient data frame formats such as
"feather"
or"aws_parquet"
. For more on storage formats, see the help file oftargets::tar_target()
.- 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
"feather"
or"aws_parquet"
. For more on storage formats, see the help file oftargets::tar_target()
.- repository
Character of length 1, remote repository for target storage. Choices:
"local"
: file system of the local machine."aws"
: Amazon Web Services (AWS) S3 bucket. Can be configured with a non-AWS S3 bucket using theendpoint
argument oftar_resources_aws()
, but versioning capabilities may be lost in doing so. See the cloud storage section of https://books.ropensci.org/targets/data.html for details for instructions."gcp"
: Google Cloud Platform storage bucket. See the cloud storage section of https://books.ropensci.org/targets/data.html for details for instructions.A character string from
tar_repository_cas()
for content-addressable storage.
Note: if
repository
is not"local"
andformat
is"file"
then the target should create a single output file. That output file is uploaded to the cloud and tracked for changes where it exists in the cloud. The local file is deleted after the target runs.- error
Character of length 1, what to do if the target stops and throws an error. Options:
"stop"
: the whole pipeline stops and throws an error."continue"
: the whole pipeline keeps going."null"
: The errored target continues and returnsNULL
. The data hash is deliberately wrong so the target is not up to date for the next run of the pipeline. In addition, as oftargets
version 1.8.0.9011, a value ofNULL
is given to upstream dependencies witherror = "null"
if loading fails."abridge"
: any currently running targets keep running, but no new targets launch after that."trim"
: all currently running targets stay running. A queued target is allowed to start if:It is not downstream of the error, and
It is not a sibling branch from the same
tar_target()
call (if the error happened in a dynamic branch).
The idea is to avoid starting any new work that the immediate error impacts.
error = "trim"
is just likeerror = "abridge"
, but it allows potentially healthy regions of the dependency graph to begin running. (Visit https://books.ropensci.org/targets/debugging.html to learn how to debug targets using saved workspaces.)
- memory
Character of length 1, memory strategy. Possible values:
"auto"
: new intargets
version 1.8.0.9011,memory = "auto"
is equivalent tomemory = "transient"
for dynamic branching (a non-nullpattern
argument) andmemory = "persistent"
for targets that do not use dynamic branching."persistent"
: the target stays in memory until the end of the pipeline (unlessstorage
is"worker"
, in which casetargets
unloads the value from memory right after storing it in order to avoid sending copious data over a network)."transient"
: the target gets unloaded after every new target completes. Either way, the target gets automatically loaded into memory whenever another target needs the value.
For cloud-based dynamic files (e.g.
format = "file"
withrepository = "aws"
), thememory
option applies to the temporary local copy of the file:"persistent"
means it remains until the end of the pipeline and is then deleted, and"transient"
means it gets deleted as soon as possible. The former conserves bandwidth, and the latter conserves local storage.- garbage_collection
Logical:
TRUE
to runbase::gc()
just before the target runs,FALSE
to omit garbage collection. In the case of high-performance computing,gc()
runs both locally and on the parallel worker. All this garbage collection is skipped if the actual target is skipped in the pipeline. Non-logical values ofgarbage_collection
are converted toTRUE
orFALSE
usingisTRUE()
. In other words, non-logical values are convertedFALSE
. For example,garbage_collection = 2
is equivalent togarbage_collection = FALSE
.- deployment
Character of length 1. If
deployment
is"main"
, then the target will run on the central controlling R process. Otherwise, ifdeployment
is"worker"
and you set up the pipeline with distributed/parallel computing, then the target runs on a parallel worker. For more on distributed/parallel computing intargets
, please visit https://books.ropensci.org/targets/crew.html.- 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
tar_make_future()
).- resources
Object returned by
tar_resources()
with optional settings for high-performance computing functionality, alternative data storage formats, and other optional capabilities oftargets
. Seetar_resources()
for details.- storage
Character string to control when the output of the target is saved to storage. Only relevant when using
targets
with parallel workers (https://books.ropensci.org/targets/crew.html). Must be one of the following values:"main"
: the target's return value is sent back to the host machine and saved/uploaded locally."worker"
: the worker saves/uploads the value."none"
:targets
makes no attempt to save the result of the target to storage in the location wheretargets
expects it to be. Saving to storage is the responsibility of the user. Use with caution.
- 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
targets
with parallel workers (https://books.ropensci.org/targets/crew.html). Must be one of the following values:"main"
: the target's dependencies are loaded on the host machine and sent to the worker before the target runs."worker"
: the worker loads the target's dependencies."none"
:targets
makes no attempt to load its dependencies. Withretrieval = "none"
, loading dependencies is the responsibility of the user. Use with caution.
- cue
An optional object from
tar_cue()
to customize the rules that decide whether the target is up to date.- description
Character of length 1, a custom free-form human-readable text description of the target. Descriptions appear as target labels in functions like
tar_manifest()
andtar_visnetwork()
, and they let you select subsets of targets for thenames
argument of functions liketar_make()
. For example,tar_manifest(names = tar_described_as(starts_with("survival model")))
lists all the targets whose descriptions start with the character string"survival model"
.
Value
tar_stan_mle_rep_summaries()
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.
The specific target objects returned by
tar_stan_mle_rep_summary(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 ifcompile = "original"
. Returns a character vector of lines in the model file.x_data
: use dynamic branching to generate multiple datasets by repeatedly running the R expression in thedata
argument. Each dynamic branch returns a batch of Stan data lists thatx_y
supplies to the model.x_y
: dynamic branching target to run maximum likelihood once per dataset. Each dynamic branch returns a tidy data frames of maximum likelihood estimates corresponding to a batch of Stan data fromx_data
.x
: combine all branches ofx_y
into a single non-dynamic target. Suppressed ifcombine
isFALSE
. Returns a long tidy data frame of maximum likelihood estimates.
Details
Most of the arguments are passed to the $compile()
and $optimize()
methods of the CmdStanModel
class. If you
previously compiled the model in an upstream tar_stan_compile()
target, then the model should not recompile.
Seeds
Rep-specific random number generator seeds for the data and models
are automatically set based on the seed
argument, batch, rep,
parent target name, and tar_option_get("seed")
. This ensures
the rep-specific seeds do not change when you change the batching
configuration (e.g. 40 batches of 10 reps each vs 20 batches of 20
reps each). Each data seed is in the .seed
list element of the output,
and each Stan seed is in the .seed column of each Stan model output.
Target objects
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.
See also
Other optimization:
tar_stan_mle()
,
tar_stan_mle_rep_draws()
Examples
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_mle_rep_summary(
your_model,
stan_files = path,
data = tar_stan_example_data(),
batches = 2,
reps = 2,
stdout = R.utils::nullfile(),
stderr = R.utils::nullfile()
)
)
}, ask = FALSE)
targets::tar_make()
})
}