Nothing
#' @title Batched replication with dynamic branching.
#' @description Batching is important for optimizing the efficiency
#' of heavily dynamically-branched workflows:
#' <https://books.ropensci.org/targets/dynamic.html#batching>.
#' [tar_rep()] replicates a command in strategically sized batches.
#'
#' [tar_rep()] expects unevaluated `name` and `command` arguments
#' (e.g. `tar_rep(name = sim, command = simulate())`)
#' whereas [tar_rep_raw()] expects an evaluated string for `name`
#' and an evaluated expression object for `command`
#' (e.g. `tar_rep_raw(name = "sim", command = quote(simulate()))`).
#' @export
#' @family branching
#' @details `tar_rep()` and `tar_rep_raw()` each create two targets:
#' an upstream local stem
#' with an integer vector of batch ids, and a downstream pattern
#' that maps over the batch ids. (Thus, each batch is a branch.)
#' Each batch/branch replicates the command a certain number of times.
#' If the command returns a list or data frame, then
#' the targets from `tar_rep()` will try to append new elements/columns
#' `tar_batch`, `tar_rep`, and `tar_seed` to the output
#' to denote the batch, rep-within-batch index, and rep-specific seed,
#' respectively.
#'
#' Both batches and reps within each batch
#' are aggregated according to the method you specify
#' in the `iteration` argument. If `"list"`, reps and batches
#' are aggregated with `list()`. If `"vector"`,
#' then `vctrs::vec_c()`. If `"group"`, then `vctrs::vec_rbind()`.
#' @inheritSection tar_map Target objects
#' @section Replicate-specific seeds:
#' In ordinary pipelines, each target has its own unique deterministic
#' pseudo-random number generator seed derived from its target name.
#' In batched replicate, however, each batch is a target with multiple
#' replicate within that batch. That is why [tar_rep()]
#' and friends give each *replicate* its own unique seed.
#' Each replicate-specific seed is created
#' based on the dynamic parent target name,
#' `tar_option_get("seed")` (for `targets` version 0.13.5.9000 and above),
#' batch index, and rep-within-batch index.
#' The seed is set just before the replicate runs.
#' Replicate-specific seeds are invariant to batching structure.
#' In other words,
#' `tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)`
#' produces the same numerical output as
#' `tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)`
#' (but with different batch names).
#' Other target factories with this seed scheme are [tar_rep2()],
#' [tar_map_rep()], [tar_map2_count()], [tar_map2_size()],
#' and [tar_render_rep()].
#' For the `tar_map2_*()` functions,
#' it is possible to manually supply your own seeds
#' through the `command1` argument and then invoke them in your
#' custom code for `command2` (`set.seed()`, `withr::with_seed`,
#' or `withr::local_seed()`). For [tar_render_rep()],
#' custom seeds can be supplied to the `params` argument
#' and then invoked in the individual R Markdown reports.
#' Likewise with [tar_quarto_rep()] and the `execute_params` argument.
#' @return A list of two targets, one upstream and one downstream.
#' The upstream target returns a numeric index of batch ids,
#' and the downstream one dynamically maps over the batch ids
#' to run the command multiple times.
#' If the command returns a list or data frame, then
#' the targets from `tar_rep()` will try to append new elements/columns
#' `tar_batch`, `tar_rep`, and `tar_seed` to the output
#' to denote the batch, rep-within-batch ID, and random number
#' generator seed, respectively.
#'
#' `tar_read(your_target)` (on the downstream target with the actual work)
#' will return a list of lists, where the outer list has one element per
#' batch and each inner list has one element per rep within batch.
#' To un-batch this nested list, call
#' `tar_read(your_target, recursive = FALSE)`.
#' @inheritParams targets::tar_target
#' @param name Name of the target.
#' [tar_rep()] expects unevaluated `name` and `command` arguments
#' (e.g. `tar_rep(name = sim, command = simulate())`)
#' whereas [tar_rep_raw()] expects an evaluated string for `name`
#' and an evaluated expression object for `command`
#' (e.g. `tar_rep_raw(name = "sim", command = quote(simulate()))`).
#' @param command R code to run multiple times. Must return a list or
#' data frame because `tar_rep()` will try to append new elements/columns
#' `tar_batch` and `tar_rep` to the output to denote the batch
#' and rep-within-batch IDs, respectively.
#'
#' [tar_rep()] expects unevaluated `name` and `command` arguments
#' (e.g. `tar_rep(name = sim, command = simulate())`)
#' whereas [tar_rep_raw()] expects an evaluated string for `name`
#' and an evaluated expression object for `command`
#' (e.g. `tar_rep_raw(name = "sim", command = quote(simulate()))`).
#' @param batches Number of batches. This is also the number of dynamic
#' branches created during `tar_make()`.
#' @param reps Number of replications in each batch. The total number
#' of replications is `batches * reps`.
#' @param rep_workers Positive integer of length 1, number of local R
#' processes to use to run reps within batches in parallel. If 1,
#' then reps are run sequentially within each batch. If greater than 1,
#' then reps within batch are run in parallel using a PSOCK cluster.
#' @param tidy_eval Whether to invoke tidy evaluation
#' (e.g. the `!!` operator from `rlang`) as soon as the target is defined
#' (before `tar_make()`). Applies to the `command` argument.
#' @param iteration Character of length 1, name of the iteration mode
#' of the target. Choices:
#' * `"vector"`: branching happens with `vectors::vec_slice()` and
#' aggregation happens with `vctrs::vec_c()`.
#' * `"list"`, branching happens with `[[]]` and aggregation happens with
#' `list()`. In the case of list iteration, `tar_read(your_target)`
#' will return a list of lists, where the outer list has one element per
#' batch and each inner list has one element per rep within batch.
#' To un-batch this nested list, call
#' `tar_read(your_target, recursive = FALSE)`.
#' * `"group"`: `dplyr::group_by()`-like functionality to branch over
#' subsets of a data frame. The target's return value must be a data
#' frame with a special `tar_group` column of consecutive integers
#' from 1 through the number of groups. Each integer designates a group,
#' and a branch is created for each collection of rows in a group.
#' See the `tar_group()` function in `targets` to see how you can
#' create the special `tar_group` column with `dplyr::group_by()`.
#' @examples
#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) {
#' targets::tar_dir({ # tar_dir() runs code from a temporary directory.
#' targets::tar_script({
#' list(
#' tarchetypes::tar_rep(
#' x,
#' data.frame(x = sample.int(1e4, 2)),
#' batches = 2,
#' reps = 3
#' )
#' )
#' })
#' targets::tar_make()
#' targets::tar_read(x)
#' targets::tar_script({
#' list(
#' tarchetypes::tar_rep_raw(
#' "x",
#' quote(data.frame(x = sample.int(1e4, 2))),
#' batches = 2,
#' reps = 3
#' )
#' )
#' })
#' targets::tar_make()
#' targets::tar_read(x)
#' })
#' }
tar_rep <- function(
name,
command,
batches = 1,
reps = 1,
rep_workers = 1,
tidy_eval = targets::tar_option_get("tidy_eval"),
packages = targets::tar_option_get("packages"),
library = targets::tar_option_get("library"),
format = targets::tar_option_get("format"),
repository = targets::tar_option_get("repository"),
iteration = targets::tar_option_get("iteration"),
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 <- targets::tar_deparse_language(substitute(name))
envir <- targets::tar_option_get("envir")
command <- targets::tar_tidy_eval(substitute(command), envir, tidy_eval)
tar_rep_raw(
name = name,
command = command,
batches = batches,
reps = reps,
rep_workers = rep_workers,
packages = packages,
library = library,
format = format,
repository = repository,
iteration = iteration,
error = error,
memory = memory,
garbage_collection = garbage_collection,
deployment = deployment,
priority = priority,
resources = resources,
storage = storage,
retrieval = retrieval,
cue = cue,
description = description
)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.