merge doc files for tar_rep*()

Author: wlandau

Diff for: R/tar_rep.R

@@ -3,6 +3,12 @@
 #'   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:
@@ -66,10 +72,22 @@
 #'   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
@@ -113,6 +131,18 @@
 #' })
 #' 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(

Diff for: R/tar_rep2.R

@@ -6,40 +6,83 @@
 #'   <https://books.ropensci.org/targets/dynamic.html#batching>.
 #'   [tar_rep2()] uses dynamic branching to iterate
 #'   over the batches and reps of existing upstream targets.
+#'
+#'   [tar_rep2()] expects unevaluated language for the `name`, `command`,
+#'   and `...` arguments
+#'   (e.g. `tar_rep2(name = sim, command = simulate(), data1, data2)`)
+#'   whereas [tar_rep2_raw()] expects an evaluated string for `name`,
+#'   an evaluated expression object for `command`,
+#'   and a character vector for `targets`
+#'   (e.g.
+#'   `tar_rep2_raw("sim", quote(simulate(x, y)), targets = c("x', "y"))`).
 #' @return A new target object to perform batched computation.
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
 #' @inheritSection tar_rep Replicate-specific seeds
 #' @inheritParams targets::tar_target
 #' @inheritParams tar_rep
+#' @param name Name of the target.
+#'   [tar_rep2()] expects unevaluated language for the `name`, `command`,
+#'   and `...` arguments
+#'   (e.g. `tar_rep2(name = sim, command = simulate(), data1, data2)`)
+#'   whereas [tar_rep2_raw()] expects an evaluated string for `name`,
+#'   an evaluated expression object for `command`,
+#'   and a character vector for `targets`
+#'   (e.g.
+#'   `tar_rep2_raw("sim", quote(simulate(x, y)), targets = c("x', "y"))`).
+#' @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_rep2()] expects unevaluated language for the `name`, `command`,
+#'   and `...` arguments
+#'   (e.g. `tar_rep2(name = sim, command = simulate(), data1, data2)`)
+#'   whereas [tar_rep2_raw()] expects an evaluated string for `name`,
+#'   an evaluated expression object for `command`,
+#'   and a character vector for `targets`
+#'   (e.g.
+#'   `tar_rep2_raw("sim", quote(simulate(x, y)), targets = c("x', "y"))`).
 #' @param ... Symbols to name one or more upstream batched targets
 #'   created by [tar_rep()].
 #'   If you supply more than one such target, all those targets must have the
 #'   same number of batches and reps per batch. And they must all return
 #'   either data frames or lists. List targets must use `iteration = "list"`
 #'   in [tar_rep()].
+#' @param targets Character vector of names of upstream batched targets
+#'   created by [tar_rep()].
+#'   If you supply more than one such target, all those targets must have the
+#'   same number of batches and reps per batch. And they must all return
+#'   either data frames or lists. List targets must use `iteration = "list"`
+#'   in [tar_rep()].
 #' @examples
 #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) {
 #' targets::tar_dir({ # tar_dir() runs code from a temporary directory.
 #' targets::tar_script({
+#'   library(tarchetypes)
 #'   list(
-#'     tarchetypes::tar_rep(
+#'     tar_rep(
 #'       data1,
 #'       data.frame(value = rnorm(1)),
 #'       batches = 2,
 #'       reps = 3
 #'     ),
-#'     tarchetypes::tar_rep(
+#'     tar_rep(
 #'       data2,
 #'       list(value = rnorm(1)),
 #'       batches = 2, reps = 3,
 #'       iteration = "list" # List iteration is important for batched lists.
 #'     ),
-#'     tarchetypes::tar_rep2(
+#'     tar_rep2(
 #'       aggregate,
 #'       data.frame(value = data1$value + data2$value),
 #'       data1,
 #'       data2
+#'     ),
+#'     tar_rep2_raw(
+#'       "aggregate2",
+#'       quote(data.frame(value = data1$value + data2$value)),
+#'       targets = c("data1", "data2")
 #'     )
 #'   )
 #' })

