tar_jags {jagstargets} | R Documentation |
One MCMC per model with multiple outputs
Description
Targets to run a JAGS model once with MCMC and save multiple outputs.
Usage
tar_jags(
name,
jags_files,
parameters.to.save,
data = list(),
summaries = list(),
summary_args = list(),
n.cluster = 1,
n.chains = 3,
n.iter = 2000,
n.burnin = as.integer(n.iter/2),
n.thin = 1,
jags.module = c("glm", "dic"),
inits = NULL,
RNGname = c("Wichmann-Hill", "Marsaglia-Multicarry", "Super-Duper", "Mersenne-Twister"),
jags.seed = 1,
stdout = NULL,
stderr = NULL,
progress.bar = "text",
refresh = 0,
draws = TRUE,
summary = TRUE,
dic = TRUE,
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. |
jags_files |
Character vector of JAGS model files. If you
supply multiple files, each model will run on the one shared dataset
generated by the code in |
parameters.to.save |
Model parameters to save, passed to
|
data |
Code to generate the |
summaries |
List of summary functions passed to |
summary_args |
List of summary function arguments passed to
|
n.cluster |
Number of parallel processes, passed to
|
n.chains |
Number of MCMC chains, passed to
|
n.iter |
Number if iterations (including warmup), passed to
|
n.burnin |
Number of warmup iterations, passed to
|
n.thin |
Thinning interval, passed to
|
jags.module |
Character vector of JAGS modules to load, passed to
|
inits |
Initial values of model parameters, passed to
|
RNGname |
Choice of random number generator, passed to
|
jags.seed |
Seeds to apply to JAGS, passed to
|
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 |
progress.bar |
Type of progress bar, passed to
|
refresh |
Frequency for refreshing the progress bar, passed to
|
draws |
Logical, whether to create a target for posterior draws.
Saves draws as a compressed |
summary |
Logical, whether to create a target to store a small data frame of posterior summary statistics and convergence diagnostics. |
dic |
Logical, whether to create a target with deviance information criterion (DIC) results. |
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 non-data-frame
targets such as the JAGS data and any JAGS fit objects.
Please choose an all=purpose
format 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.
If |
garbage_collection |
Logical, whether to run |
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 of length 1, only relevant to
|
retrieval |
Character of length 1, only relevant to
|
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 |
Details
The MCMC targets use R2jags::jags()
if n.cluster
is 1
and
R2jags::jags.parallel()
otherwise. Most arguments to tar_jags()
are forwarded to these functions.
Value
tar_jags()
returns 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 jags_files
appear in the suffixes where applicable.
As an example, the specific target objects returned by
tar_jags(name = x, jags_files = "y.jags", ...)
returns a list
of targets::tar_target()
objects:
-
x_file_y
: reproducibly track the JAGS model file. Returns a character vector of length 1 with the path to the JAGS model file. -
x_lines_y
: read the contents of the JAGS model file for safe transport to parallel workers. Returns a character vector of lines in the model file. -
x_data
: run the R expression in thedata
argument to produce a JAGS dataset for the model. Returns a JAGS data list. -
x_mcmc_y
: run MCMC on the model and dataset. Returns anrjags
object fromR2jags
with all the MCMC results. -
x_draws_y
: extract posterior samples fromx_mcmc_y
. Returns a tidy data frame of MCMC draws. Omitted ifdraws = FALSE
. -
x_summary_y
: extract posterior summaries fromx_mcmc_y
. Returns a tidy data frame of MCMC draws. Omitted ifsummary = FALSE
. -
x_dic
: extract deviance information criterion (DIC) info fromx_mcmc_y
. Returns a tidy data frame of DIC info. Omitted ifdic = FALSE
.
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.
Examples
if (requireNamespace("R2jags", quietly = TRUE)) {
targets::tar_dir({ # tar_dir() runs code from a temporary directory.
targets::tar_script({
library(jagstargets)
# Do not use a temp file for a real project
# or else your targets will always rerun.
tmp <- tempfile(pattern = "", fileext = ".jags")
tar_jags_example_file(tmp)
list(
tar_jags(
your_model,
jags_files = tmp,
data = tar_jags_example_data(),
parameters.to.save = "beta",
stdout = R.utils::nullfile(),
stderr = R.utils::nullfile()
)
)
}, ask = FALSE)
targets::tar_make()
})
}