Diff for: R/tar_rep2_raw.R

@@ -1,55 +1,5 @@
-#' @title Dynamic batched computation downstream of [tar_rep()] (raw version).
+#' @rdname tar_rep2
 #' @export
-#' @family branching
-#' @keywords internal
-#' @description Batching is important for optimizing the efficiency
-#'   of heavily dynamically-branched workflows:
-#'   <https://books.ropensci.org/targets/dynamic.html#batching>.
-#'   `tar_rep2_raw()`
-#'   is just like [tar_rep2()] except it accepts a character
-#'   of length 1 for `name`, a language object for `command`,
-#'   and a character vector of the names of the upstream batched targets.
-#' @return A new target object to perform batched computation
-#'   downstream of [tar_rep()].
-#'   See the "Target objects" section for background.
-#' @inheritSection tar_map Target objects
-#' @inheritSection tar_rep Replicate-specific seeds
-#' @inheritParams targets::tar_target
-#' @inheritParams tar_rep
-#' @param targets Character vector of names of upstream batched targets
-#'   created by [tar_rep()].
-#'   If you supply more than one such target, all those targets must have the
-#'   same number of batches and reps per batch. And they must all return
-#'   either data frames or lists. List targets must use `iteration = "list"`
-#'   in [tar_rep()].
-#' @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(
-#'       data1,
-#'       data.frame(value = rnorm(1)),
-#'       batches = 2,
-#'       reps = 3
-#'     ),
-#'     tarchetypes::tar_rep(
-#'       data2,
-#'       list(value = rnorm(1)),
-#'       batches = 2, reps = 3,
-#'       iteration = "list" # List iteration is important for batched lists.
-#'     ),
-#'     tarchetypes::tar_rep2_raw(
-#'       "aggregate",
-#'       quote(data.frame(value = data1$value + data2$value)),
-#'       targets = c("data1", "data2")
-#'     )
-#'   )
-#' })
-#' targets::tar_make()
-#' targets::tar_read(aggregate)
-#' })
-#' }
 tar_rep2_raw <- function(
   name,
   command,

Diff for: R/tar_rep_raw.R

@@ -1,69 +1,5 @@
-#' @title Batched replication with dynamic branching
-#'   (raw version).
+#' @rdname tar_rep
 #' @export
-#' @family branching
-#' @description Batching is important for optimizing the efficiency
-#'   of heavily dynamically-branched workflows:
-#'   <https://books.ropensci.org/targets/dynamic.html#batching>.
-#'   [tar_rep_raw()] is just like [tar_rep()] except the
-#'   name is a character string and the command is a
-#'   language object.
-#' @details `tar_rep_raw()` creates 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.
-#'
-#'   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_rep Replicate-specific seeds
-#' @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)`.
-#' @inheritSection tar_map Target objects
-#' @inheritParams targets::tar_target_raw
-#' @inheritParams tar_rep
-#' @param command Expression object with code to run multiple times.
-#'   Must return a list or data frame when evaluated.
-#' @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 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.
-#' @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_raw(
-#'       "x",
-#'       expression(data.frame(x = sample.int(1e4, 2))),
-#'       batches = 2,
-#'       reps = 3
-#'     )
-#'   )
-#' })
-#' targets::tar_make(callr_function = NULL)
-#' targets::tar_read(x)
-#' })
-#' }
 tar_rep_raw <- function(
   name,
   command,

Diff for: _pkgdown.yml

@@ -56,9 +56,7 @@ reference:
 - title: Dynamic batched replication
   contents:
   - 'tar_rep'
-  - 'tar_rep_raw'
   - 'tar_rep2'
-  - 'tar_rep2_raw'
 - title: Dynamic batched replication within static branches for data frames
   contents:
   - 'tar_map_rep'

Diff for: inst/WORDLIST

@@ -19,6 +19,7 @@ Baltagi
 batchtools
 quosure
 Bengtsson
+unevaluated
 Bioinformatics
 Boneri
 Bostock