diff --git a/DESCRIPTION b/DESCRIPTION index dd81d96..a7da5ea 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -9,7 +9,7 @@ Description: Function-oriented Make-like declarative pipelines for reproducible pipelines concisely and compactly. The methods in this package were influenced by the 'drake' R package by Will Landau (2018) . -Version: 0.9.1.9000 +Version: 0.9.1.9001 License: MIT + file LICENSE URL: https://docs.ropensci.org/tarchetypes/, https://github.com/ropensci/tarchetypes BugReports: https://github.com/ropensci/tarchetypes/issues diff --git a/NAMESPACE b/NAMESPACE index d7ae879..872386e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -83,6 +83,7 @@ export(tar_map2) export(tar_map2_count) export(tar_map2_count_raw) export(tar_map2_group) +export(tar_map2_raw) export(tar_map2_run) export(tar_map2_run_rep) export(tar_map2_size) diff --git a/NEWS.md b/NEWS.md index c6fab64..b1f20e7 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,9 @@ -# tarchetypes 0.9.1.9000 (development) +# tarchetypes 0.9.1.9001 (development) * Add a `delimiter` argument to `tar_map()` etc. for customizing separators in target names (#177, @psychelzh). * Add "raw" hook functions (#185, @multimeric). * Add `tar_assign()` (#186, https://github.com/ropensci/targets/issues/1309, @hadley). +* Merge help files of "_raw" functions (#191, @hadley). # tarchetypes 0.9.0 diff --git a/R/tar_cue_age.R b/R/tar_cue_age.R index 2bbcf69..f3032df 100644 --- a/R/tar_cue_age.R +++ b/R/tar_cue_age.R @@ -6,14 +6,32 @@ #' The age of the target is determined by `targets::tar_timestamp()`, #' and the way the time stamp is calculated is explained #' in the Details section of the help file of that function. +#' +#' `tar_cue_age()` expects an unevaluated symbol for the `name` +#' argument, whereas `tar_cue_age_raw()` expects a character string +#' for `name`. #' @details `tar_cue_age()` uses the time stamps from `tar_meta()$time`. #' If no time stamp is recorded, the cue defaults to the ordinary #' invalidation rules (i.e. `mode = "thorough"` in `targets::tar_cue()`). #' @inheritSection tar_age Dynamic branches at regular time intervals #' @return A cue object. See the "Cue objects" section for background. #' @inheritSection tar_cue_force Cue objects -#' @inheritParams tar_cue_age_raw -#' @param name Symbol, name of the target. +#' @inheritSection tar_cue_force Cue objects +#' @inheritParams targets::tar_cue +#' @param name Name of the target. +#' `tar_cue_age()` expects an unevaluated symbol for the `name` +#' argument, whereas `tar_cue_age_raw()` expects a character string +#' for `name`. +#' @param age A `difftime` object of length 1, such as +#' `as.difftime(3, units = "days")`. If the target's output data +#' files are older than `age` (according to the most recent +#' time stamp over all the target's output files) +#' then the target will rerun. +#' On the other hand, if at least one data file is +#' younger than `Sys.time() - age`, then the ordinary +#' invalidation rules apply, and the target may or not rerun. +#' If you want to force the target to run every 3 days, +#' for example, set `age = as.difftime(3, units = "days")`. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. diff --git a/R/tar_cue_age_raw.R b/R/tar_cue_age_raw.R index b7c5b57..aaff038 100644 --- a/R/tar_cue_age_raw.R +++ b/R/tar_cue_age_raw.R @@ -1,53 +1,5 @@ -#' @title Cue to run a target when the last run reaches a certain age -#' (raw version) +#' @rdname tar_cue_age #' @export -#' @family cues -#' @description `tar_cue_age_raw()` acts like `tar_cue_age()` -#' except the `name` argument is a character string, -#' not a symbol. `tar_cue_age_raw()` creates a cue object to -#' rerun a target if the most recent output data becomes old enough. -#' The age of the target is determined by `targets::tar_timestamp()`, -#' and the way the time stamp is calculated is explained -#' in the Details section of the help file of that function. -#' @details `tar_cue_age_raw()` uses the time stamps from `tar_meta()$time`. -#' If no time stamp is recorded, the cue defaults to the ordinary -#' invalidation rules (i.e. `mode = "thorough"` in `targets::tar_cue()`). -#' @inheritSection tar_age Dynamic branches at regular time intervals -#' @return A cue object. See the "Cue objects" section for background. -#' @inheritSection tar_cue_force Cue objects -#' @inheritParams targets::tar_cue -#' @param name Character of length 1, name of the target. -#' @param age A `difftime` object of length 1, such as -#' `as.difftime(3, units = "days")`. If the target's output data -#' files are older than `age` (according to the most recent -#' time stamp over all the target's output files) -#' then the target will rerun. -#' On the other hand, if at least one data file is -#' younger than `Sys.time() - age`, then the ordinary -#' invalidation rules apply, and the target may or not rerun. -#' If you want to force the target to run every 3 days, -#' for example, set `age = as.difftime(3, units = "days")`. -#' @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( -#' targets::tar_target( -#' data, -#' data.frame(x = seq_len(26)), -#' cue = tarchetypes::tar_cue_age_raw( -#' name = "data", -#' age = as.difftime(0.5, units = "secs") -#' ) -#' ) -#' ) -#' }) -#' targets::tar_make() -#' Sys.sleep(0.6) -#' targets::tar_make() -#' }) -#' } tar_cue_age_raw <- function( name, age, diff --git a/R/tar_eval.R b/R/tar_eval.R index 84c116c..0174867 100644 --- a/R/tar_eval.R +++ b/R/tar_eval.R @@ -4,15 +4,24 @@ #' @description Loop over a grid of values, create an expression object #' from each one, and then evaluate that expression. #' Helps with general metaprogramming. +#' +#' [tar_eval()] expects an unevaluated expression for +#' the `expr` object, whereas [tar_eval_raw()] expects an +#' evaluated expression object. #' @return A list of return values from the generated expression objects. #' Often, these values are target objects. #' See the "Target objects" section for background #' on target objects specifically. #' @inheritSection tar_map Target objects -#' @inheritParams tar_eval_raw +#' @inheritParams tar_sub #' @param expr Starting expression. Values are iteratively substituted #' in place of symbols in `expr` to create each new expression, #' and then each new expression is evaluated. +#' +#' [tar_eval()] expects an unevaluated expression for +#' the `expr` object, whereas [tar_eval_raw()] expects an +#' evaluated expression object. +#' @param envir Environment in which to evaluate the new expressions. #' @examples #' # tar_map() is incompatible with tar_render() because the latter #' # operates on preexisting tar_target() objects. By contrast, @@ -27,6 +36,7 @@ #' path <- tempfile() #' file.create(path) #' str(tar_eval(tar_render(name, path), values = values)) +#' str(tar_eval_raw(quote(tar_render(name, path)), values = values)) #' # So in your _targets.R file, you can define a pipeline like as below. #' # Just make sure to set a unique name for each target #' # (which tar_map() does automatically). diff --git a/R/tar_eval_raw.R b/R/tar_eval_raw.R index 6f48a9c..c183f7a 100644 --- a/R/tar_eval_raw.R +++ b/R/tar_eval_raw.R @@ -1,46 +1,5 @@ -#' @title Evaluate multiple expressions created with symbol substitution -#' (raw version). +#' @rdname tar_eval #' @export -#' @family Metaprogramming utilities -#' @description Loop over a grid of values, create an expression object -#' from each one, and then evaluate that expression. -#' Helps with general metaprogramming. Unlike [tar_sub()], -#' which quotes the `expr` argument, `tar_sub_raw()` assumes `expr` -#' is an expression object. -#' @return A list of return values from evaluating the expression objects. -#' Often, these values are target objects. -#' See the "Target objects" section for background -#' on target objects specifically. -#' @inheritSection tar_map Target objects -#' @inheritParams tar_sub_raw -#' @param expr Expression object with the starting expression. -#' Values are iteratively substituted -#' in place of symbols in `expr` to create each new expression, -#' and then each expression is evaluated. -#' @param envir Environment in which to evaluate the new expressions. -#' @examples -#' # tar_map() is incompatible with tar_render() because the latter -#' # operates on preexisting tar_target() objects. By contrast, -#' # tar_eval_raw() and tar_sub_raw() iterate over code farther upstream. -#' values <- list( -#' name = lapply(c("name1", "name2"), as.symbol), -#' file = c("file1.Rmd", "file2.Rmd") -#' ) -#' tar_sub_raw(quote(list(name, file)), values = values) -#' tar_sub_raw(quote(tar_render(name, file)), values = values) -#' path <- tempfile() -#' file.create(path) -#' str(tar_eval_raw(quote(tar_render(name, path)), values = values)) -#' # So in your _targets.R file, you can define a pipeline like as below. -#' # Just make sure to set a unique name for each target -#' # (which tar_map() does automatically). -#' values <- list( -#' name = lapply(c("name1", "name2"), as.symbol), -#' file = c(path, path) -#' ) -#' list( -#' tar_eval_raw(quote(tar_render(name, file)), values = values) -#' ) tar_eval_raw <- function(expr, values, envir = parent.frame()) { targets::tar_assert_lang(expr) assert_values_list(values) diff --git a/R/tar_hook_before.R b/R/tar_hook_before.R index 534720a..77ab933 100644 --- a/R/tar_hook_before.R +++ b/R/tar_hook_before.R @@ -2,21 +2,43 @@ #' @export #' @family hooks #' @description Prepend R code to the commands of multiple targets. +#' `tar_hook_before()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_before_raw()` expects +#' evaluated expression objects. #' @return A flattened list of target objects with the hooks applied. #' Even if the input target list had a nested structure, #' the return value is a simple list where each element is a target object. #' All hook functions remove the nested structure of the input target list. #' @inheritSection tar_map Target objects #' @inheritParams tar_hook_before_raw -#' @param hook R code to insert. When you supply code to this argument, -#' the code is quoted (not evaluated) so there is no need -#' to wrap it in `quote()`, `expression()`, or similar. +#' @param hook R code to insert. +#' `tar_hook_before()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_before_raw()` expects +#' evaluated expression objects. #' @param names Name of targets in the target list -#' to apply the hook. Supplied with `tidyselect` helpers like +#' to apply the hook. Supplied using `tidyselect` helpers like #' [starts_with()], as in `names = starts_with("your_prefix_")`. #' Set to `NULL` to include all targets supplied to the `targets` argument. #' Targets not included in `names` still remain in the target list, #' but they are not modified because the hook does not apply to them. +#' +#' The regular hook functions expects unevaluated expressions for the `hook` +#' and `names` arguments, whereas the `"_raw"` versions expect +#' evaluated expression objects. +#' @param set_deps Logical of length 1, whether to refresh the dependencies +#' of each modified target by scanning the newly generated +#' target commands for dependencies. If `FALSE`, then the target will +#' keep the original set of dependencies it had before the hook. +#' Set to `NULL` to include all targets supplied to the `targets` argument. +#' `TRUE` is recommended for nearly all situations. Only use `FALSE` +#' if you have a specialized use case and you know what you are doing. +#' @param envir Optional environment to construct the quosure for the `names` +#' argument to select names. +#' @param targets A list of target objects. The input target list +#' can be arbitrarily nested, but it must consist entirely of target +#' objects. In addition, the return value is a simple list +#' where each element is a target object. +#' All hook functions remove the nested structure of the input target list. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -38,6 +60,23 @@ #' }) #' targets::tar_manifest(fields = command) #' }) +#' # With tar_hook_before_raw(): +#' targets::tar_script({ +#' targets <- list( +#' # Nested target lists work with hooks. +#' list( +#' targets::tar_target(x1, task1()), +#' targets::tar_target(x2, task2(x1)) +#' ), +#' targets::tar_target(x3, task3(x2)), +#' targets::tar_target(y1, task4(x3)) +#' ) +#' tarchetypes::tar_hook_before_raw( +#' targets = targets, +#' hook = quote(print("Running hook.")), +#' names = quote(starts_with("x")) +#' ) +#' }) #' } tar_hook_before <- function( targets, diff --git a/R/tar_hook_before_raw.R b/R/tar_hook_before_raw.R index 109104c..93c6759 100644 --- a/R/tar_hook_before_raw.R +++ b/R/tar_hook_before_raw.R @@ -1,56 +1,5 @@ -#' @title Hook to prepend code (raw version) +#' @rdname tar_hook_before #' @export -#' @family hooks -#' @description Prepend R code to the commands of multiple targets. -#' Like [tar_hook_before()] except that the `hook` and `names` -#' arguments are already pre-quoted language objects. -#' @return A flattened list of target objects with the hooks applied. -#' Even if the input target list had a nested structure, -#' the return value is a simple list where each element is a target object. -#' All hook functions remove the nested structure of the input target list. -#' @inheritSection tar_map Target objects -#' @param targets A list of target objects. The input target list -#' can be arbitrarily nested, but it must consist entirely of target -#' objects. In addition, the return value is a simple list -#' where each element is a target object. -#' All hook functions remove the nested structure of the input target list. -#' @param hook A pre-quoted language object with R code to insert. -#' @param names Name of targets in the target list -#' to apply the hook. Supplied as a language object with a -#' `tidyselect` expression: for example, `names = quote(starts_with("x_"))`. -#' Targets not included in `names` still remain in the target list, -#' but they are not modified because the hook does not apply to them. -#' @param set_deps Logical of length 1, whether to refresh the dependencies -#' of each modified target by scanning the newly generated -#' target commands for dependencies. If `FALSE`, then the target will -#' keep the original set of dependencies it had before the hook. -#' Set to `NULL` to include all targets supplied to the `targets` argument. -#' `TRUE` is recommended for nearly all situations. Only use `FALSE` -#' if you have a specialized use case and you know what you are doing. -#' @param envir Optional environment to construct the quosure for the `names` -#' argument to select names. -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' targets::tar_script({ -#' targets <- list( -#' # Nested target lists work with hooks. -#' list( -#' targets::tar_target(x1, task1()), -#' targets::tar_target(x2, task2(x1)) -#' ), -#' targets::tar_target(x3, task3(x2)), -#' targets::tar_target(y1, task4(x3)) -#' ) -#' tarchetypes::tar_hook_before_raw( -#' targets = targets, -#' hook = quote(print("Running hook.")), -#' names = quote(starts_with("x")) -#' ) -#' }) -#' targets::tar_manifest(fields = command) -#' }) -#' } tar_hook_before_raw <- function( targets, hook, diff --git a/R/tar_hook_inner.R b/R/tar_hook_inner.R index c01e935..d5c73d3 100644 --- a/R/tar_hook_inner.R +++ b/R/tar_hook_inner.R @@ -3,6 +3,10 @@ #' @family hooks #' @description In the command of each target, wrap each mention of #' each dependency target in an arbitrary R expression. +#' +#' `tar_hook_inner()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_inner_raw()` expects +#' evaluated expression objects. #' @details The expression you supply to `hook` #' must contain the special placeholder symbol `.x` #' so `tar_hook_inner()` knows where to insert the original command @@ -17,8 +21,10 @@ #' The hook must contain the special placeholder symbol `.x` #' so `tar_hook_inner()` knows where to insert the code to wrap #' mentions of dependencies. -#' The hook code is quoted (not evaluated) so there is no need -#' to wrap it in `quote()`, `expression()`, or similar. +#' +#' `tar_hook_inner()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_inner_raw()` expects +#' evaluated expression objects. #' @param names_wrap Names of targets to wrap with the hook #' where they appear as dependencies in the commands of other targets. #' Use `tidyselect` helpers like [starts_with()], as in @@ -43,6 +49,23 @@ #' ) #' }) #' targets::tar_manifest(fields = command) +#' # With tar_hook_inner_raw(): +#' targets::tar_script({ +#' targets <- list( +#' # Nested target lists work with hooks. +#' list( +#' targets::tar_target(x1, task1()), +#' targets::tar_target(x2, task2(x1)) +#' ), +#' targets::tar_target(x3, task3(x2, x1)), +#' targets::tar_target(y1, task4(x3)) +#' ) +#' tarchetypes::tar_hook_inner_raw( +#' targets = targets, +#' hook = quote(fun(.x)), +#' names = quote(starts_with("x")) +#' ) +#' }) #' }) #' } tar_hook_inner <- function( diff --git a/R/tar_hook_inner_raw.R b/R/tar_hook_inner_raw.R index 6185558..4ee5463 100644 --- a/R/tar_hook_inner_raw.R +++ b/R/tar_hook_inner_raw.R @@ -1,53 +1,5 @@ -#' @title Hook to wrap dependencies (raw version) +#' @rdname tar_hook_inner #' @export -#' @family hooks -#' @description In the command of each target, wrap each mention of -#' each dependency target in an arbitrary R expression. -#' [tar_hook_inner_raw()] is like [tar_hook_inner()] except -#' that the `hook`, `names`, and `names_wrap` arguments are -#' pre-quoted language objects. -#' @details The expression you supply to `hook` -#' must contain the special placeholder symbol `.x` -#' so `tar_hook_inner()` knows where to insert the original command -#' of the target. -#' @return A flattened list of target objects with the hooks applied. -#' Even if the input target list had a nested structure, -#' the return value is a simple list where each element is a target object. -#' All hook functions remove the nested structure of the input target list. -#' @inheritSection tar_map Target objects -#' @inheritParams tar_hook_before_raw -#' @param hook Pre-quoted language object with -#' R code to wrap each target's command. -#' The hook must contain the special placeholder symbol `.x` -#' so `tar_hook_inner()` knows where to insert the code to wrap -#' mentions of dependencies. -#' @param names_wrap Pre-quoted language object with -#' names of targets to wrap with the hook -#' where they appear as dependencies in the commands of other targets. -#' Use `tidyselect` expressions, e.g. -#' `names_wrap = quote(starts_with("your_prefix_"))`. -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' targets::tar_script({ -#' targets <- list( -#' # Nested target lists work with hooks. -#' list( -#' targets::tar_target(x1, task1()), -#' targets::tar_target(x2, task2(x1)) -#' ), -#' targets::tar_target(x3, task3(x2, x1)), -#' targets::tar_target(y1, task4(x3)) -#' ) -#' tarchetypes::tar_hook_inner_raw( -#' targets = targets, -#' hook = quote(fun(.x)), -#' names = quote(starts_with("x")) -#' ) -#' }) -#' targets::tar_manifest(fields = command) -#' }) -#' } tar_hook_inner_raw <- function( targets, hook, diff --git a/R/tar_hook_outer.R b/R/tar_hook_outer.R index a715736..08da468 100644 --- a/R/tar_hook_outer.R +++ b/R/tar_hook_outer.R @@ -2,6 +2,9 @@ #' @export #' @family hooks #' @description Wrap the command of each target in an arbitrary R expression. +#' `tar_hook_outer()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_outer_raw()` expects +#' evaluated expression objects. #' @details The expression you supply to `hook` #' must contain the special placeholder symbol `.x` #' so `tar_hook_outer()` knows where to insert the original command @@ -16,8 +19,10 @@ #' The hook must contain the special placeholder symbol `.x` #' so `tar_hook_outer()` knows where to insert the original command #' of the target. -#' The hook code is quoted (not evaluated) so there is no need -#' to wrap it in `quote()`, `expression()`, or similar. +#' +#' `tar_hook_outer()` expects unevaluated expressions for the `hook` and +#' `names` arguments, whereas `tar_hook_outer_raw()` expects +#' evaluated expression objects. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -38,6 +43,23 @@ #' ) #' }) #' targets::tar_manifest(fields = command) +#' # Using tar_hook_outer_raw(): +#' targets::tar_script({ +#' targets <- list( +#' # Nested target lists work with hooks. +#' list( +#' targets::tar_target(x1, task1()), +#' targets::tar_target(x2, task2(x1)) +#' ), +#' targets::tar_target(x3, task3(x2)), +#' targets::tar_target(y1, task4(x3)) +#' ) +#' tarchetypes::tar_hook_outer_raw( +#' targets = targets, +#' hook = quote(postprocess(.x, arg = "value")), +#' names = quote(starts_with("x")) +#' ) +#' }) #' }) #' } tar_hook_outer <- function( diff --git a/R/tar_map2.R b/R/tar_map2.R index 357cebc..c2093c9 100644 --- a/R/tar_map2.R +++ b/R/tar_map2.R @@ -5,13 +5,12 @@ #' @description Define targets for batched #' dynamic-within-static branching for data frames. #' Not a user-side function. Do not invoke directly. -#' @details Static branching creates one pair of targets -#' for each row in `values`. In each pair, -#' there is an upstream non-dynamic target that runs `command1` -#' and a downstream dynamic target that runs `command2`. -#' `command1` produces a data frame of arguments to -#' `command2`, and `command2` dynamically maps over -#' these arguments in batches. +#' +#' [tar_map2()] expects unevaluated language for arguments +#' `name`, `command1`, `command2`, `columns1`, and `columns2`. +#' [tar_map2_raw()] expects a character string for `name` +#' and an evaluated expression object for each of +#' `command1`, `command2`, `columns1`, and `columns2`. #' @details Static branching creates one pair of targets #' for each row in `values`. In each pair, #' there is an upstream non-dynamic target that runs `command1` @@ -23,20 +22,53 @@ #' @return A list of new target objects. #' See the "Target objects" section for background. #' @inheritSection tar_map Target objects -#' @inheritParams tar_map2_raw +#' @inheritParams tar_map_rep +#' @inheritParams tar_rep2 +#' @inheritParams tar_map #' @inheritParams tar_rep -#' @param name Symbol, base name of the targets. +#' @param name Base name of the targets. +#' In regular `tarchetypes` functions, +#' the `name` argument is an unevaluated symbol. +#' In the `"_raw"` versions +#' of functions, `name` is a character string. #' @param command1 R code to create named arguments to `command2`. -#' Must return a data frame with one row per call to `command2`. +#' Must return a data frame with one row per call to `command2` when run. +#' +#' In regular `tarchetypes` functions, +#' the `command1` argument is an unevaluated expression. +#' In the `"_raw"` versions +#' of functions, `command1` is an evaluated expression object. #' @param command2 R code to map over the data frame of arguments #' produced by `command1`. Must return a data frame. +#' +#' In regular `tarchetypes` functions, +#' the `command2` argument is an unevaluated expression. +#' In the `"_raw"` versions +#' of functions, `command2` is an evaluated expression object. #' @param columns1 A tidyselect expression to select which columns of `values` #' to append to the output of all targets. #' Columns already in the target output are not appended. -#' @param columns2 A tidyselect expression to select which columns of `command1` +#' +#' In regular `tarchetypes` functions, +#' the `columns1` argument is an unevaluated expression. +#' In the `"_raw"` versions +#' of functions, `columns1` is an evaluated expression object. +#' @param columns2 A tidyselect expression to select which columns of +#' `command1` #' output to append to `command2` output. #' Columns already in the target output are not appended. #' `columns1` takes precedence over `columns2`. +#' +#' In regular `tarchetypes` functions, +#' the `columns2` argument is an unevaluated expression. +#' In the `"_raw"` versions +#' of functions, `columns2` is an evaluated expression object. +#' @param suffix1 Character of length 1, +#' suffix to apply to the `command1` targets to distinguish +#' them from the `command2` targets. +#' @param suffix2 Character of length 1, +#' suffix to apply to the `command2` targets to distinguish +#' them from the `command1` targets. tar_map2 <- function( name, command1, diff --git a/R/tar_map2_count.R b/R/tar_map2_count.R index 2acdaa0..ab123f1 100644 --- a/R/tar_map2_count.R +++ b/R/tar_map2_count.R @@ -5,6 +5,12 @@ #' @description Define targets for batched #' dynamic-within-static branching for data frames, #' where the user sets the (maximum) number of batches. +#' +#' [tar_map2_count()] expects unevaluated language for arguments +#' `name`, `command1`, `command2`, `columns1`, and `columns2`. +#' [tar_map2_count_raw()] expects a character string for `name` +#' and an evaluated expression object for each of +#' `command1`, `command2`, `columns1`, and `columns2`. #' @details Static branching creates one pair of targets #' for each row in `values`. In each pair, #' there is an upstream non-dynamic target that runs `command1` @@ -18,7 +24,10 @@ #' @inheritSection tar_rep Replicate-specific seeds #' @inheritParams tar_rep #' @inheritParams tar_map2 -#' @inheritParams tar_map2_count_raw +#' @param batches Positive integer of length 1, +#' maximum number of batches (dynamic branches within static branches) +#' of the downstream (`command2`) targets. Batches +#' are formed from row groups of the `command1` target output. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -40,6 +49,27 @@ #' }) #' targets::tar_make() #' targets::tar_read(x) +#' # With tar_map2_count_raw(): +#' targets::tar_script({ +#' tarchetypes::tar_map2_count_raw( +#' name = "x", +#' command1 = quote( +#' tibble::tibble( +#' arg1 = arg1, +#' arg2 = seq_len(6) +#' ) +#' ), +#' command2 = quote( +#' tibble::tibble( +#' result = paste(arg1, arg2), +#' random = sample.int(1e9, size = 1), +#' length_input = length(arg1) +#' ) +#' ), +#' values = tibble::tibble(arg1 = letters[seq_len(2)]), +#' batches = 3 +#' ) +#' }) #' }) #' } tar_map2_count <- function( diff --git a/R/tar_map2_count_raw.R b/R/tar_map2_count_raw.R index ce947a5..10eccc2 100644 --- a/R/tar_map2_count_raw.R +++ b/R/tar_map2_count_raw.R @@ -1,57 +1,5 @@ -#' @title Dynamic-within-static branching for data frames -#' (count batching; raw version). +#' @rdname tar_map2_count #' @export -#' @family branching -#' @description Define targets for batched -#' dynamic-within-static branching for data frames, -#' where the user sets the (maximum) number of batches. -#' Like `tar_map2_count()` except `name` is a character string -#' and `command1`, `command2`, `names`, `columns1`, and `columns2` -#' are all language objects. -#' @details Static branching creates one pair of targets -#' for each row in `values`. In each pair, -#' there is an upstream non-dynamic target that runs `command1` -#' and a downstream dynamic target that runs `command2`. -#' `command1` produces a data frame of arguments to -#' `command2`, and `command2` dynamically maps over -#' these arguments in batches. -#' @return A list of new target objects. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritParams tar_rep -#' @param batches Positive integer of length 1, -#' maximum number of batches (dynamic branches within static branches) -#' of the downstream (`command2`) targets. Batches -#' are formed from row groups of the `command1` target output. -#' @inheritParams tar_map2_raw -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' targets::tar_script({ -#' tarchetypes::tar_map2_count_raw( -#' "x", -#' command1 = quote( -#' tibble::tibble( -#' arg1 = arg1, -#' arg2 = seq_len(6) -#' ) -#' ), -#' command2 = quote( -#' tibble::tibble( -#' result = paste(arg1, arg2), -#' random = sample.int(1e6, size = 1), -#' length_input = length(arg1) -#' ) -#' ), -#' values = tibble::tibble(arg1 = letters[seq_len(2)]), -#' batches = 3 -#' ) -#' }) -#' targets::tar_make() -#' targets::tar_read(x) -#' }) -#' } tar_map2_count_raw <- function( name, command1, diff --git a/R/tar_map2_raw.R b/R/tar_map2_raw.R index 516075d..c37f5f2 100644 --- a/R/tar_map2_raw.R +++ b/R/tar_map2_raw.R @@ -1,42 +1,6 @@ -#' @title Batched dynamic-within-static branching for data frames (raw version). +#' @rdname tar_map2 +#' @export #' @keywords internal -#' @family branching -#' @description Define targets for batched -#' dynamic-within-static branching for data frames (raw version). -#' Not a user-side function. Do not invoke directly. -#' @details Like `tar_map2()` except `name` is a character string -#' and `command1`, `command2`, `group`, `names`, `columns1`, and `columns2` -#' are language objects. -#' @return A list of new target objects. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritParams tar_map -#' @inheritParams tar_rep -#' @param name Character of length 1, base name of the targets. -#' @param command1 Language object to create named arguments to `command2`. -#' Must return a data frame with one row per call to `command2`. -#' @param command2 Language object to map over the data frame of arguments -#' produced by `command1`. Must return a data frame. -#' @param columns1 Language object, a tidyselect expression -#' to select which columns of `values` -#' to append to the output of all targets. -#' @param group Function on the data produced by `command1` to create the -#' `tar_group` column that determines the batching structure for the -#' `command2` targets. -#' @param columns2 Language object, a tidyselect expression -#' to select which columns of `command1` -#' output to append to `command2` output. -#' In case of conflicts, `column1` takes precedence. -#' @param suffix1 Character of length 1, -#' suffix to apply to the `command1` targets to distinguish -#' them from the `command2` targets. -#' @param suffix2 Character of length 1, -#' suffix to apply to the `command2` targets to distinguish -#' them from the `command1` targets. -#' @inheritParams tar_map_rep_raw -#' @inheritParams tar_rep2 -#' @inheritParams tar_map tar_map2_raw <- function( name, command1, diff --git a/R/tar_map2_size.R b/R/tar_map2_size.R index 47dfe27..0416b2a 100644 --- a/R/tar_map2_size.R +++ b/R/tar_map2_size.R @@ -5,6 +5,12 @@ #' @description Define targets for batched #' dynamic-within-static branching for data frames, #' where the user sets the (maximum) size of each batch. +#' +#' [tar_map2_size()] expects unevaluated language for arguments +#' `name`, `command1`, `command2`, `columns1`, and `columns2`. +#' [tar_map2_size_raw()] expects a character string for `name` +#' and an evaluated expression object for each of +#' `command1`, `command2`, `columns1`, and `columns2`. #' @details Static branching creates one pair of targets #' for each row in `values`. In each pair, #' there is an upstream non-dynamic target that runs `command1` @@ -18,7 +24,10 @@ #' @inheritSection tar_rep Replicate-specific seeds #' @inheritParams tar_rep #' @inheritParams tar_map2 -#' @inheritParams tar_map2_size_raw +#' @param size Positive integer of length 1, +#' maximum number of rows in each batch for +#' the downstream (`command2`) targets. Batches +#' are formed from row groups of the `command1` target output. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -40,6 +49,27 @@ #' }) #' targets::tar_make() #' targets::tar_read(x) +#' # With tar_map2_size_raw(): +#' targets::tar_script({ +#' tarchetypes::tar_map2_size_raw( +#' name = "x", +#' command1 = quote( +#' tibble::tibble( +#' arg1 = arg1, +#' arg2 = seq_len(6) +#' ) +#' ), +#' command2 = quote( +#' tibble::tibble( +#' result = paste(arg1, arg2), +#' random = sample.int(1e9, size = 1), +#' length_input = length(arg1) +#' ) +#' ), +#' values = tibble::tibble(arg1 = letters[seq_len(2)]), +#' size = 2 +#' ) +#' }) #' }) #' } tar_map2_size <- function( diff --git a/R/tar_map2_size_raw.R b/R/tar_map2_size_raw.R index b8aec9c..6665cdb 100644 --- a/R/tar_map2_size_raw.R +++ b/R/tar_map2_size_raw.R @@ -1,58 +1,5 @@ -#' @title Dynamic-within-static branching for data frames -#' (size batching; raw version). +#' @rdname tar_map2_size #' @export -#' @family branching -#' @description Define targets for batched -#' dynamic-within-static branching for data frames, -#' where the user sets the (maximum) size of each batch. -#' Like `tar_map2_size()` except `name` is a character string -#' and `command1`, `command2`, `names`, `columns1`, and `columns2` -#' are all language objects. -#' @details Static branching creates one pair of targets -#' for each row in `values`. In each pair, -#' there is an upstream non-dynamic target that runs `command1` -#' and a downstream dynamic target that runs `command2`. -#' `command1` produces a data frame of arguments to -#' `command2`, and `command2` dynamically maps over -#' these arguments in batches. -#' @return A list of new target objects. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritParams tar_map -#' @inheritParams tar_rep -#' @param size Positive integer of length 1, -#' maximum number of rows in each batch for -#' the downstream (`command2`) targets. Batches -#' are formed from row groups of the `command1` target output. -#' @inheritParams tar_map2_raw -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' targets::tar_script({ -#' tarchetypes::tar_map2_size_raw( -#' "x", -#' command1 = quote( -#' tibble::tibble( -#' arg1 = arg1, -#' arg2 = seq_len(6) -#' ) -#' ), -#' command2 = quote( -#' tibble::tibble( -#' result = paste(arg1, arg2), -#' random = sample.int(1e6, size = 1), -#' length_input = length(arg1) -#' ) -#' ), -#' values = tibble::tibble(arg1 = letters[seq_len(2)]), -#' size = 2 -#' ) -#' }) -#' targets::tar_make() -#' targets::tar_read(x) -#' }) -#' } tar_map2_size_raw <- function( name, command1, diff --git a/R/tar_map_rep.R b/R/tar_map_rep.R index df9c4ec..fc54959 100644 --- a/R/tar_map_rep.R +++ b/R/tar_map_rep.R @@ -3,15 +3,26 @@ #' @export #' @family branching #' @description Define targets for batched replication -#' within static branches for data frames. +#' within static branches for data frames. +#' +#' [tar_map_rep()] expects an unevaluated symbol for the `name` argument +#' and an unevaluated expression for `command`, +#' whereas [tar_map_rep_raw()] expects a character string for `name` +#' and an evaluated expression object for `command`. #' @return A list of new target objects. #' See the "Target objects" section for background. #' @inheritSection tar_map Target objects #' @inheritSection tar_rep Replicate-specific seeds +#' @inheritParams tar_map #' @inheritParams tar_rep -#' @inheritParams tar_map_rep_raw +#' @param name Name of the target. +#' [tar_map_rep()] expects an unevaluated symbol for the `name` argument, +#' whereas [tar_map_rep_raw()] expects a character string for `name`. #' @param command R code for a single replicate. Must return -#' a data frame. +#' a data frame when run. +#' [tar_map_rep()] expects an unevaluated expression for `command`, +#' whereas [tar_map_rep_raw()] expects +#' an evaluated expression object for `command`. #' @param columns A tidyselect expression to select which columns of `values` #' to append to the output. Columns already in the target output #' are not appended. @@ -21,6 +32,7 @@ #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. #' targets::tar_script({ +#' library(tarchetypes) #' # Just a sketch of a Bayesian sensitivity analysis of hyperparameters: #' assess_hyperparameters <- function(sigma1, sigma2) { #' # data <- simulate_random_data() # user-defined function @@ -38,14 +50,24 @@ #' sigma1 = c(10, 50, 50), #' sigma2 = c(10, 5, 10) #' ) -#' tarchetypes::tar_map_rep( -#' sensitivity_analysis, -#' command = assess_hyperparameters(sigma1, sigma2), -#' values = hyperparameters, -#' names = tidyselect::any_of("scenario"), -#' batches = 2, -#' reps = 3 -#' ) +#' list( +#' tar_map_rep( +#' name = sensitivity_analysis, +#' command = assess_hyperparameters(sigma1, sigma2), +#' values = hyperparameters, +#' names = tidyselect::any_of("scenario"), +#' batches = 2, +#' reps = 3 +#' ), +#' tar_map_rep_raw( +#' name = "sensitivity_analysis2", +#' command = quote(assess_hyperparameters(sigma1, sigma2)), +#' values = hyperparameters, +#' names = tidyselect::any_of("scenario"), +#' batches = 2, +#' reps = 3 +#' ) +#' ) #' }) #' targets::tar_make() #' targets::tar_read(sensitivity_analysis) diff --git a/R/tar_map_rep_raw.R b/R/tar_map_rep_raw.R index c2e1bf4..591f7ef 100644 --- a/R/tar_map_rep_raw.R +++ b/R/tar_map_rep_raw.R @@ -1,71 +1,5 @@ -#' @title Dynamic batched replication within static branches -#' for data frames (raw version). +#' @rdname tar_map_rep #' @export -#' @family branching -#' @description Define targets for batched replication -#' within static branches for data frames (raw version). -#' @description This function is like [tar_map_rep()] -#' except the `name` argument is a character string -#' and the `names` and `columns` arguments are -#' language objects. -#' @return A list of new target objects. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritParams tar_rep -#' @param command Language object, R code for a single replicate. Must return -#' a data frame. -#' @param names Language object with a tidyselect expression -#' to select which columns of `values` to use to construct -#' statically branched target names. If `NULL`, then -#' short names are automatically generated. -#' @param columns Language object with a tidyselect expression -#' to select which columns of `values` to append to the output. -#' Columns already in the target output are not appended. -#' @param combine Logical of length 1, whether to statically combine -#' all the results into a single target downstream. -#' @param format Character of length 1, storage format of the output. -#' An efficient data frame format like `"feather"` is recommended, -#' but the default is `"rds"` to avoid incurring extra package -#' dependencies. See the help file of `targets::tar_target()` -#' for details on storage formats. -#' @inheritParams targets::tar_target -#' @inheritParams tar_map -#' @inheritParams 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({ -#' # Just a sketch of a Bayesian sensitivity analysis of hyperparameters: -#' assess_hyperparameters <- function(sigma1, sigma2) { -#' # data <- simulate_random_data() # user-defined function -#' # run_model(data, sigma1, sigma2) # user-defined function -#' # Mock output from the model: -#' posterior_samples <- stats::rnorm(1000, 0, sigma1 + sigma2) -#' tibble::tibble( -#' posterior_median = median(posterior_samples), -#' posterior_quantile_0.025 = quantile(posterior_samples, 0.025), -#' posterior_quantile_0.975 = quantile(posterior_samples, 0.975) -#' ) -#' } -#' hyperparameters <- tibble::tibble( -#' scenario = c("tight", "medium", "diffuse"), -#' sigma1 = c(10, 50, 50), -#' sigma2 = c(10, 5, 10) -#' ) -#' tarchetypes::tar_map_rep_raw( -#' "sensitivity_analysis", -#' command = quote(assess_hyperparameters(sigma1, sigma2)), -#' values = hyperparameters, -#' names = quote(tidyselect::any_of("scenario")), -#' batches = 2, -#' reps = 3 -#' ) -#' }) -#' targets::tar_make() -#' targets::tar_read(sensitivity_analysis) -#' }) -#' } tar_map_rep_raw <- function( name, command, diff --git a/R/tar_quarto.R b/R/tar_quarto.R index 229d995..eca22ae 100644 --- a/R/tar_quarto.R +++ b/R/tar_quarto.R @@ -3,6 +3,12 @@ #' @family Literate programming targets #' @description Shorthand to include a Quarto project in a #' `targets` pipeline. +#' +#' [tar_quarto()] expects an unevaluated symbol for the `name` +#' argument and an unevaluated expression for the `exectue_params` argument. +#' [tar_quarto_raw()] expects a character string for the `name` +#' argument and an evaluated expression object +#' for the `exectue_params` argument. #' @details `tar_quarto()` is an alternative to `tar_target()` for #' Quarto projects and standalone Quarto source documents #' that depend on upstream targets. The Quarto @@ -49,14 +55,27 @@ #' See the "Target objects" section for background. #' @inheritSection tar_map Target objects #' @inheritParams targets::tar_target -#' @inheritParams tar_quarto_raw -#' @param execute_params Code, cannot be `NULL`. -#' `execute_params` evaluates to a named list of parameters +#' @inheritParams quarto::quarto_render +#' @inheritParams tar_render +#' @param name Name of the target. +#' [tar_quarto()] expects an unevaluated symbol for the `name` +#' argument, and +#' [tar_quarto_raw()] expects a character string for `name`. +#' @param path Character string, path to the Quarto source file. +#' @param extra_files Character vector of extra files and +#' directories to track for changes. The target will be invalidated +#' (rerun on the next `tar_make()`) if the contents of these files changes. +#' No need to include anything already in the output of [tar_quarto_files()], +#' the list of file dependencies automatically detected through +#' `quarto::quarto_inspect()`. +#' @param execute_params Named collection of parameters #' for parameterized Quarto documents. These parameters override the custom #' custom elements of the `params` list in the YAML front-matter of the -#' Quarto source files. The list is quoted -#' (not evaluated until the target runs) -#' so that upstream targets can serve as parameter values. +#' Quarto source files. +#' +#' [tar_quarto()] expects an unevaluated expression for the +#' `exectue_params` argument, whereas +#' [tar_quarto_raw()] expects an evaluated expression object. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -78,7 +97,7 @@ #' library(tarchetypes) #' list( #' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_quarto(report, path = "report.qmd") +#' tar_quarto(name = report, path = "report.qmd") #' ) #' }, ask = FALSE) #' # Then, run the pipeline as usual. @@ -105,9 +124,14 @@ #' list( #' tar_target(data, data.frame(x = seq_len(26), y = letters)), #' tar_quarto( -#' report, +#' name = report, #' path = "report.qmd", #' execute_params = list(your_param = data) +#' ), +#' tar_quarto_raw( +#' name = "report2", +#' path = "report.qmd", +#' execute_params = quote(list(your_param = data)) #' ) #' ) #' }, ask = FALSE) diff --git a/R/tar_quarto_raw.R b/R/tar_quarto_raw.R index 0ee4b05..8074445 100644 --- a/R/tar_quarto_raw.R +++ b/R/tar_quarto_raw.R @@ -1,111 +1,5 @@ -#' @title Target with a Quarto project (raw version). +#' @rdname tar_quarto #' @export -#' @family Literate programming targets -#' @description Shorthand to include a Quarto project or standalone -#' Quarto source document in a `targets` pipeline. -#' @details `tar_quarto_raw()` is just like [tar_quarto()] -#' except that it uses standard evaluation for the -#' `name` and `execute_params` arguments (instead of quoting them). -#' @return A target object with `format = "file"`. -#' When this target runs, it returns a sorted character vector -#' of all the important file paths: the rendered documents, -#' the Quarto source files, and other input and output files. -#' The output files are determined by the YAML front-matter of -#' standalone Quarto documents and `_quarto.yml` in Quarto projects, -#' and you can see these files with [tar_quarto_files()] -#' (powered by `quarto::quarto_inspect()`). -#' All returned paths are *relative* paths to ensure portability -#' (so that the project can be moved from one file system to another -#' without invalidating the target). -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_render Literate programming limitations -#' @inheritSection tar_quarto Quarto troubleshooting -#' @inheritParams targets::tar_target_raw -#' @inheritParams quarto::quarto_render -#' @inheritParams tar_render -#' @param path Character of length 1, -#' either the single `*.qmd` source file to be rendered -#' or a directory containing a Quarto project. -#' Defaults to the working directory of the `targets` pipeline. -#' Passed directly to the `input` argument of `quarto::quarto_render()`. -#' @param extra_files Character vector of extra files and -#' directories to track for changes. The target will be invalidated -#' (rerun on the next `tar_make()`) if the contents of these files changes. -#' No need to include anything already in the output of [tar_quarto_files()], -#' the list of file dependencies automatically detected through -#' `quarto::quarto_inspect()`. -#' @param execute_params A non-expression language object -#' (use `quote()`, not `expression()`) that -#' evaluates to a named list of parameters -#' for parameterized Quarto documents. These parameters override the custom -#' custom elements of the `params` list in the YAML front-matter of the -#' Quarto source files. The list is quoted -#' (not evaluated until the target runs) -#' so that upstream targets can serve as parameter values. -#' @param profile Character of length 1, Quarto profile. If `NULL`, -#' the default profile will be used. Requires Quarto version 1.2 or higher. -#' See for details. -#' @param packages Deprecated on 2023-09-05 (version 0.7.8.9000). Please -#' load R packages inside the Quarto report itself. -#' @param library Deprecated on 2023-09-05 (version 0.7.8.9000). Please -#' load R packages inside the Quarto report itself. -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' # Unparameterized Quarto document: -#' lines <- c( -#' "---", -#' "title: report.qmd source file", -#' "output_format: html", -#' "---", -#' "Assume these lines are in report.qmd.", -#' "```{r}", -#' "targets::tar_read(data)", -#' "```" -#' ) -#' # In tar_dir(), not part of the user's file space: -#' writeLines(lines, "report.qmd") -#' # Include the report in a pipeline as follows. -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_quarto_raw("report", path = "report.qmd") -#' ) -#' }, ask = FALSE) -#' # Then, run the pipeline as usual. -#' -#' # Parameterized Quarto: -#' lines <- c( -#' "---", -#' "title: 'report.qmd source file with parameters'", -#' "output_format: html_document", -#' "params:", -#' " your_param: \"default value\"", -#' "---", -#' "Assume these lines are in report.qmd.", -#' "```{r}", -#' "print(params$your_param)", -#' "```" -#' ) -#' # In tar_dir(), not part of the user's file space: -#' writeLines(lines, "report.qmd") -#' # Include the report in the pipeline as follows. -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_quarto_raw( -#' "report", -#' path = "report.qmd", -#' execute_params = quote(list(your_param = data)) -#' ) -#' ) -#' }, ask = FALSE) -#' # Then, run the pipeline as usual. -#' }) -#' } tar_quarto_raw <- function( name, path = ".", diff --git a/R/tar_quarto_rep.R b/R/tar_quarto_rep.R index 3335d8f..98cf44c 100644 --- a/R/tar_quarto_rep.R +++ b/R/tar_quarto_rep.R @@ -3,6 +3,12 @@ #' @family Literate programming targets #' @description Targets to render a parameterized Quarto document #' with multiple sets of parameters. +#' +#' [tar_quarto_rep()] expects an unevaluated symbol for the `name` +#' argument and an unevaluated expression for the `exectue_params` argument. +#' [tar_quarto_rep_raw()] expects a character string for the `name` +#' argument and an evaluated expression object +#' for the `exectue_params` argument. #' @details `tar_quarto_rep()` is an alternative to `tar_target()` for #' a parameterized Quarto document that depends on other targets. #' Parameters must be given as a data frame with one row per @@ -40,17 +46,27 @@ #' @inheritSection tar_rep Replicate-specific seeds #' @inheritSection tar_render Literate programming limitations #' @inheritSection tar_quarto Quarto troubleshooting +#' @inheritParams tar_quarto #' @inheritParams tar_rep #' @inheritParams targets::tar_target #' @inheritParams quarto::quarto_render -#' @inheritParams tar_quarto_rep_raw #' @param tidy_eval Logical of length 1, whether to use tidy evaluation #' to resolve `execute_params`. Similar to the `tidy_eval` #' argument of `targets::tar_target()`. +#' @param name Name of the target. +#' [tar_quarto_rep()] expects an unevaluated symbol for the `name` +#' argument, and +#' [tar_quarto_rep_raw()] expects a character string for `name`. #' @param execute_params Code to generate #' a data frame or `tibble` with one row per rendered report -#' and one column per Quarto parameter. You may also include an -#' `output_file` column to specify the path of each rendered report. +#' and one column per Quarto parameter. +#' [tar_quarto_rep()] expects an unevaluated expression for the +#' `exectue_params` argument, whereas +#' [tar_quarto_rep_raw()] expects an evaluated expression object. +#' +#' You may also include an +#' `output_file` column in the parameters +#' to specify the path of each rendered report. #' If included, the `output_file` column must be a character vector #' with one and only one output file for each row of parameters. #' If an `output_file` column is not included, @@ -83,9 +99,14 @@ #' library(tarchetypes) #' list( #' tar_quarto_rep( -#' report, +#' name = report, #' path = "report.qmd", #' execute_params = tibble::tibble(par = c(1, 2)) +#' ), +#' tar_quarto_rep_raw( +#' name = "report", +#' path = "report.qmd", +#' execute_params = quote(tibble::tibble(par = c(1, 2))) #' ) #' ) #' }, ask = FALSE) diff --git a/R/tar_quarto_rep_raw.R b/R/tar_quarto_rep_raw.R index ab75dd8..6dbc510 100644 --- a/R/tar_quarto_rep_raw.R +++ b/R/tar_quarto_rep_raw.R @@ -1,112 +1,5 @@ -#' @title Parameterized Quarto with dynamic branching (raw version). +#' @rdname tar_quarto_rep #' @export -#' @family Literate programming targets -#' @description Targets to render a parameterized Quarto document -#' with multiple sets of parameters (raw version). Same as -#' `tar_quarto_rep()` except `name` is a character string, -#' `params` is an expression object, -#' and extra arguments to `quarto::quarto_render()` are passed through -#' the `args` argument instead of `...`. -#' @details `tar_quarto_rep_raw()` is an alternative to `tar_target_raw()` for -#' parameterized Quarto reports that depend on other targets. -#' Parameters must be given as a data frame with one row per -#' rendered report and one column per parameter. An optional -#' `output_file` column may be included to set the output file path -#' of each rendered report. (See the `execute_params` argument for details.) -#' -#' The Quarto source should mention other dependency targets -#' `tar_load()` and `tar_read()` in the active code chunks -#' (which also allows you to render the report -#' outside the pipeline if the `_targets/` data store already exists -#' and appropriate defaults are specified for the parameters). -#' (Do not use `tar_load_raw()` or `tar_read_raw()` for this.) -#' Then, `tar_quarto()` defines a special kind of target. It -#' 1. Finds all the `tar_load()`/`tar_read()` dependencies in the report -#' and inserts them into the target's command. -#' This enforces the proper dependency relationships. -#' (Do not use `tar_load_raw()` or `tar_read_raw()` for this.) -#' 2. Sets `format = "file"` (see `tar_target()`) so `targets` -#' watches the files at the returned paths and reruns the report -#' if those files change. -#' 3. Configures the target's command to return the output -#' report files: the rendered document, the source file, -#' and then the `*_files/` directory if it exists. -#' All these file paths -#' are relative paths so the project stays portable. -#' 4. Forces the report to run in the user's current working directory -#' instead of the working directory of the report. -#' 5. Sets convenient default options such as `deployment = "main"` -#' in the target and `quiet = TRUE` in `quarto::quarto_render()`. -#' @return A list of target objects to render the Quarto -#' reports. Changes to the parameters, source file, dependencies, etc. -#' will cause the appropriate targets to rerun during `tar_make()`. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritSection tar_render Literate programming limitations -#' @inheritSection tar_quarto Quarto troubleshooting -#' @inheritParams tar_rep -#' @inheritParams quarto::quarto_render -#' @inheritParams targets::tar_target -#' @inheritParams tar_quarto_rep_run -#' @inheritParams tar_render -#' @param path Character string, file path to the Quarto source file. -#' Must have length 1. -#' @param execute_params Expression object with code to generate -#' a data frame or `tibble` with one row per rendered report -#' and one column per Quarto parameter. You may also include an -#' `output_file` column to specify the path of each rendered report. -#' If included, the `output_file` column must be a character vector -#' with one and only one output file for each row of parameters. -#' If an `output_file` column is not included, -#' then the output files are automatically determined using the parameters, -#' and the default file format is determined by the YAML front-matter -#' of the Quarto source document. Only the first file format is used, -#' the others are not generated. -#' Quarto parameters must not be named `tar_group` or `output_file`. -#' This `execute_params` argument is converted into the command for a target -#' that supplies the Quarto parameters. -#' @param batches Number of batches to group the Quarto files. -#' For a large number of reports, increase the number of batches -#' to decrease target-level overhead. Defaults to the number of -#' reports to render (1 report per batch). -#' @param format Character of length 1, `format` argument to `tar_target()` -#' to store the data frame of Quarto parameters. -#' @param iteration Character of length 1, `iteration` argument -#' to `tar_target()` for the Quarto documents. Does not apply -#' to the target with Quarto parameters (whose iteration -#' is always `"group"`). -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' # Parameterized Quarto: -#' lines <- c( -#' "---", -#' "title: 'report.qmd source file'", -#' "output_format: html_document", -#' "params:", -#' " par: \"default value\"", -#' "---", -#' "Assume these lines are in a file called report.qmd.", -#' "```{r}", -#' "print(params$par)", -#' "```" -#' ) -#' writeLines(lines, "report.qmd") # In tar_dir(), not the user's file space. -#' # The following pipeline will run the report for each row of params. -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_quarto_rep_raw( -#' "report", -#' path = "report.qmd", -#' execute_params = quote(tibble::tibble(par = c(1, 2))) -#' ) -#' ) -#' }, ask = FALSE) -#' # Then, run the targets pipeline as usual. -#' }) -#' } tar_quarto_rep_raw <- function( name, path, diff --git a/R/tar_render.R b/R/tar_render.R index d210c3d..e812e8f 100644 --- a/R/tar_render.R +++ b/R/tar_render.R @@ -3,6 +3,13 @@ #' @family Literate programming targets #' @description Shorthand to include an R Markdown document in a #' `targets` pipeline. +#' +#' [tar_render()] expects an unevaluated symbol for the `name` argument, +#' and it supports named `...` arguments for `rmarkdown::render()` +#' arguments. +#' [tar_render_raw()] expects a character string for `name` and +#' supports an evaluated expression object +#' `render_arguments` for `rmarkdown::render()` arguments. #' @details `tar_render()` is an alternative to `tar_target()` for #' R Markdown reports that depend on other targets. The R Markdown source #' should mention dependency targets with `tar_load()` and `tar_read()` @@ -48,6 +55,10 @@ #' @inheritSection tar_map Target objects #' @inheritParams targets::tar_target #' @inheritParams rmarkdown::render +#' @param name Name of the target. +#' [tar_render()] expects an unevaluated symbol for the `name` argument, +#' whereas +#' [tar_render_raw()] expects a character string for `name`. #' @param path Character string, file path to the R Markdown source file. #' Must have length 1. #' @param output_file Character string, file path to the rendered output file. @@ -71,7 +82,16 @@ #' For parameterized reports, it is recommended to supply a distinct #' `output_file` argument to each `tar_render()` call #' and set useful defaults for parameters in the R Markdown source. -#' See the examples section for a demonstration. +#' See the examples section for a demonstration. +#' @param render_arguments Optional language object with a list +#' of named arguments to `rmarkdown::render()`. +#' Cannot be an expression object. +#' (Use `quote()`, not `expression()`.) +#' The reason for quoting is that these arguments may depend on +#' upstream targets whose values are not available at +#' the time the target is defined, and because `tar_render_raw()` +#' is the "raw" version of a function, we want to avoid +#' all non-standard evaluation. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -114,7 +134,16 @@ #' library(tarchetypes) #' list( #' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_render(report, "report.Rmd", params = list(your_param = data)) +#' tar_render( +#' name = report, +#' "report.Rmd", +#' params = list(your_param = data) +#' ), +#' tar_render_raw( +#' name = "report2", +#' "report.Rmd", +#' params = quote(list(your_param = data)) +#' ) #' ) #' }, ask = FALSE) #' }) diff --git a/R/tar_render_raw.R b/R/tar_render_raw.R index 41a2a69..1f0b9c1 100644 --- a/R/tar_render_raw.R +++ b/R/tar_render_raw.R @@ -1,86 +1,5 @@ -#' @title Target with an R Markdown document (raw version). +#' @rdname tar_render #' @export -#' @family Literate programming targets -#' @description Shorthand to include an R Markdown document in a -#' `targets` pipeline (raw version) -#' @details `tar_render_raw()` is just like `tar_render()` -#' except that it uses standard evaluation. The `name` argument -#' is a character vector, and the `render_arguments` argument -#' is a language object. -#' @return A target object with `format = "file"`. -#' When this target runs, it returns a character vector -#' of file paths: the rendered document, the source file, -#' and then the `*_files/` directory if it exists. -#' Unlike `rmarkdown::render()`, -#' all returned paths are *relative* paths to ensure portability -#' (so that the project can be moved from one file system to another -#' without invalidating the target). -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_render Literate programming limitations -#' @inheritParams tar_render -#' @param name Character of length 1, name of the target. -#' @param render_arguments Optional language object with a list -#' of named arguments to `rmarkdown::render()`. -#' Cannot be an expression object. -#' (Use `quote()`, not `expression()`.) -#' The reason for quoting is that these arguments may depend on -#' upstream targets whose values are not available at -#' the time the target is defined, and because `tar_render_raw()` -#' is the "raw" version of a function, we want to avoid -#' all non-standard evaluation. -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' # Unparameterized R Markdown report: -#' lines <- c( -#' "---", -#' "title: 'report.Rmd source file'", -#' "output_format: html_document", -#' "---", -#' "Assume these lines are in report.Rmd.", -#' "```{r}", -#' "targets::tar_read(data)", -#' "```" -#' ) -#' # Include the report in the pipeline as follows: -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_render_raw("report", "report.Rmd") -#' ) -#' }, ask = FALSE) -#' # Then, run the targets pipeline as usual. -#' -#' # Parameterized R Markdown: -#' lines <- c( -#' "---", -#' "title: 'report.Rmd source file with parameters.'", -#' "output_format: html_document", -#' "params:", -#' " your_param: \"default value\"", -#' "---", -#' "Assume these lines are in report.Rmd.", -#' "```{r}", -#' "print(params$your_param)", -#' "```" -#' ) -#' # Include this parameterized report in the pipeline as follows. -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_target(data, data.frame(x = seq_len(26), y = letters)), -#' tar_render_raw( -#' "report", -#' "report.Rmd", -#' render_arguments = quote(list(params = list(your_param = data))) -#' ) -#' ) -#' }, ask = FALSE) -#' # Then, run the targets pipeline as usual. -#' }) -#' } tar_render_raw <- function( name, path, diff --git a/R/tar_render_rep.R b/R/tar_render_rep.R index d2f24dc..e672d58 100644 --- a/R/tar_render_rep.R +++ b/R/tar_render_rep.R @@ -3,6 +3,13 @@ #' @family Literate programming targets #' @description Targets to render a parameterized R Markdown report #' with multiple sets of parameters. +#' +#' [tar_render_rep()] expects an unevaluated symbol for the `name` argument, +#' and it supports named `...` arguments for `rmarkdown::render()` +#' arguments. +#' [tar_render_rep_raw()] expects a character string for `name` and +#' supports an evaluated expression object +#' `render_arguments` for `rmarkdown::render()` arguments. #' @details `tar_render_rep()` is an alternative to `tar_target()` for #' parameterized R Markdown reports that depend on other targets. #' Parameters must be given as a data frame with one row per @@ -38,10 +45,14 @@ #' @inheritSection tar_map Target objects #' @inheritSection tar_rep Replicate-specific seeds #' @inheritSection tar_render Literate programming limitations +#' @inheritParams tar_render #' @inheritParams tar_rep #' @inheritParams targets::tar_target #' @inheritParams rmarkdown::render -#' @inheritParams tar_render_rep_raw +#' @param name Name of the target. +#' [tar_render_rep()] expects an unevaluated symbol for the `name` argument, +#' whereas +#' [tar_render_rep_raw()] expects a character string for `name`. #' @param path Character string, file path to the R Markdown source file. #' Must have length 1. #' @param params Code to generate a data frame or `tibble` @@ -55,6 +66,9 @@ #' is defined, not when it is run. (The only reason to delay evaluation #' in [tar_render()] was to handle R Markdown parameters, and #' `tar_render_rep()` handles them differently.) +#' @param args Named list of other arguments to `rmarkdown::render()`. +#' Must not include `params` or `output_file`. Evaluated when the target +#' is defined. #' @examples #' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { #' targets::tar_dir({ # tar_dir() runs code from a temporary directory. @@ -76,9 +90,14 @@ #' library(tarchetypes) #' list( #' tar_render_rep( -#' report, +#' name = report, #' "report.Rmd", #' params = tibble::tibble(par = c(1, 2)) +#' ), +#' tar_render_rep_raw( +#' name = "report2", +#' "report.Rmd", +#' params = quote(tibble::tibble(par = c(1, 2))) #' ) #' ) #' }, ask = FALSE) diff --git a/R/tar_render_rep_raw.R b/R/tar_render_rep_raw.R index 3f41d57..d5fcfcd 100644 --- a/R/tar_render_rep_raw.R +++ b/R/tar_render_rep_raw.R @@ -1,104 +1,5 @@ -#' @title Parameterized R Markdown with dynamic branching (raw version). +#' @rdname tar_render_rep #' @export -#' @family Literate programming targets -#' @description Targets to render a parameterized R Markdown report -#' with multiple sets of parameters (raw version). Same as -#' `tar_render_rep()` except `name` is a character string, -#' `params` is an expression object, -#' and extra arguments to `rmarkdown::render()` are passed through -#' the `args` argument instead of `...`. -#' @details `tar_render_rep_raw()` is an alternative to `tar_target_raw()` for -#' parameterized R Markdown reports that depend on other targets. -#' Parameters must be given as a data frame with one row per -#' rendered report and one column per parameter. An optional -#' `output_file` column may be included to set the output file path -#' of each rendered report. -#' The R Markdown source should mention other dependency targets -#' `tar_load()` and `tar_read()` in the active code chunks -#' (which also allows you to render the report -#' outside the pipeline if the `_targets/` data store already exists -#' and appropriate defaults are specified for the parameters). -#' (Do not use `tar_load_raw()` or `tar_read_raw()` for this.) -#' Then, `tar_render()` defines a special kind of target. It -#' 1. Finds all the `tar_load()`/`tar_read()` dependencies in the report -#' and inserts them into the target's command. -#' This enforces the proper dependency relationships. -#' (Do not use `tar_load_raw()` or `tar_read_raw()` for this.) -#' 2. Sets `format = "file"` (see `tar_target()`) so `targets` -#' watches the files at the returned paths and reruns the report -#' if those files change. -#' 3. Configures the target's command to return the output -#' report files: the rendered document, the source file, -#' and then the `*_files/` directory if it exists. -#' All these file paths -#' are relative paths so the project stays portable. -#' 4. Forces the report to run in the user's current working directory -#' instead of the working directory of the report. -#' 5. Sets convenient default options such as `deployment = "main"` -#' in the target and `quiet = TRUE` in `rmarkdown::render()`. -#' @return A list of target objects to render the R Markdown -#' reports. Changes to the parameters, source file, dependencies, etc. -#' will cause the appropriate targets to rerun during `tar_make()`. -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @inheritSection tar_rep Replicate-specific seeds -#' @inheritSection tar_render Literate programming limitations -#' @inheritParams targets::tar_target -#' @inheritParams rmarkdown::render -#' @inheritParams tar_rep -#' @inheritParams tar_render -#' @param path Character string, file path to the R Markdown source file. -#' Must have length 1. -#' @param params Expression object with code to generate -#' a data frame or `tibble` with one row per rendered report -#' and one column per R Markdown parameter. You may also include an -#' `output_file` column to specify the path of each rendered report. -#' R Markdown parameters must not be named `tar_group` or `output_file`. -#' This `params` argument is converted into the command for a target -#' that supplies the R Markdown parameters. -#' @param batches Number of batches to group the R Markdown files. -#' For a large number of reports, increase the number of batches -#' to decrease target-level overhead. Defaults to the number of -#' reports to render (1 report per batch). -#' @param format Character of length 1, `format` argument to `tar_target()` -#' to store the data frame of R Markdown parameters. -#' @param iteration Character of length 1, `iteration` argument -#' to `tar_target()` for the R Markdown documents. Does not apply -#' to the target with R Markdown parameters (whose iteration -#' is always `"group"`). -#' @param args Named list of other arguments to `rmarkdown::render()`. -#' Must not include `params` or `output_file`. Evaluated when the target -#' is defined. -#' @examples -#' if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. -#' # Parameterized R Markdown: -#' lines <- c( -#' "---", -#' "title: 'report.Rmd source file'", -#' "output_format: html_document", -#' "params:", -#' " par: \"default value\"", -#' "---", -#' "Assume these lines are in a file called report.Rmd.", -#' "```{r}", -#' "print(params$par)", -#' "```" -#' ) -#' # The following pipeline will run the report for each row of params. -#' targets::tar_script({ -#' library(tarchetypes) -#' list( -#' tar_render_rep_raw( -#' "report", -#' "report.Rmd", -#' params = quote(tibble::tibble(par = c(1, 2))) -#' ) -#' ) -#' }, ask = FALSE) -#' # Then, run the targets pipeline as usual. -#' }) -#' } tar_render_rep_raw <- function( name, path, diff --git a/R/tar_sub.R b/R/tar_sub.R index f591042..f6c7add 100644 --- a/R/tar_sub.R +++ b/R/tar_sub.R @@ -3,13 +3,22 @@ #' @family Metaprogramming utilities #' @description Loop over a grid of values and create an expression object #' from each one. Helps with general metaprogramming. +#' +#' [tar_sub()] expects an unevaluated expression for +#' the `expr` object, whereas [tar_sub_raw()] expects an +#' evaluated expression object. #' @return A list of expression objects. Often, these expression objects #' evaluate to target objects (but not necessarily). #' See the "Target objects" section for background. #' @inheritSection tar_map Target objects -#' @inheritParams tar_sub_raw #' @param expr Starting expression. Values are iteratively substituted #' in place of symbols in `expr` to create each new expression. +#' +#' [tar_sub()] expects an unevaluated expression for +#' the `expr` object, whereas [tar_sub_raw()] expects an +#' evaluated expression object. +#' @param values List of values to substitute into `expr` to create +#' the expressions. All elements of `values` must have the same length. #' @examples #' # tar_map() is incompatible with tar_render() because the latter #' # operates on preexisting tar_target() objects. By contrast, @@ -19,6 +28,7 @@ #' file = list("file1.Rmd", "file2.Rmd") #' ) #' tar_sub(tar_render(name, file), values = values) +#' tar_sub_raw(quote(tar_render(name, file)), values = values) tar_sub <- function(expr, values) { tar_sub_raw(expr = substitute(expr), values = values) } diff --git a/R/tar_sub_raw.R b/R/tar_sub_raw.R index b843ca1..830fbf8 100644 --- a/R/tar_sub_raw.R +++ b/R/tar_sub_raw.R @@ -1,28 +1,5 @@ -#' @title Create multiple expressions with symbol substitution (raw version). +#' @rdname tar_sub #' @export -#' @family Metaprogramming utilities -#' @description Loop over a grid of values and create an expression object -#' from each one. Helps with general metaprogramming. Unlike [tar_sub()], -#' which quotes the `expr` argument, `tar_sub_raw()` assumes `expr` -#' is an expression object. -#' @return A list of expression objects. Often, these expression objects -#' evaluate to target objects (but not necessarily). -#' See the "Target objects" section for background. -#' @inheritSection tar_map Target objects -#' @param expr Expression object with the starting expression. -#' Values are iteratively substituted -#' in place of symbols in `expr` to create each new expression. -#' @param values List of values to substitute into `expr` to create -#' the expressions. All elements of `values` must have the same length. -#' @examples -#' # tar_map() is incompatible with tar_render() because the latter -#' # operates on preexisting tar_target() objects. By contrast, -#' # tar_eval_raw() and tar_sub_raw() iterate over code farther upstream. -#' values <- list( -#' name = lapply(c("name1", "name2"), as.symbol), -#' file = c("file1.Rmd", "file2.Rmd") -#' ) -#' tar_sub_raw(quote(tar_render(name, file)), values = values) tar_sub_raw <- function(expr, values) { targets::tar_assert_lang(expr) assert_values_list(values) diff --git a/_pkgdown.yml b/_pkgdown.yml index cfda6a1..f820123 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -17,13 +17,9 @@ reference: contents: - 'tar_knit' - 'tar_quarto' - - 'tar_quarto_raw' - 'tar_quarto_rep' - - 'tar_quarto_rep_raw' - 'tar_render' - - 'tar_render_raw' - 'tar_render_rep' - - 'tar_render_rep_raw' - title: Literate programming utilities contents: - 'tar_knitr_deps' @@ -56,13 +52,10 @@ reference: - title: Dynamic batched replication within static branches for data frames contents: - 'tar_map_rep' - - 'tar_map_rep_raw' - title: Batched dynamic-within-static branching for data frames contents: - 'tar_map2_count' - - 'tar_map2_count_raw' - 'tar_map2_size' - - 'tar_map2_size_raw' - title: Target selection contents: - 'tar_select_names' @@ -77,23 +70,17 @@ reference: - title: Cues contents: - 'tar_cue_age' - - 'tar_cue_age_raw' - 'tar_cue_force' - 'tar_cue_skip' - title: Hooks contents: - 'tar_hook_before' - - 'tar_hook_before_raw' - 'tar_hook_inner' - - 'tar_hook_inner_raw' - 'tar_hook_outer' - - 'tar_hook_outer_raw' - title: Metaprogramming utilities contents: - 'tar_eval' - - 'tar_eval_raw' - 'tar_sub' - - 'tar_sub_raw' - title: Domain-specific languages for pipeline construction contents: - 'tar_assign' diff --git a/man/tar_age.Rd b/man/tar_age.Rd index 5439c46..1759b18 100644 --- a/man/tar_age.Rd +++ b/man/tar_age.Rd @@ -28,7 +28,10 @@ tar_age( ) } \arguments{ -\item{name}{Character of length 1, name of the target.} +\item{name}{Name of the target. +\code{tar_cue_age()} expects an unevaluated symbol for the \code{name} +argument, whereas \code{tar_cue_age_raw()} expects a character string +for \code{name}.} \item{command}{R code to run the target and return a value.} @@ -275,7 +278,6 @@ targets::tar_make() \seealso{ Other cues: \code{\link{tar_cue_age}()}, -\code{\link{tar_cue_age_raw}()}, \code{\link{tar_cue_force}()}, \code{\link{tar_cue_skip}()} } diff --git a/man/tar_cue_age.Rd b/man/tar_cue_age.Rd index 6955185..a9a9069 100644 --- a/man/tar_cue_age.Rd +++ b/man/tar_cue_age.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_cue_age.R +% Please edit documentation in R/tar_cue_age.R, R/tar_cue_age_raw.R \name{tar_cue_age} \alias{tar_cue_age} +\alias{tar_cue_age_raw} \title{Cue to run a target when the last output reaches a certain age} \usage{ tar_cue_age( @@ -14,9 +15,23 @@ tar_cue_age( iteration = TRUE, file = TRUE ) + +tar_cue_age_raw( + name, + age, + command = TRUE, + depend = TRUE, + format = TRUE, + repository = TRUE, + iteration = TRUE, + file = TRUE +) } \arguments{ -\item{name}{Symbol, name of the target.} +\item{name}{Name of the target. +\code{tar_cue_age()} expects an unevaluated symbol for the \code{name} +argument, whereas \code{tar_cue_age_raw()} expects a character string +for \code{name}.} \item{age}{A \code{difftime} object of length 1, such as \code{as.difftime(3, units = "days")}. If the target's output data @@ -59,6 +74,10 @@ rerun a target if the most recent output data becomes old enough. The age of the target is determined by \code{targets::tar_timestamp()}, and the way the time stamp is calculated is explained in the Details section of the help file of that function. + +\code{tar_cue_age()} expects an unevaluated symbol for the \code{name} +argument, whereas \code{tar_cue_age_raw()} expects a character string +for \code{name}. } \details{ \code{tar_cue_age()} uses the time stamps from \code{tar_meta()$time}. @@ -80,6 +99,18 @@ will rerun those targets. \section{Cue objects}{ +A cue object is an object generated by \code{targets::tar_cue()}, +\code{tarchetypes::tar_cue_force()}, or similar. It is +a collection of decision rules that decide when a target +is invalidated/outdated (e.g. when \code{tar_make()} or similar +reruns the target). You can supply these cue objects to the +\code{tar_target()} function or similar. For example, +\code{tar_target(x, run_stuff(), cue = tar_cue(mode = "always"))} +is a target that always calls \code{run_stuff()} during \code{tar_make()} +and always shows as invalidated/outdated in \code{tar_outdated()}, +\code{tar_visnetwork()}, and similar functions. + + A cue object is an object generated by \code{targets::tar_cue()}, \code{tarchetypes::tar_cue_force()}, or similar. It is a collection of decision rules that decide when a target @@ -117,7 +148,6 @@ targets::tar_make() \seealso{ Other cues: \code{\link{tar_age}()}, -\code{\link{tar_cue_age_raw}()}, \code{\link{tar_cue_force}()}, \code{\link{tar_cue_skip}()} } diff --git a/man/tar_cue_age_raw.Rd b/man/tar_cue_age_raw.Rd deleted file mode 100644 index f50225a..0000000 --- a/man/tar_cue_age_raw.Rd +++ /dev/null @@ -1,127 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_cue_age_raw.R -\name{tar_cue_age_raw} -\alias{tar_cue_age_raw} -\title{Cue to run a target when the last run reaches a certain age -(raw version)} -\usage{ -tar_cue_age_raw( - name, - age, - command = TRUE, - depend = TRUE, - format = TRUE, - repository = TRUE, - iteration = TRUE, - file = TRUE -) -} -\arguments{ -\item{name}{Character of length 1, name of the target.} - -\item{age}{A \code{difftime} object of length 1, such as -\code{as.difftime(3, units = "days")}. If the target's output data -files are older than \code{age} (according to the most recent -time stamp over all the target's output files) -then the target will rerun. -On the other hand, if at least one data file is -younger than \code{Sys.time() - age}, then the ordinary -invalidation rules apply, and the target may or not rerun. -If you want to force the target to run every 3 days, -for example, set \code{age = as.difftime(3, units = "days")}.} - -\item{command}{Logical, whether to rerun the target if command changed -since last time.} - -\item{depend}{Logical, whether to rerun the target if the value of one -of the dependencies changed.} - -\item{format}{Logical, whether to rerun the target if the user-specified -storage format changed. The storage format is user-specified through -\code{\link[targets:tar_target]{tar_target()}} or \code{\link[targets:tar_option_set]{tar_option_set()}}.} - -\item{repository}{Logical, whether to rerun the target if the user-specified -storage repository changed. The storage repository is user-specified -through \code{\link[targets:tar_target]{tar_target()}} or \code{\link[targets:tar_option_set]{tar_option_set()}}.} - -\item{iteration}{Logical, whether to rerun the target if the user-specified -iteration method changed. The iteration method is user-specified through -\code{\link[targets:tar_target]{tar_target()}} or \code{\link[targets:tar_option_set]{tar_option_set()}}.} - -\item{file}{Logical, whether to rerun the target if the file(s) with the -return value changed or at least one is missing.} -} -\value{ -A cue object. See the "Cue objects" section for background. -} -\description{ -\code{tar_cue_age_raw()} acts like \code{tar_cue_age()} -except the \code{name} argument is a character string, -not a symbol. \code{tar_cue_age_raw()} creates a cue object to -rerun a target if the most recent output data becomes old enough. -The age of the target is determined by \code{targets::tar_timestamp()}, -and the way the time stamp is calculated is explained -in the Details section of the help file of that function. -} -\details{ -\code{tar_cue_age_raw()} uses the time stamps from \code{tar_meta()$time}. -If no time stamp is recorded, the cue defaults to the ordinary -invalidation rules (i.e. \code{mode = "thorough"} in \code{targets::tar_cue()}). -} -\section{Dynamic branches at regular time intervals}{ - -Time stamps are not recorded for whole dynamic targets, -so \code{tar_age()} is not a good fit for dynamic branching. -To invalidate dynamic branches at regular intervals, -it is recommended to use \code{targets::tar_older()} in combination -with \code{targets::tar_invalidate()} right before calling \code{tar_make()}. -For example, -\code{tar_invalidate(any_of(tar_older(Sys.time - as.difftime(1, units = "weeks"))))} # nolint -invalidates all targets more than a week old. Then, the next \code{tar_make()} -will rerun those targets. -} - -\section{Cue objects}{ - -A cue object is an object generated by \code{targets::tar_cue()}, -\code{tarchetypes::tar_cue_force()}, or similar. It is -a collection of decision rules that decide when a target -is invalidated/outdated (e.g. when \code{tar_make()} or similar -reruns the target). You can supply these cue objects to the -\code{tar_target()} function or similar. For example, -\code{tar_target(x, run_stuff(), cue = tar_cue(mode = "always"))} -is a target that always calls \code{run_stuff()} during \code{tar_make()} -and always shows as invalidated/outdated in \code{tar_outdated()}, -\code{tar_visnetwork()}, and similar functions. -} - -\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( - targets::tar_target( - data, - data.frame(x = seq_len(26)), - cue = tarchetypes::tar_cue_age_raw( - name = "data", - age = as.difftime(0.5, units = "secs") - ) - ) - ) -}) -targets::tar_make() -Sys.sleep(0.6) -targets::tar_make() -}) -} -} -\seealso{ -Other cues: -\code{\link{tar_age}()}, -\code{\link{tar_cue_age}()}, -\code{\link{tar_cue_force}()}, -\code{\link{tar_cue_skip}()} -} -\concept{cues} diff --git a/man/tar_cue_force.Rd b/man/tar_cue_force.Rd index 84ed128..3c753f6 100644 --- a/man/tar_cue_force.Rd +++ b/man/tar_cue_force.Rd @@ -100,7 +100,6 @@ targets::tar_make() Other cues: \code{\link{tar_age}()}, \code{\link{tar_cue_age}()}, -\code{\link{tar_cue_age_raw}()}, \code{\link{tar_cue_skip}()} } \concept{cues} diff --git a/man/tar_cue_skip.Rd b/man/tar_cue_skip.Rd index 8685a96..909f03a 100644 --- a/man/tar_cue_skip.Rd +++ b/man/tar_cue_skip.Rd @@ -102,7 +102,6 @@ targets::tar_make() Other cues: \code{\link{tar_age}()}, \code{\link{tar_cue_age}()}, -\code{\link{tar_cue_age_raw}()}, \code{\link{tar_cue_force}()} } \concept{cues} diff --git a/man/tar_eval.Rd b/man/tar_eval.Rd index df288d5..46cf2b5 100644 --- a/man/tar_eval.Rd +++ b/man/tar_eval.Rd @@ -1,15 +1,22 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_eval.R +% Please edit documentation in R/tar_eval.R, R/tar_eval_raw.R \name{tar_eval} \alias{tar_eval} +\alias{tar_eval_raw} \title{Evaluate multiple expressions created with symbol substitution.} \usage{ tar_eval(expr, values, envir = parent.frame()) + +tar_eval_raw(expr, values, envir = parent.frame()) } \arguments{ \item{expr}{Starting expression. Values are iteratively substituted in place of symbols in \code{expr} to create each new expression, -and then each new expression is evaluated.} +and then each new expression is evaluated. + +\code{\link[=tar_eval]{tar_eval()}} expects an unevaluated expression for +the \code{expr} object, whereas \code{\link[=tar_eval_raw]{tar_eval_raw()}} expects an +evaluated expression object.} \item{values}{List of values to substitute into \code{expr} to create the expressions. All elements of \code{values} must have the same length.} @@ -26,6 +33,10 @@ on target objects specifically. Loop over a grid of values, create an expression object from each one, and then evaluate that expression. Helps with general metaprogramming. + +\code{\link[=tar_eval]{tar_eval()}} expects an unevaluated expression for +the \code{expr} object, whereas \code{\link[=tar_eval_raw]{tar_eval_raw()}} expects an +evaluated expression object. } \section{Target objects}{ @@ -60,6 +71,7 @@ tar_sub(tar_render(name, file), values = values) path <- tempfile() file.create(path) str(tar_eval(tar_render(name, path), values = values)) +str(tar_eval_raw(quote(tar_render(name, path)), values = values)) # So in your _targets.R file, you can define a pipeline like as below. # Just make sure to set a unique name for each target # (which tar_map() does automatically). @@ -73,8 +85,6 @@ list( } \seealso{ Other Metaprogramming utilities: -\code{\link{tar_eval_raw}()}, -\code{\link{tar_sub}()}, -\code{\link{tar_sub_raw}()} +\code{\link{tar_sub}()} } \concept{Metaprogramming utilities} diff --git a/man/tar_eval_raw.Rd b/man/tar_eval_raw.Rd deleted file mode 100644 index c03aa9d..0000000 --- a/man/tar_eval_raw.Rd +++ /dev/null @@ -1,83 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_eval_raw.R -\name{tar_eval_raw} -\alias{tar_eval_raw} -\title{Evaluate multiple expressions created with symbol substitution -(raw version).} -\usage{ -tar_eval_raw(expr, values, envir = parent.frame()) -} -\arguments{ -\item{expr}{Expression object with the starting expression. -Values are iteratively substituted -in place of symbols in \code{expr} to create each new expression, -and then each expression is evaluated.} - -\item{values}{List of values to substitute into \code{expr} to create -the expressions. All elements of \code{values} must have the same length.} - -\item{envir}{Environment in which to evaluate the new expressions.} -} -\value{ -A list of return values from evaluating the expression objects. -Often, these values are target objects. -See the "Target objects" section for background -on target objects specifically. -} -\description{ -Loop over a grid of values, create an expression object -from each one, and then evaluate that expression. -Helps with general metaprogramming. Unlike \code{\link[=tar_sub]{tar_sub()}}, -which quotes the \code{expr} argument, \code{tar_sub_raw()} assumes \code{expr} -is an expression object. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\examples{ -# tar_map() is incompatible with tar_render() because the latter -# operates on preexisting tar_target() objects. By contrast, -# tar_eval_raw() and tar_sub_raw() iterate over code farther upstream. -values <- list( - name = lapply(c("name1", "name2"), as.symbol), - file = c("file1.Rmd", "file2.Rmd") -) -tar_sub_raw(quote(list(name, file)), values = values) -tar_sub_raw(quote(tar_render(name, file)), values = values) -path <- tempfile() -file.create(path) -str(tar_eval_raw(quote(tar_render(name, path)), values = values)) -# So in your _targets.R file, you can define a pipeline like as below. -# Just make sure to set a unique name for each target -# (which tar_map() does automatically). -values <- list( - name = lapply(c("name1", "name2"), as.symbol), - file = c(path, path) -) -list( - tar_eval_raw(quote(tar_render(name, file)), values = values) -) -} -\seealso{ -Other Metaprogramming utilities: -\code{\link{tar_eval}()}, -\code{\link{tar_sub}()}, -\code{\link{tar_sub_raw}()} -} -\concept{Metaprogramming utilities} diff --git a/man/tar_hook_before.Rd b/man/tar_hook_before.Rd index 190b132..fefa9c2 100644 --- a/man/tar_hook_before.Rd +++ b/man/tar_hook_before.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_hook_before.R +% Please edit documentation in R/tar_hook_before.R, R/tar_hook_before_raw.R \name{tar_hook_before} \alias{tar_hook_before} +\alias{tar_hook_before_raw} \title{Hook to prepend code} \usage{ tar_hook_before( @@ -11,6 +12,14 @@ tar_hook_before( set_deps = TRUE, envir = parent.frame() ) + +tar_hook_before_raw( + targets, + hook, + names = NULL, + set_deps = TRUE, + envir = parent.frame() +) } \arguments{ \item{targets}{A list of target objects. The input target list @@ -19,16 +28,21 @@ objects. In addition, the return value is a simple list where each element is a target object. All hook functions remove the nested structure of the input target list.} -\item{hook}{R code to insert. When you supply code to this argument, -the code is quoted (not evaluated) so there is no need -to wrap it in \code{quote()}, \code{expression()}, or similar.} +\item{hook}{R code to insert. +\code{tar_hook_before()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_before_raw()} expects +evaluated expression objects.} \item{names}{Name of targets in the target list -to apply the hook. Supplied with \code{tidyselect} helpers like +to apply the hook. Supplied using \code{tidyselect} helpers like \code{\link[=starts_with]{starts_with()}}, as in \code{names = starts_with("your_prefix_")}. Set to \code{NULL} to include all targets supplied to the \code{targets} argument. Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} +but they are not modified because the hook does not apply to them. + +The regular hook functions expects unevaluated expressions for the \code{hook} +and \code{names} arguments, whereas the \code{"_raw"} versions expect +evaluated expression objects.} \item{set_deps}{Logical of length 1, whether to refresh the dependencies of each modified target by scanning the newly generated @@ -49,6 +63,9 @@ All hook functions remove the nested structure of the input target list. } \description{ Prepend R code to the commands of multiple targets. +\code{tar_hook_before()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_before_raw()} expects +evaluated expression objects. } \section{Target objects}{ @@ -90,13 +107,28 @@ targets::tar_script({ }) targets::tar_manifest(fields = command) }) +# With tar_hook_before_raw(): +targets::tar_script({ + targets <- list( + # Nested target lists work with hooks. + list( + targets::tar_target(x1, task1()), + targets::tar_target(x2, task2(x1)) + ), + targets::tar_target(x3, task3(x2)), + targets::tar_target(y1, task4(x3)) + ) + tarchetypes::tar_hook_before_raw( + targets = targets, + hook = quote(print("Running hook.")), + names = quote(starts_with("x")) + ) +}) } } \seealso{ Other hooks: -\code{\link{tar_hook_before_raw}()}, \code{\link{tar_hook_inner}()}, -\code{\link{tar_hook_inner_raw}()}, \code{\link{tar_hook_outer}()}, \code{\link{tar_hook_outer_raw}()} } diff --git a/man/tar_hook_before_raw.Rd b/man/tar_hook_before_raw.Rd deleted file mode 100644 index 1dfb73e..0000000 --- a/man/tar_hook_before_raw.Rd +++ /dev/null @@ -1,102 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_hook_before_raw.R -\name{tar_hook_before_raw} -\alias{tar_hook_before_raw} -\title{Hook to prepend code (raw version)} -\usage{ -tar_hook_before_raw( - targets, - hook, - names = NULL, - set_deps = TRUE, - envir = parent.frame() -) -} -\arguments{ -\item{targets}{A list of target objects. The input target list -can be arbitrarily nested, but it must consist entirely of target -objects. In addition, the return value is a simple list -where each element is a target object. -All hook functions remove the nested structure of the input target list.} - -\item{hook}{A pre-quoted language object with R code to insert.} - -\item{names}{Name of targets in the target list -to apply the hook. Supplied as a language object with a -\code{tidyselect} expression: for example, \code{names = quote(starts_with("x_"))}. -Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} - -\item{set_deps}{Logical of length 1, whether to refresh the dependencies -of each modified target by scanning the newly generated -target commands for dependencies. If \code{FALSE}, then the target will -keep the original set of dependencies it had before the hook. -Set to \code{NULL} to include all targets supplied to the \code{targets} argument. -\code{TRUE} is recommended for nearly all situations. Only use \code{FALSE} -if you have a specialized use case and you know what you are doing.} - -\item{envir}{Optional environment to construct the quosure for the \code{names} -argument to select names.} -} -\value{ -A flattened list of target objects with the hooks applied. -Even if the input target list had a nested structure, -the return value is a simple list where each element is a target object. -All hook functions remove the nested structure of the input target list. -} -\description{ -Prepend R code to the commands of multiple targets. -Like \code{\link[=tar_hook_before]{tar_hook_before()}} except that the \code{hook} and \code{names} -arguments are already pre-quoted language objects. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -targets::tar_script({ - targets <- list( - # Nested target lists work with hooks. - list( - targets::tar_target(x1, task1()), - targets::tar_target(x2, task2(x1)) - ), - targets::tar_target(x3, task3(x2)), - targets::tar_target(y1, task4(x3)) - ) - tarchetypes::tar_hook_before_raw( - targets = targets, - hook = quote(print("Running hook.")), - names = quote(starts_with("x")) - ) -}) -targets::tar_manifest(fields = command) -}) -} -} -\seealso{ -Other hooks: -\code{\link{tar_hook_before}()}, -\code{\link{tar_hook_inner}()}, -\code{\link{tar_hook_inner_raw}()}, -\code{\link{tar_hook_outer}()}, -\code{\link{tar_hook_outer_raw}()} -} -\concept{hooks} diff --git a/man/tar_hook_inner.Rd b/man/tar_hook_inner.Rd index 2c22c43..443b40d 100644 --- a/man/tar_hook_inner.Rd +++ b/man/tar_hook_inner.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_hook_inner.R +% Please edit documentation in R/tar_hook_inner.R, R/tar_hook_inner_raw.R \name{tar_hook_inner} \alias{tar_hook_inner} +\alias{tar_hook_inner_raw} \title{Hook to wrap dependencies} \usage{ tar_hook_inner( @@ -12,6 +13,15 @@ tar_hook_inner( set_deps = TRUE, envir = parent.frame() ) + +tar_hook_inner_raw( + targets, + hook, + names = NULL, + names_wrap = NULL, + set_deps = TRUE, + envir = parent.frame() +) } \arguments{ \item{targets}{A list of target objects. The input target list @@ -24,15 +34,21 @@ All hook functions remove the nested structure of the input target list.} The hook must contain the special placeholder symbol \code{.x} so \code{tar_hook_inner()} knows where to insert the code to wrap mentions of dependencies. -The hook code is quoted (not evaluated) so there is no need -to wrap it in \code{quote()}, \code{expression()}, or similar.} + +\code{tar_hook_inner()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_inner_raw()} expects +evaluated expression objects.} \item{names}{Name of targets in the target list -to apply the hook. Supplied with \code{tidyselect} helpers like +to apply the hook. Supplied using \code{tidyselect} helpers like \code{\link[=starts_with]{starts_with()}}, as in \code{names = starts_with("your_prefix_")}. Set to \code{NULL} to include all targets supplied to the \code{targets} argument. Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} +but they are not modified because the hook does not apply to them. + +The regular hook functions expects unevaluated expressions for the \code{hook} +and \code{names} arguments, whereas the \code{"_raw"} versions expect +evaluated expression objects.} \item{names_wrap}{Names of targets to wrap with the hook where they appear as dependencies in the commands of other targets. @@ -59,6 +75,10 @@ All hook functions remove the nested structure of the input target list. \description{ In the command of each target, wrap each mention of each dependency target in an arbitrary R expression. + +\code{tar_hook_inner()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_inner_raw()} expects +evaluated expression objects. } \details{ The expression you supply to \code{hook} @@ -105,14 +125,29 @@ targets::tar_script({ ) }) targets::tar_manifest(fields = command) +# With tar_hook_inner_raw(): +targets::tar_script({ + targets <- list( + # Nested target lists work with hooks. + list( + targets::tar_target(x1, task1()), + targets::tar_target(x2, task2(x1)) + ), + targets::tar_target(x3, task3(x2, x1)), + targets::tar_target(y1, task4(x3)) + ) + tarchetypes::tar_hook_inner_raw( + targets = targets, + hook = quote(fun(.x)), + names = quote(starts_with("x")) + ) +}) }) } } \seealso{ Other hooks: \code{\link{tar_hook_before}()}, -\code{\link{tar_hook_before_raw}()}, -\code{\link{tar_hook_inner_raw}()}, \code{\link{tar_hook_outer}()}, \code{\link{tar_hook_outer_raw}()} } diff --git a/man/tar_hook_inner_raw.Rd b/man/tar_hook_inner_raw.Rd deleted file mode 100644 index ac96c83..0000000 --- a/man/tar_hook_inner_raw.Rd +++ /dev/null @@ -1,121 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_hook_inner_raw.R -\name{tar_hook_inner_raw} -\alias{tar_hook_inner_raw} -\title{Hook to wrap dependencies (raw version)} -\usage{ -tar_hook_inner_raw( - targets, - hook, - names = NULL, - names_wrap = NULL, - set_deps = TRUE, - envir = parent.frame() -) -} -\arguments{ -\item{targets}{A list of target objects. The input target list -can be arbitrarily nested, but it must consist entirely of target -objects. In addition, the return value is a simple list -where each element is a target object. -All hook functions remove the nested structure of the input target list.} - -\item{hook}{Pre-quoted language object with -R code to wrap each target's command. -The hook must contain the special placeholder symbol \code{.x} -so \code{tar_hook_inner()} knows where to insert the code to wrap -mentions of dependencies.} - -\item{names}{Name of targets in the target list -to apply the hook. Supplied as a language object with a -\code{tidyselect} expression: for example, \code{names = quote(starts_with("x_"))}. -Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} - -\item{names_wrap}{Pre-quoted language object with -names of targets to wrap with the hook -where they appear as dependencies in the commands of other targets. -Use \code{tidyselect} expressions, e.g. -\code{names_wrap = quote(starts_with("your_prefix_"))}.} - -\item{set_deps}{Logical of length 1, whether to refresh the dependencies -of each modified target by scanning the newly generated -target commands for dependencies. If \code{FALSE}, then the target will -keep the original set of dependencies it had before the hook. -Set to \code{NULL} to include all targets supplied to the \code{targets} argument. -\code{TRUE} is recommended for nearly all situations. Only use \code{FALSE} -if you have a specialized use case and you know what you are doing.} - -\item{envir}{Optional environment to construct the quosure for the \code{names} -argument to select names.} -} -\value{ -A flattened list of target objects with the hooks applied. -Even if the input target list had a nested structure, -the return value is a simple list where each element is a target object. -All hook functions remove the nested structure of the input target list. -} -\description{ -In the command of each target, wrap each mention of -each dependency target in an arbitrary R expression. -\code{\link[=tar_hook_inner_raw]{tar_hook_inner_raw()}} is like \code{\link[=tar_hook_inner]{tar_hook_inner()}} except -that the \code{hook}, \code{names}, and \code{names_wrap} arguments are -pre-quoted language objects. -} -\details{ -The expression you supply to \code{hook} -must contain the special placeholder symbol \code{.x} -so \code{tar_hook_inner()} knows where to insert the original command -of the target. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -targets::tar_script({ - targets <- list( - # Nested target lists work with hooks. - list( - targets::tar_target(x1, task1()), - targets::tar_target(x2, task2(x1)) - ), - targets::tar_target(x3, task3(x2, x1)), - targets::tar_target(y1, task4(x3)) - ) - tarchetypes::tar_hook_inner_raw( - targets = targets, - hook = quote(fun(.x)), - names = quote(starts_with("x")) - ) -}) -targets::tar_manifest(fields = command) -}) -} -} -\seealso{ -Other hooks: -\code{\link{tar_hook_before}()}, -\code{\link{tar_hook_before_raw}()}, -\code{\link{tar_hook_inner}()}, -\code{\link{tar_hook_outer}()}, -\code{\link{tar_hook_outer_raw}()} -} -\concept{hooks} diff --git a/man/tar_hook_outer.Rd b/man/tar_hook_outer.Rd index c6e2ff6..5bedceb 100644 --- a/man/tar_hook_outer.Rd +++ b/man/tar_hook_outer.Rd @@ -23,15 +23,21 @@ All hook functions remove the nested structure of the input target list.} The hook must contain the special placeholder symbol \code{.x} so \code{tar_hook_outer()} knows where to insert the original command of the target. -The hook code is quoted (not evaluated) so there is no need -to wrap it in \code{quote()}, \code{expression()}, or similar.} + +\code{tar_hook_outer()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_outer_raw()} expects +evaluated expression objects.} \item{names}{Name of targets in the target list -to apply the hook. Supplied with \code{tidyselect} helpers like +to apply the hook. Supplied using \code{tidyselect} helpers like \code{\link[=starts_with]{starts_with()}}, as in \code{names = starts_with("your_prefix_")}. Set to \code{NULL} to include all targets supplied to the \code{targets} argument. Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} +but they are not modified because the hook does not apply to them. + +The regular hook functions expects unevaluated expressions for the \code{hook} +and \code{names} arguments, whereas the \code{"_raw"} versions expect +evaluated expression objects.} \item{set_deps}{Logical of length 1, whether to refresh the dependencies of each modified target by scanning the newly generated @@ -52,6 +58,9 @@ All hook functions remove the nested structure of the input target list. } \description{ Wrap the command of each target in an arbitrary R expression. +\code{tar_hook_outer()} expects unevaluated expressions for the \code{hook} and +\code{names} arguments, whereas \code{tar_hook_outer_raw()} expects +evaluated expression objects. } \details{ The expression you supply to \code{hook} @@ -98,15 +107,30 @@ targets::tar_script({ ) }) targets::tar_manifest(fields = command) +# Using tar_hook_outer_raw(): +targets::tar_script({ + targets <- list( + # Nested target lists work with hooks. + list( + targets::tar_target(x1, task1()), + targets::tar_target(x2, task2(x1)) + ), + targets::tar_target(x3, task3(x2)), + targets::tar_target(y1, task4(x3)) + ) + tarchetypes::tar_hook_outer_raw( + targets = targets, + hook = quote(postprocess(.x, arg = "value")), + names = quote(starts_with("x")) + ) +}) }) } } \seealso{ Other hooks: \code{\link{tar_hook_before}()}, -\code{\link{tar_hook_before_raw}()}, \code{\link{tar_hook_inner}()}, -\code{\link{tar_hook_inner_raw}()}, \code{\link{tar_hook_outer_raw}()} } \concept{hooks} diff --git a/man/tar_hook_outer_raw.Rd b/man/tar_hook_outer_raw.Rd index 3502438..e514bcf 100644 --- a/man/tar_hook_outer_raw.Rd +++ b/man/tar_hook_outer_raw.Rd @@ -27,11 +27,15 @@ The hook code is quoted (not evaluated) so there is no need to wrap it in \code{quote()}, \code{expression()}, or similar.} \item{names}{Name of targets in the target list -to apply the hook. Supplied with \code{tidyselect} helpers like +to apply the hook. Supplied using \code{tidyselect} helpers like \code{\link[=starts_with]{starts_with()}}, as in \code{names = starts_with("your_prefix_")}. Set to \code{NULL} to include all targets supplied to the \code{targets} argument. Targets not included in \code{names} still remain in the target list, -but they are not modified because the hook does not apply to them.} +but they are not modified because the hook does not apply to them. + +The regular hook functions expects unevaluated expressions for the \code{hook} +and \code{names} arguments, whereas the \code{"_raw"} versions expect +evaluated expression objects.} \item{set_deps}{Logical of length 1, whether to refresh the dependencies of each modified target by scanning the newly generated @@ -106,9 +110,7 @@ targets::tar_manifest(fields = command) \seealso{ Other hooks: \code{\link{tar_hook_before}()}, -\code{\link{tar_hook_before_raw}()}, \code{\link{tar_hook_inner}()}, -\code{\link{tar_hook_inner_raw}()}, \code{\link{tar_hook_outer}()} } \concept{hooks} diff --git a/man/tar_knit.Rd b/man/tar_knit.Rd index 2f2f889..e8ae7d8 100644 --- a/man/tar_knit.Rd +++ b/man/tar_knit.Rd @@ -285,12 +285,8 @@ targets::tar_make() \seealso{ Other Literate programming targets: \code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, \code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, \code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} +\code{\link{tar_render_rep}()} } \concept{Literate programming targets} diff --git a/man/tar_map2.Rd b/man/tar_map2.Rd index 659c44b..b9f596d 100644 --- a/man/tar_map2.Rd +++ b/man/tar_map2.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2.R +% Please edit documentation in R/tar_map2.R, R/tar_map2_raw.R \name{tar_map2} \alias{tar_map2} +\alias{tar_map2_raw} \title{Batched dynamic-within-static branching for data frames.} \usage{ tar_map2( @@ -35,15 +36,61 @@ tar_map2( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_map2_raw( + name, + command1, + command2, + values = NULL, + names = NULL, + descriptions = quote(tidyselect::everything()), + group = quote(rep(1L, nrow(as.data.frame(!!.x)))), + combine = TRUE, + columns1 = quote(tidyselect::everything()), + columns2 = quote(tidyselect::everything()), + suffix1 = "1", + suffix2 = "2", + rep_workers = 1, + delimiter = "_", + 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"), + 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{ -\item{name}{Symbol, base name of the targets.} +\item{name}{Base name of the targets. +In regular \code{tarchetypes} functions, +the \code{name} argument is an unevaluated symbol. +In the \code{"_raw"} versions +of functions, \code{name} is a character string.} \item{command1}{R code to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} +Must return a data frame with one row per call to \code{command2} when run. + +In regular \code{tarchetypes} functions, +the \code{command1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command1} is an evaluated expression object.} \item{command2}{R code to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} +produced by \code{command1}. Must return a data frame. + +In regular \code{tarchetypes} functions, +the \code{command2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command2} is an evaluated expression object.} \item{values}{Named list or data frame with values to iterate over. The names are the names of symbols in the commands and pattern @@ -67,10 +114,6 @@ to append to the custom description of each generated target. The value of \code{descriptions} should be a \code{tidyselect} expression such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} -\item{group}{Function on the data produced by \code{command1} to create the -\code{tar_group} column that determines the batching structure for the -\code{command2} targets.} - \item{combine}{Logical of length 1, whether to statically combine all the results into a single target downstream.} @@ -84,12 +127,23 @@ them from the \code{command1} targets.} \item{columns1}{A tidyselect expression to select which columns of \code{values} to append to the output of all targets. -Columns already in the target output are not appended.} +Columns already in the target output are not appended. + +In regular \code{tarchetypes} functions, +the \code{columns1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns1} is an evaluated expression object.} -\item{columns2}{A tidyselect expression to select which columns of \code{command1} +\item{columns2}{A tidyselect expression to select which columns of +\code{command1} output to append to \code{command2} output. Columns already in the target output are not appended. -\code{columns1} takes precedence over \code{columns2}.} +\code{columns1} takes precedence over \code{columns2}. + +In regular \code{tarchetypes} functions, +the \code{columns2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns2} is an evaluated expression object.} \item{rep_workers}{Positive integer of length 1, number of local R processes to use to run reps within batches in parallel. If 1, @@ -273,16 +327,14 @@ See the "Target objects" section for background. Define targets for batched dynamic-within-static branching for data frames. Not a user-side function. Do not invoke directly. + +\code{\link[=tar_map2]{tar_map2()}} expects unevaluated language for arguments +\code{name}, \code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. +\code{\link[=tar_map2_raw]{tar_map2_raw()}} expects a character string for \code{name} +and an evaluated expression object for each of +\code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. } \details{ -Static branching creates one pair of targets -for each row in \code{values}. In each pair, -there is an upstream non-dynamic target that runs \code{command1} -and a downstream dynamic target that runs \code{command2}. -\code{command1} produces a data frame of arguments to -\code{command2}, and \code{command2} dynamically maps over -these arguments in batches. - Static branching creates one pair of targets for each row in \code{values}. In each pair, there is an upstream non-dynamic target that runs \code{command1} @@ -344,12 +396,8 @@ details the structure and composition of target objects. \seealso{ Other branching: \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()}, diff --git a/man/tar_map2_count.Rd b/man/tar_map2_count.Rd index cb73e45..9d0acd7 100644 --- a/man/tar_map2_count.Rd +++ b/man/tar_map2_count.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2_count.R +% Please edit documentation in R/tar_map2_count.R, R/tar_map2_count_raw.R \name{tar_map2_count} \alias{tar_map2_count} +\alias{tar_map2_count_raw} \title{Dynamic-within-static branching for data frames (count batching).} \usage{ @@ -36,6 +37,38 @@ tar_map2_count( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_map2_count_raw( + name, + command1, + command2, + values = NULL, + names = NULL, + descriptions = quote(tidyselect::everything()), + batches = 1L, + combine = TRUE, + suffix1 = "1", + suffix2 = "2", + columns1 = quote(tidyselect::everything()), + columns2 = quote(tidyselect::everything()), + rep_workers = 1, + delimiter = "_", + 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"), + 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{ \item{name}{Name of the target. @@ -46,10 +79,20 @@ and an evaluated expression object for \code{command} (e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} \item{command1}{R code to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} +Must return a data frame with one row per call to \code{command2} when run. + +In regular \code{tarchetypes} functions, +the \code{command1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command1} is an evaluated expression object.} \item{command2}{R code to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} +produced by \code{command1}. Must return a data frame. + +In regular \code{tarchetypes} functions, +the \code{command2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command2} is an evaluated expression object.} \item{values}{Named list or data frame with values to iterate over. The names are the names of symbols in the commands and pattern @@ -73,8 +116,10 @@ to append to the custom description of each generated target. The value of \code{descriptions} should be a \code{tidyselect} expression such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} -\item{batches}{Number of batches. This is also the number of dynamic -branches created during \code{tar_make()}.} +\item{batches}{Positive integer of length 1, +maximum number of batches (dynamic branches within static branches) +of the downstream (\code{command2}) targets. Batches +are formed from row groups of the \code{command1} target output.} \item{combine}{Logical of length 1, whether to statically combine all the results into a single target downstream.} @@ -89,12 +134,23 @@ them from the \code{command1} targets.} \item{columns1}{A tidyselect expression to select which columns of \code{values} to append to the output of all targets. -Columns already in the target output are not appended.} +Columns already in the target output are not appended. -\item{columns2}{A tidyselect expression to select which columns of \code{command1} +In regular \code{tarchetypes} functions, +the \code{columns1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns1} is an evaluated expression object.} + +\item{columns2}{A tidyselect expression to select which columns of +\code{command1} output to append to \code{command2} output. Columns already in the target output are not appended. -\code{columns1} takes precedence over \code{columns2}.} +\code{columns1} takes precedence over \code{columns2}. + +In regular \code{tarchetypes} functions, +the \code{columns2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns2} is an evaluated expression object.} \item{rep_workers}{Positive integer of length 1, number of local R processes to use to run reps within batches in parallel. If 1, @@ -278,6 +334,12 @@ See the "Target objects" section for background. Define targets for batched dynamic-within-static branching for data frames, where the user sets the (maximum) number of batches. + +\code{\link[=tar_map2_count]{tar_map2_count()}} expects unevaluated language for arguments +\code{name}, \code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. +\code{\link[=tar_map2_count_raw]{tar_map2_count_raw()}} expects a character string for \code{name} +and an evaluated expression object for each of +\code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. } \details{ Static branching creates one pair of targets @@ -359,18 +421,35 @@ targets::tar_script({ }) targets::tar_make() targets::tar_read(x) +# With tar_map2_count_raw(): +targets::tar_script({ + tarchetypes::tar_map2_count_raw( + name = "x", + command1 = quote( + tibble::tibble( + arg1 = arg1, + arg2 = seq_len(6) + ) + ), + command2 = quote( + tibble::tibble( + result = paste(arg1, arg2), + random = sample.int(1e9, size = 1), + length_input = length(arg1) + ) + ), + values = tibble::tibble(arg1 = letters[seq_len(2)]), + batches = 3 + ) +}) }) } } \seealso{ Other branching: \code{\link{tar_map2}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()}, diff --git a/man/tar_map2_count_raw.Rd b/man/tar_map2_count_raw.Rd deleted file mode 100644 index 27c016e..0000000 --- a/man/tar_map2_count_raw.Rd +++ /dev/null @@ -1,388 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2_count_raw.R -\name{tar_map2_count_raw} -\alias{tar_map2_count_raw} -\title{Dynamic-within-static branching for data frames -(count batching; raw version).} -\usage{ -tar_map2_count_raw( - name, - command1, - command2, - values = NULL, - names = NULL, - descriptions = quote(tidyselect::everything()), - batches = 1L, - combine = TRUE, - suffix1 = "1", - suffix2 = "2", - columns1 = quote(tidyselect::everything()), - columns2 = quote(tidyselect::everything()), - rep_workers = 1, - delimiter = "_", - 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"), - 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{ -\item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} - -\item{command1}{Language object to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} - -\item{command2}{Language object to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} - -\item{values}{Named list or data frame with values to iterate over. -The names are the names of symbols in the commands and pattern -statements, and the elements are values that get substituted -in place of those symbols. \code{\link[=tar_map]{tar_map()}} uses these elements -to create new R code, so they should be basic types, symbols, -or R expressions. For objects even a little bit complicated, -especially objects with attributes, it is not obvious how to -convert the object into code that generates it. -For complicated objects, consider using \code{quote()} when -you define \code{values}, as shown at -\url{https://github.com/ropensci/tarchetypes/discussions/105}.} - -\item{names}{Subset of \code{names(values)} -used to generate the suffixes in the names of the new targets. -The value of \code{names} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{descriptions}{Names of a column in \code{values} -to append to the custom description of each generated target. -The value of \code{descriptions} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{batches}{Positive integer of length 1, -maximum number of batches (dynamic branches within static branches) -of the downstream (\code{command2}) targets. Batches -are formed from row groups of the \code{command1} target output.} - -\item{combine}{Logical of length 1, whether to statically combine -all the results into a single target downstream.} - -\item{suffix1}{Character of length 1, -suffix to apply to the \code{command1} targets to distinguish -them from the \code{command2} targets.} - -\item{suffix2}{Character of length 1, -suffix to apply to the \code{command2} targets to distinguish -them from the \code{command1} targets.} - -\item{columns1}{Language object, a tidyselect expression -to select which columns of \code{values} -to append to the output of all targets.} - -\item{columns2}{Language object, a tidyselect expression -to select which columns of \code{command1} -output to append to \code{command2} output. -In case of conflicts, \code{column1} takes precedence.} - -\item{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.} - -\item{delimiter}{Character of length 1, string to insert between -other strings when creating names of targets.} - -\item{tidy_eval}{Whether to invoke tidy evaluation -(e.g. the \verb{!!} operator from \code{rlang}) as soon as the target is defined -(before \code{tar_make()}). Applies to the \code{command} argument.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Optional storage format for the target's return value. -With the exception of \code{format = "file"}, each target -gets a file in \verb{_targets/objects}, and each format is a different -way to save and load this file. See the "Storage formats" section -for a detailed list of possible data storage formats.} - -\item{repository}{Character of length 1, remote repository for target -storage. Choices: -\itemize{ -\item \code{"local"}: file system of the local machine. -\item \code{"aws"}: Amazon Web Services (AWS) S3 bucket. Can be configured -with a non-AWS S3 bucket using the \code{endpoint} argument of -\code{\link[targets:tar_resources_aws]{tar_resources_aws()}}, but versioning capabilities may be lost -in doing so. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item \code{"gcp"}: Google Cloud Platform storage bucket. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item A character string from \code{\link[targets:tar_repository_cas]{tar_repository_cas()}} for content-addressable -storage. -} - -Note: if \code{repository} is not \code{"local"} and \code{format} is \code{"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.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{storage}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's return value is sent back to the -host machine and saved/uploaded locally. -\item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. -}} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A list of new target objects. -See the "Target objects" section for background. -} -\description{ -Define targets for batched -dynamic-within-static branching for data frames, -where the user sets the (maximum) number of batches. -Like \code{tar_map2_count()} except \code{name} is a character string -and \code{command1}, \code{command2}, \code{names}, \code{columns1}, and \code{columns2} -are all language objects. -} -\details{ -Static branching creates one pair of targets -for each row in \code{values}. In each pair, -there is an upstream non-dynamic target that runs \code{command1} -and a downstream dynamic target that runs \code{command2}. -\code{command1} produces a data frame of arguments to -\code{command2}, and \code{command2} dynamically maps over -these arguments in batches. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -targets::tar_script({ - tarchetypes::tar_map2_count_raw( - "x", - command1 = quote( - tibble::tibble( - arg1 = arg1, - arg2 = seq_len(6) - ) - ), - command2 = quote( - tibble::tibble( - result = paste(arg1, arg2), - random = sample.int(1e6, size = 1), - length_input = length(arg1) - ) - ), - values = tibble::tibble(arg1 = letters[seq_len(2)]), - batches = 3 - ) -}) -targets::tar_make() -targets::tar_read(x) -}) -} -} -\seealso{ -Other branching: -\code{\link{tar_map2}()}, -\code{\link{tar_map2_count}()}, -\code{\link{tar_map2_raw}()}, -\code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, -\code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, -\code{\link{tar_rep}()}, -\code{\link{tar_rep2}()}, -\code{\link{tar_rep_map}()}, -\code{\link{tar_rep_map_raw}()} -} -\concept{branching} diff --git a/man/tar_map2_raw.Rd b/man/tar_map2_raw.Rd deleted file mode 100644 index 1a5015a..0000000 --- a/man/tar_map2_raw.Rd +++ /dev/null @@ -1,347 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2_raw.R -\name{tar_map2_raw} -\alias{tar_map2_raw} -\title{Batched dynamic-within-static branching for data frames (raw version).} -\usage{ -tar_map2_raw( - name, - command1, - command2, - values = NULL, - names = NULL, - descriptions = quote(tidyselect::everything()), - group = quote(rep(1L, nrow(as.data.frame(!!.x)))), - combine = TRUE, - columns1 = quote(tidyselect::everything()), - columns2 = quote(tidyselect::everything()), - suffix1 = "1", - suffix2 = "2", - rep_workers = 1, - delimiter = "_", - 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"), - 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{ -\item{name}{Character of length 1, base name of the targets.} - -\item{command1}{Language object to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} - -\item{command2}{Language object to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} - -\item{values}{Named list or data frame with values to iterate over. -The names are the names of symbols in the commands and pattern -statements, and the elements are values that get substituted -in place of those symbols. \code{\link[=tar_map]{tar_map()}} uses these elements -to create new R code, so they should be basic types, symbols, -or R expressions. For objects even a little bit complicated, -especially objects with attributes, it is not obvious how to -convert the object into code that generates it. -For complicated objects, consider using \code{quote()} when -you define \code{values}, as shown at -\url{https://github.com/ropensci/tarchetypes/discussions/105}.} - -\item{names}{Subset of \code{names(values)} -used to generate the suffixes in the names of the new targets. -The value of \code{names} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{descriptions}{Names of a column in \code{values} -to append to the custom description of each generated target. -The value of \code{descriptions} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{group}{Function on the data produced by \code{command1} to create the -\code{tar_group} column that determines the batching structure for the -\code{command2} targets.} - -\item{combine}{Logical of length 1, whether to statically combine -all the results into a single target downstream.} - -\item{columns1}{Language object, a tidyselect expression -to select which columns of \code{values} -to append to the output of all targets.} - -\item{columns2}{Language object, a tidyselect expression -to select which columns of \code{command1} -output to append to \code{command2} output. -In case of conflicts, \code{column1} takes precedence.} - -\item{suffix1}{Character of length 1, -suffix to apply to the \code{command1} targets to distinguish -them from the \code{command2} targets.} - -\item{suffix2}{Character of length 1, -suffix to apply to the \code{command2} targets to distinguish -them from the \code{command1} targets.} - -\item{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.} - -\item{delimiter}{Character of length 1, string to insert between -other strings when creating names of targets.} - -\item{tidy_eval}{Whether to invoke tidy evaluation -(e.g. the \verb{!!} operator from \code{rlang}) as soon as the target is defined -(before \code{tar_make()}). Applies to the \code{command} argument.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Optional storage format for the target's return value. -With the exception of \code{format = "file"}, each target -gets a file in \verb{_targets/objects}, and each format is a different -way to save and load this file. See the "Storage formats" section -for a detailed list of possible data storage formats.} - -\item{repository}{Character of length 1, remote repository for target -storage. Choices: -\itemize{ -\item \code{"local"}: file system of the local machine. -\item \code{"aws"}: Amazon Web Services (AWS) S3 bucket. Can be configured -with a non-AWS S3 bucket using the \code{endpoint} argument of -\code{\link[targets:tar_resources_aws]{tar_resources_aws()}}, but versioning capabilities may be lost -in doing so. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item \code{"gcp"}: Google Cloud Platform storage bucket. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item A character string from \code{\link[targets:tar_repository_cas]{tar_repository_cas()}} for content-addressable -storage. -} - -Note: if \code{repository} is not \code{"local"} and \code{format} is \code{"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.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{storage}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's return value is sent back to the -host machine and saved/uploaded locally. -\item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. -}} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A list of new target objects. -See the "Target objects" section for background. -} -\description{ -Define targets for batched -dynamic-within-static branching for data frames (raw version). -Not a user-side function. Do not invoke directly. -} -\details{ -Like \code{tar_map2()} except \code{name} is a character string -and \code{command1}, \code{command2}, \code{group}, \code{names}, \code{columns1}, and \code{columns2} -are language objects. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\seealso{ -Other branching: -\code{\link{tar_map2}()}, -\code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, -\code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, -\code{\link{tar_rep}()}, -\code{\link{tar_rep2}()}, -\code{\link{tar_rep_map}()}, -\code{\link{tar_rep_map_raw}()} -} -\concept{branching} -\keyword{internal} diff --git a/man/tar_map2_size.Rd b/man/tar_map2_size.Rd index 3d91e8c..8bfe52e 100644 --- a/man/tar_map2_size.Rd +++ b/man/tar_map2_size.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2_size.R +% Please edit documentation in R/tar_map2_size.R, R/tar_map2_size_raw.R \name{tar_map2_size} \alias{tar_map2_size} +\alias{tar_map2_size_raw} \title{Dynamic-within-static branching for data frames (size batching).} \usage{ @@ -36,6 +37,38 @@ tar_map2_size( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_map2_size_raw( + name, + command1, + command2, + values = NULL, + names = NULL, + descriptions = quote(tidyselect::everything()), + size = Inf, + combine = TRUE, + suffix1 = "1", + suffix2 = "2", + columns1 = quote(tidyselect::everything()), + columns2 = quote(tidyselect::everything()), + rep_workers = 1, + delimiter = "_", + 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"), + 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{ \item{name}{Name of the target. @@ -46,10 +79,20 @@ and an evaluated expression object for \code{command} (e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} \item{command1}{R code to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} +Must return a data frame with one row per call to \code{command2} when run. + +In regular \code{tarchetypes} functions, +the \code{command1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command1} is an evaluated expression object.} \item{command2}{R code to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} +produced by \code{command1}. Must return a data frame. + +In regular \code{tarchetypes} functions, +the \code{command2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{command2} is an evaluated expression object.} \item{values}{Named list or data frame with values to iterate over. The names are the names of symbols in the commands and pattern @@ -91,12 +134,23 @@ them from the \code{command1} targets.} \item{columns1}{A tidyselect expression to select which columns of \code{values} to append to the output of all targets. -Columns already in the target output are not appended.} +Columns already in the target output are not appended. -\item{columns2}{A tidyselect expression to select which columns of \code{command1} +In regular \code{tarchetypes} functions, +the \code{columns1} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns1} is an evaluated expression object.} + +\item{columns2}{A tidyselect expression to select which columns of +\code{command1} output to append to \code{command2} output. Columns already in the target output are not appended. -\code{columns1} takes precedence over \code{columns2}.} +\code{columns1} takes precedence over \code{columns2}. + +In regular \code{tarchetypes} functions, +the \code{columns2} argument is an unevaluated expression. +In the \code{"_raw"} versions +of functions, \code{columns2} is an evaluated expression object.} \item{rep_workers}{Positive integer of length 1, number of local R processes to use to run reps within batches in parallel. If 1, @@ -280,6 +334,12 @@ See the "Target objects" section for background. Define targets for batched dynamic-within-static branching for data frames, where the user sets the (maximum) size of each batch. + +\code{\link[=tar_map2_size]{tar_map2_size()}} expects unevaluated language for arguments +\code{name}, \code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. +\code{\link[=tar_map2_size_raw]{tar_map2_size_raw()}} expects a character string for \code{name} +and an evaluated expression object for each of +\code{command1}, \code{command2}, \code{columns1}, and \code{columns2}. } \details{ Static branching creates one pair of targets @@ -361,6 +421,27 @@ targets::tar_script({ }) targets::tar_make() targets::tar_read(x) +# With tar_map2_size_raw(): +targets::tar_script({ + tarchetypes::tar_map2_size_raw( + name = "x", + command1 = quote( + tibble::tibble( + arg1 = arg1, + arg2 = seq_len(6) + ) + ), + command2 = quote( + tibble::tibble( + result = paste(arg1, arg2), + random = sample.int(1e9, size = 1), + length_input = length(arg1) + ) + ), + values = tibble::tibble(arg1 = letters[seq_len(2)]), + size = 2 + ) +}) }) } } @@ -368,11 +449,7 @@ targets::tar_read(x) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()}, diff --git a/man/tar_map2_size_raw.Rd b/man/tar_map2_size_raw.Rd deleted file mode 100644 index 0fa32f6..0000000 --- a/man/tar_map2_size_raw.Rd +++ /dev/null @@ -1,388 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map2_size_raw.R -\name{tar_map2_size_raw} -\alias{tar_map2_size_raw} -\title{Dynamic-within-static branching for data frames -(size batching; raw version).} -\usage{ -tar_map2_size_raw( - name, - command1, - command2, - values = NULL, - names = NULL, - descriptions = quote(tidyselect::everything()), - size = Inf, - combine = TRUE, - suffix1 = "1", - suffix2 = "2", - columns1 = quote(tidyselect::everything()), - columns2 = quote(tidyselect::everything()), - rep_workers = 1, - delimiter = "_", - 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"), - 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{ -\item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} - -\item{command1}{Language object to create named arguments to \code{command2}. -Must return a data frame with one row per call to \code{command2}.} - -\item{command2}{Language object to map over the data frame of arguments -produced by \code{command1}. Must return a data frame.} - -\item{values}{Named list or data frame with values to iterate over. -The names are the names of symbols in the commands and pattern -statements, and the elements are values that get substituted -in place of those symbols. \code{\link[=tar_map]{tar_map()}} uses these elements -to create new R code, so they should be basic types, symbols, -or R expressions. For objects even a little bit complicated, -especially objects with attributes, it is not obvious how to -convert the object into code that generates it. -For complicated objects, consider using \code{quote()} when -you define \code{values}, as shown at -\url{https://github.com/ropensci/tarchetypes/discussions/105}.} - -\item{names}{Subset of \code{names(values)} -used to generate the suffixes in the names of the new targets. -The value of \code{names} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{descriptions}{Names of a column in \code{values} -to append to the custom description of each generated target. -The value of \code{descriptions} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{size}{Positive integer of length 1, -maximum number of rows in each batch for -the downstream (\code{command2}) targets. Batches -are formed from row groups of the \code{command1} target output.} - -\item{combine}{Logical of length 1, whether to statically combine -all the results into a single target downstream.} - -\item{suffix1}{Character of length 1, -suffix to apply to the \code{command1} targets to distinguish -them from the \code{command2} targets.} - -\item{suffix2}{Character of length 1, -suffix to apply to the \code{command2} targets to distinguish -them from the \code{command1} targets.} - -\item{columns1}{Language object, a tidyselect expression -to select which columns of \code{values} -to append to the output of all targets.} - -\item{columns2}{Language object, a tidyselect expression -to select which columns of \code{command1} -output to append to \code{command2} output. -In case of conflicts, \code{column1} takes precedence.} - -\item{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.} - -\item{delimiter}{Character of length 1, string to insert between -other strings when creating names of targets.} - -\item{tidy_eval}{Whether to invoke tidy evaluation -(e.g. the \verb{!!} operator from \code{rlang}) as soon as the target is defined -(before \code{tar_make()}). Applies to the \code{command} argument.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Optional storage format for the target's return value. -With the exception of \code{format = "file"}, each target -gets a file in \verb{_targets/objects}, and each format is a different -way to save and load this file. See the "Storage formats" section -for a detailed list of possible data storage formats.} - -\item{repository}{Character of length 1, remote repository for target -storage. Choices: -\itemize{ -\item \code{"local"}: file system of the local machine. -\item \code{"aws"}: Amazon Web Services (AWS) S3 bucket. Can be configured -with a non-AWS S3 bucket using the \code{endpoint} argument of -\code{\link[targets:tar_resources_aws]{tar_resources_aws()}}, but versioning capabilities may be lost -in doing so. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item \code{"gcp"}: Google Cloud Platform storage bucket. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item A character string from \code{\link[targets:tar_repository_cas]{tar_repository_cas()}} for content-addressable -storage. -} - -Note: if \code{repository} is not \code{"local"} and \code{format} is \code{"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.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{storage}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's return value is sent back to the -host machine and saved/uploaded locally. -\item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. -}} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A list of new target objects. -See the "Target objects" section for background. -} -\description{ -Define targets for batched -dynamic-within-static branching for data frames, -where the user sets the (maximum) size of each batch. -Like \code{tar_map2_size()} except \code{name} is a character string -and \code{command1}, \code{command2}, \code{names}, \code{columns1}, and \code{columns2} -are all language objects. -} -\details{ -Static branching creates one pair of targets -for each row in \code{values}. In each pair, -there is an upstream non-dynamic target that runs \code{command1} -and a downstream dynamic target that runs \code{command2}. -\code{command1} produces a data frame of arguments to -\code{command2}, and \code{command2} dynamically maps over -these arguments in batches. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -targets::tar_script({ - tarchetypes::tar_map2_size_raw( - "x", - command1 = quote( - tibble::tibble( - arg1 = arg1, - arg2 = seq_len(6) - ) - ), - command2 = quote( - tibble::tibble( - result = paste(arg1, arg2), - random = sample.int(1e6, size = 1), - length_input = length(arg1) - ) - ), - values = tibble::tibble(arg1 = letters[seq_len(2)]), - size = 2 - ) -}) -targets::tar_make() -targets::tar_read(x) -}) -} -} -\seealso{ -Other branching: -\code{\link{tar_map2}()}, -\code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, -\code{\link{tar_map2_size}()}, -\code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, -\code{\link{tar_rep}()}, -\code{\link{tar_rep2}()}, -\code{\link{tar_rep_map}()}, -\code{\link{tar_rep_map_raw}()} -} -\concept{branching} diff --git a/man/tar_map_rep.Rd b/man/tar_map_rep.Rd index c760e03..f313405 100644 --- a/man/tar_map_rep.Rd +++ b/man/tar_map_rep.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map_rep.R +% Please edit documentation in R/tar_map_rep.R, R/tar_map_rep_raw.R \name{tar_map_rep} \alias{tar_map_rep} +\alias{tar_map_rep_raw} \title{Dynamic batched replication within static branches for data frames.} \usage{ @@ -33,17 +34,46 @@ tar_map_rep( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_map_rep_raw( + name, + command, + values = NULL, + names = NULL, + descriptions = quote(tidyselect::everything()), + columns = quote(tidyselect::everything()), + batches = 1, + reps = 1, + rep_workers = 1, + combine = TRUE, + delimiter = "_", + 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"), + 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{ \item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} +\code{\link[=tar_map_rep]{tar_map_rep()}} expects an unevaluated symbol for the \code{name} argument, +whereas \code{\link[=tar_map_rep_raw]{tar_map_rep_raw()}} expects a character string for \code{name}.} \item{command}{R code for a single replicate. Must return -a data frame.} +a data frame when run. +\code{\link[=tar_map_rep]{tar_map_rep()}} expects an unevaluated expression for \code{command}, +whereas \code{\link[=tar_map_rep_raw]{tar_map_rep_raw()}} expects +an evaluated expression object for \code{command}.} \item{values}{Named list or data frame with values to iterate over. The names are the names of symbols in the commands and pattern @@ -57,10 +87,10 @@ For complicated objects, consider using \code{quote()} when you define \code{values}, as shown at \url{https://github.com/ropensci/tarchetypes/discussions/105}.} -\item{names}{Language object with a tidyselect expression -to select which columns of \code{values} to use to construct -statically branched target names. If \code{NULL}, then -short names are automatically generated.} +\item{names}{Subset of \code{names(values)} +used to generate the suffixes in the names of the new targets. +The value of \code{names} should be a \code{tidyselect} expression +such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} \item{descriptions}{Names of a column in \code{values} to append to the custom description of each generated target. @@ -260,7 +290,12 @@ See the "Target objects" section for background. } \description{ Define targets for batched replication -within static branches for data frames. +within static branches for data frames. + +\code{\link[=tar_map_rep]{tar_map_rep()}} expects an unevaluated symbol for the \code{name} argument +and an unevaluated expression for \code{command}, +whereas \code{\link[=tar_map_rep_raw]{tar_map_rep_raw()}} expects a character string for \code{name} +and an evaluated expression object for \code{command}. } \section{Target objects}{ @@ -316,6 +351,7 @@ Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{exec if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { targets::tar_dir({ # tar_dir() runs code from a temporary directory. targets::tar_script({ + library(tarchetypes) # Just a sketch of a Bayesian sensitivity analysis of hyperparameters: assess_hyperparameters <- function(sigma1, sigma2) { # data <- simulate_random_data() # user-defined function @@ -333,14 +369,24 @@ targets::tar_script({ sigma1 = c(10, 50, 50), sigma2 = c(10, 5, 10) ) - tarchetypes::tar_map_rep( - sensitivity_analysis, - command = assess_hyperparameters(sigma1, sigma2), - values = hyperparameters, - names = tidyselect::any_of("scenario"), - batches = 2, - reps = 3 - ) + list( + tar_map_rep( + name = sensitivity_analysis, + command = assess_hyperparameters(sigma1, sigma2), + values = hyperparameters, + names = tidyselect::any_of("scenario"), + batches = 2, + reps = 3 + ), + tar_map_rep_raw( + name = "sensitivity_analysis2", + command = quote(assess_hyperparameters(sigma1, sigma2)), + values = hyperparameters, + names = tidyselect::any_of("scenario"), + batches = 2, + reps = 3 + ) + ) }) targets::tar_make() targets::tar_read(sensitivity_analysis) @@ -351,11 +397,7 @@ targets::tar_read(sensitivity_analysis) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()}, diff --git a/man/tar_map_rep_raw.Rd b/man/tar_map_rep_raw.Rd deleted file mode 100644 index 1247b31..0000000 --- a/man/tar_map_rep_raw.Rd +++ /dev/null @@ -1,369 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_map_rep_raw.R -\name{tar_map_rep_raw} -\alias{tar_map_rep_raw} -\title{Dynamic batched replication within static branches -for data frames (raw version).} -\usage{ -tar_map_rep_raw( - name, - command, - values = NULL, - names = NULL, - descriptions = quote(tidyselect::everything()), - columns = quote(tidyselect::everything()), - batches = 1, - reps = 1, - rep_workers = 1, - combine = TRUE, - delimiter = "_", - 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"), - 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{ -\item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} - -\item{command}{Language object, R code for a single replicate. Must return -a data frame.} - -\item{values}{Named list or data frame with values to iterate over. -The names are the names of symbols in the commands and pattern -statements, and the elements are values that get substituted -in place of those symbols. \code{\link[=tar_map]{tar_map()}} uses these elements -to create new R code, so they should be basic types, symbols, -or R expressions. For objects even a little bit complicated, -especially objects with attributes, it is not obvious how to -convert the object into code that generates it. -For complicated objects, consider using \code{quote()} when -you define \code{values}, as shown at -\url{https://github.com/ropensci/tarchetypes/discussions/105}.} - -\item{names}{Language object with a tidyselect expression -to select which columns of \code{values} to use to construct -statically branched target names. If \code{NULL}, then -short names are automatically generated.} - -\item{descriptions}{Names of a column in \code{values} -to append to the custom description of each generated target. -The value of \code{descriptions} should be a \code{tidyselect} expression -such as a call to \code{\link[=any_of]{any_of()}} or \code{\link[=starts_with]{starts_with()}}.} - -\item{columns}{Language object with a tidyselect expression -to select which columns of \code{values} to append to the output. -Columns already in the target output are not appended.} - -\item{batches}{Number of batches. This is also the number of dynamic -branches created during \code{tar_make()}.} - -\item{reps}{Number of replications in each batch. The total number -of replications is \code{batches * reps}.} - -\item{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.} - -\item{combine}{Logical of length 1, whether to statically combine -all the results into a single target downstream.} - -\item{delimiter}{Character of length 1, string to insert between -other strings when creating names of targets.} - -\item{tidy_eval}{Whether to invoke tidy evaluation -(e.g. the \verb{!!} operator from \code{rlang}) as soon as the target is defined -(before \code{tar_make()}). Applies to the \code{command} argument.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Character of length 1, storage format of the output. -An efficient data frame format like \code{"feather"} is recommended, -but the default is \code{"rds"} to avoid incurring extra package -dependencies. See the help file of \code{targets::tar_target()} -for details on storage formats.} - -\item{repository}{Character of length 1, remote repository for target -storage. Choices: -\itemize{ -\item \code{"local"}: file system of the local machine. -\item \code{"aws"}: Amazon Web Services (AWS) S3 bucket. Can be configured -with a non-AWS S3 bucket using the \code{endpoint} argument of -\code{\link[targets:tar_resources_aws]{tar_resources_aws()}}, but versioning capabilities may be lost -in doing so. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item \code{"gcp"}: Google Cloud Platform storage bucket. -See the cloud storage section of -\url{https://books.ropensci.org/targets/data.html} -for details for instructions. -\item A character string from \code{\link[targets:tar_repository_cas]{tar_repository_cas()}} for content-addressable -storage. -} - -Note: if \code{repository} is not \code{"local"} and \code{format} is \code{"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.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{storage}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's return value is sent back to the -host machine and saved/uploaded locally. -\item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. -}} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A list of new target objects. -See the "Target objects" section for background. -} -\description{ -Define targets for batched replication -within static branches for data frames (raw version). - -This function is like \code{\link[=tar_map_rep]{tar_map_rep()}} -except the \code{name} argument is a character string -and the \code{names} and \code{columns} arguments are -language objects. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -targets::tar_script({ - # Just a sketch of a Bayesian sensitivity analysis of hyperparameters: - assess_hyperparameters <- function(sigma1, sigma2) { - # data <- simulate_random_data() # user-defined function - # run_model(data, sigma1, sigma2) # user-defined function - # Mock output from the model: - posterior_samples <- stats::rnorm(1000, 0, sigma1 + sigma2) - tibble::tibble( - posterior_median = median(posterior_samples), - posterior_quantile_0.025 = quantile(posterior_samples, 0.025), - posterior_quantile_0.975 = quantile(posterior_samples, 0.975) - ) - } - hyperparameters <- tibble::tibble( - scenario = c("tight", "medium", "diffuse"), - sigma1 = c(10, 50, 50), - sigma2 = c(10, 5, 10) - ) - tarchetypes::tar_map_rep_raw( - "sensitivity_analysis", - command = quote(assess_hyperparameters(sigma1, sigma2)), - values = hyperparameters, - names = quote(tidyselect::any_of("scenario")), - batches = 2, - reps = 3 - ) -}) -targets::tar_make() -targets::tar_read(sensitivity_analysis) -}) -} -} -\seealso{ -Other branching: -\code{\link{tar_map2}()}, -\code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, -\code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, -\code{\link{tar_map_rep}()}, -\code{\link{tar_rep}()}, -\code{\link{tar_rep2}()}, -\code{\link{tar_rep_map}()}, -\code{\link{tar_rep_map_raw}()} -} -\concept{branching} diff --git a/man/tar_quarto.Rd b/man/tar_quarto.Rd index e761fc9..238b7f5 100644 --- a/man/tar_quarto.Rd +++ b/man/tar_quarto.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_quarto.R +% Please edit documentation in R/tar_quarto.R, R/tar_quarto_raw.R \name{tar_quarto} \alias{tar_quarto} +\alias{tar_quarto_raw} \title{Target with a Quarto project.} \usage{ tar_quarto( @@ -31,34 +32,41 @@ tar_quarto( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_quarto_raw( + name, + path = ".", + working_directory = NULL, + extra_files = character(0), + execute = TRUE, + execute_params = NULL, + cache = NULL, + cache_refresh = FALSE, + debug = FALSE, + quiet = TRUE, + quarto_args = NULL, + pandoc_args = NULL, + profile = NULL, + packages = NULL, + library = NULL, + error = targets::tar_option_get("error"), + memory = targets::tar_option_get("memory"), + garbage_collection = targets::tar_option_get("garbage_collection"), + deployment = "main", + priority = targets::tar_option_get("priority"), + resources = targets::tar_option_get("resources"), + retrieval = targets::tar_option_get("retrieval"), + cue = targets::tar_option_get("cue"), + description = targets::tar_option_get("description") +) } \arguments{ -\item{name}{Symbol, name of the target. -In \code{\link[targets:tar_target]{tar_target()}}, \code{name} is an unevaluated symbol, e.g. -\code{tar_target(name = data)}. -In \code{\link[targets:tar_target_raw]{tar_target_raw()}}, \code{name} is a character string, e.g. -\code{tar_target_raw(name = "data")}. - -A target name must be a valid name for a symbol in R, and it -must not start with a dot. Subsequent targets -can refer to this name symbolically to induce a dependency relationship: -e.g. \code{tar_target(downstream_target, f(upstream_target))} is a -target named \code{downstream_target} which depends on a target -\code{upstream_target} and a function \code{f()}. In addition, a target's -name determines its random number generator seed. In this way, -each target runs with a reproducible seed so someone else -running the same pipeline should get the same results, -and no two targets in the same pipeline share the same seed. -(Even dynamic branches have different names and thus different seeds.) -You can recover the seed of a completed target -with \code{tar_meta(your_target, seed)} and run \code{\link[targets:tar_seed_set]{tar_seed_set()}} -on the result to locally recreate the target's initial RNG state.} - -\item{path}{Character of length 1, -either the single \verb{*.qmd} source file to be rendered -or a directory containing a Quarto project. -Defaults to the working directory of the \code{targets} pipeline. -Passed directly to the \code{input} argument of \code{quarto::quarto_render()}.} +\item{name}{Name of the target. +\code{\link[=tar_quarto]{tar_quarto()}} expects an unevaluated symbol for the \code{name} +argument, and +\code{\link[=tar_quarto_raw]{tar_quarto_raw()}} expects a character string for \code{name}.} + +\item{path}{Character string, path to the Quarto source file.} \item{working_directory}{Optional character string, path to the working directory @@ -80,13 +88,14 @@ the list of file dependencies automatically detected through \item{execute}{Whether to execute embedded code chunks.} -\item{execute_params}{Code, cannot be \code{NULL}. -\code{execute_params} evaluates to a named list of parameters +\item{execute_params}{Named collection of parameters for parameterized Quarto documents. These parameters override the custom custom elements of the \code{params} list in the YAML front-matter of the -Quarto source files. The list is quoted -(not evaluated until the target runs) -so that upstream targets can serve as parameter values.} +Quarto source files. + +\code{\link[=tar_quarto]{tar_quarto()}} expects an unevaluated expression for the +\code{exectue_params} argument, whereas +\code{\link[=tar_quarto_raw]{tar_quarto_raw()}} expects an evaluated expression object.} \item{cache}{Cache execution output (uses knitr cache and jupyter-cache respectively for Rmd and Jupyter input files).} @@ -103,9 +112,8 @@ options added to quarto CLI and not yet supported as function argument.} \item{pandoc_args}{Additional command line options to pass to pandoc.} -\item{profile}{Character of length 1, Quarto profile. If \code{NULL}, -the default profile will be used. Requires Quarto version 1.2 or higher. -See \url{https://quarto.org/docs/projects/profiles.html} for details.} +\item{profile}{\href{https://quarto.org/docs/projects/profiles.html}{Quarto project profile(s)} to use. Either +a character vector of profile names or \code{NULL} to use the default profile.} \item{tidy_eval}{Logical, whether to enable tidy evaluation when interpreting \code{command} and \code{pattern}. If \code{TRUE}, you can use the @@ -230,6 +238,12 @@ See the "Target objects" section for background. \description{ Shorthand to include a Quarto project in a \code{targets} pipeline. + +\code{\link[=tar_quarto]{tar_quarto()}} expects an unevaluated symbol for the \code{name} +argument and an unevaluated expression for the \code{exectue_params} argument. +\code{\link[=tar_quarto_raw]{tar_quarto_raw()}} expects a character string for the \code{name} +argument and an evaluated expression object +for the \code{exectue_params} argument. } \details{ \code{tar_quarto()} is an alternative to \code{tar_target()} for @@ -321,7 +335,7 @@ targets::tar_script({ library(tarchetypes) list( tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_quarto(report, path = "report.qmd") + tar_quarto(name = report, path = "report.qmd") ) }, ask = FALSE) # Then, run the pipeline as usual. @@ -347,9 +361,14 @@ targets::tar_script({ list( tar_target(data, data.frame(x = seq_len(26), y = letters)), tar_quarto( - report, + name = report, path = "report.qmd", execute_params = list(your_param = data) + ), + tar_quarto_raw( + name = "report2", + path = "report.qmd", + execute_params = quote(list(your_param = data)) ) ) }, ask = FALSE) @@ -360,12 +379,8 @@ targets::tar_script({ \seealso{ Other Literate programming targets: \code{\link{tar_knit}()}, -\code{\link{tar_quarto_raw}()}, \code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, \code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} +\code{\link{tar_render_rep}()} } \concept{Literate programming targets} diff --git a/man/tar_quarto_raw.Rd b/man/tar_quarto_raw.Rd deleted file mode 100644 index 219c76f..0000000 --- a/man/tar_quarto_raw.Rd +++ /dev/null @@ -1,344 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_quarto_raw.R -\name{tar_quarto_raw} -\alias{tar_quarto_raw} -\title{Target with a Quarto project (raw version).} -\usage{ -tar_quarto_raw( - name, - path = ".", - working_directory = NULL, - extra_files = character(0), - execute = TRUE, - execute_params = NULL, - cache = NULL, - cache_refresh = FALSE, - debug = FALSE, - quiet = TRUE, - quarto_args = NULL, - pandoc_args = NULL, - profile = NULL, - packages = NULL, - library = NULL, - error = targets::tar_option_get("error"), - memory = targets::tar_option_get("memory"), - garbage_collection = targets::tar_option_get("garbage_collection"), - deployment = "main", - priority = targets::tar_option_get("priority"), - resources = targets::tar_option_get("resources"), - retrieval = targets::tar_option_get("retrieval"), - cue = targets::tar_option_get("cue"), - description = targets::tar_option_get("description") -) -} -\arguments{ -\item{name}{Symbol, name of the target. -In \code{\link[targets:tar_target]{tar_target()}}, \code{name} is an unevaluated symbol, e.g. -\code{tar_target(name = data)}. -In \code{\link[targets:tar_target_raw]{tar_target_raw()}}, \code{name} is a character string, e.g. -\code{tar_target_raw(name = "data")}. - -A target name must be a valid name for a symbol in R, and it -must not start with a dot. Subsequent targets -can refer to this name symbolically to induce a dependency relationship: -e.g. \code{tar_target(downstream_target, f(upstream_target))} is a -target named \code{downstream_target} which depends on a target -\code{upstream_target} and a function \code{f()}. In addition, a target's -name determines its random number generator seed. In this way, -each target runs with a reproducible seed so someone else -running the same pipeline should get the same results, -and no two targets in the same pipeline share the same seed. -(Even dynamic branches have different names and thus different seeds.) -You can recover the seed of a completed target -with \code{tar_meta(your_target, seed)} and run \code{\link[targets:tar_seed_set]{tar_seed_set()}} -on the result to locally recreate the target's initial RNG state.} - -\item{path}{Character of length 1, -either the single \verb{*.qmd} source file to be rendered -or a directory containing a Quarto project. -Defaults to the working directory of the \code{targets} pipeline. -Passed directly to the \code{input} argument of \code{quarto::quarto_render()}.} - -\item{working_directory}{Optional character string, -path to the working directory -to temporarily set when running the report. -The default is \code{NULL}, which runs the report from the -current working directory at the time the pipeline is run. -This default is recommended in the vast majority of cases. -To use anything other than \code{NULL}, you must manually set the value -of the \code{store} argument relative to the working directory in all calls -to \code{tar_read()} and \code{tar_load()} in the report. Otherwise, -these functions will not know where to find the data.} - -\item{extra_files}{Character vector of extra files and -directories to track for changes. The target will be invalidated -(rerun on the next \code{tar_make()}) if the contents of these files changes. -No need to include anything already in the output of \code{\link[=tar_quarto_files]{tar_quarto_files()}}, -the list of file dependencies automatically detected through -\code{quarto::quarto_inspect()}.} - -\item{execute}{Whether to execute embedded code chunks.} - -\item{execute_params}{A non-expression language object -(use \code{quote()}, not \code{expression()}) that -evaluates to a named list of parameters -for parameterized Quarto documents. These parameters override the custom -custom elements of the \code{params} list in the YAML front-matter of the -Quarto source files. The list is quoted -(not evaluated until the target runs) -so that upstream targets can serve as parameter values.} - -\item{cache}{Cache execution output (uses knitr cache and jupyter-cache -respectively for Rmd and Jupyter input files).} - -\item{cache_refresh}{Force refresh of execution cache.} - -\item{debug}{Leave intermediate files in place after render.} - -\item{quiet}{Suppress warning and other messages.} - -\item{quarto_args}{Character vector of other \code{quarto} CLI flag pass to the -command. This is mainly for advanced usage, e.g it can be useful for new -options added to quarto CLI and not yet supported as function argument.} - -\item{pandoc_args}{Additional command line options to pass to pandoc.} - -\item{profile}{Character of length 1, Quarto profile. If \code{NULL}, -the default profile will be used. Requires Quarto version 1.2 or higher. -See \url{https://quarto.org/docs/projects/profiles.html} for details.} - -\item{packages}{Deprecated on 2023-09-05 (version 0.7.8.9000). Please -load R packages inside the Quarto report itself.} - -\item{library}{Deprecated on 2023-09-05 (version 0.7.8.9000). Please -load R packages inside the Quarto report itself.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A target object with \code{format = "file"}. -When this target runs, it returns a sorted character vector -of all the important file paths: the rendered documents, -the Quarto source files, and other input and output files. -The output files are determined by the YAML front-matter of -standalone Quarto documents and \verb{_quarto.yml} in Quarto projects, -and you can see these files with \code{\link[=tar_quarto_files]{tar_quarto_files()}} -(powered by \code{quarto::quarto_inspect()}). -All returned paths are \emph{relative} paths to ensure portability -(so that the project can be moved from one file system to another -without invalidating the target). -See the "Target objects" section for background. -} -\description{ -Shorthand to include a Quarto project or standalone -Quarto source document in a \code{targets} pipeline. -} -\details{ -\code{tar_quarto_raw()} is just like \code{\link[=tar_quarto]{tar_quarto()}} -except that it uses standard evaluation for the -\code{name} and \code{execute_params} arguments (instead of quoting them). -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\section{Literate programming limitations}{ - -Literate programming files are messy and variable, -so functions like \code{\link[=tar_render]{tar_render()}} have limitations: -* Child documents are not tracked for changes. -* Upstream target dependencies are not detected if \code{\link[=tar_read]{tar_read()}} -and/or \code{\link[=tar_load]{tar_load()}} are called from a user-defined function. -In addition, single target names must be mentioned and they must -be symbols. \code{tar_load("x")} and \code{tar_load(contains("x"))} may not -detect target \code{x}. -* Special/optional input/output files may not be detected in all cases. -* \code{\link[=tar_render]{tar_render()}} and friends are for local files only. They do not -integrate with the cloud storage capabilities of \code{targets}. -} - -\section{Quarto troubleshooting}{ - -If you encounter difficult errors, please read -\url{https://github.com/quarto-dev/quarto-r/issues/16}. -In addition, please try to reproduce the error using -\code{quarto::quarto_render("your_report.qmd", execute_dir = getwd())} -without using \code{targets} at all. Isolating errors this way -makes them much easier to solve. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -# Unparameterized Quarto document: -lines <- c( - "---", - "title: report.qmd source file", - "output_format: html", - "---", - "Assume these lines are in report.qmd.", - "```{r}", - "targets::tar_read(data)", - "```" -) -# In tar_dir(), not part of the user's file space: -writeLines(lines, "report.qmd") -# Include the report in a pipeline as follows. -targets::tar_script({ - library(tarchetypes) - list( - tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_quarto_raw("report", path = "report.qmd") - ) -}, ask = FALSE) -# Then, run the pipeline as usual. - -# Parameterized Quarto: -lines <- c( - "---", - "title: 'report.qmd source file with parameters'", - "output_format: html_document", - "params:", - " your_param: \"default value\"", - "---", - "Assume these lines are in report.qmd.", - "```{r}", - "print(params$your_param)", - "```" -) -# In tar_dir(), not part of the user's file space: -writeLines(lines, "report.qmd") -# Include the report in the pipeline as follows. -targets::tar_script({ - library(tarchetypes) - list( - tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_quarto_raw( - "report", - path = "report.qmd", - execute_params = quote(list(your_param = data)) - ) - ) -}, ask = FALSE) -# Then, run the pipeline as usual. -}) -} -} -\seealso{ -Other Literate programming targets: -\code{\link{tar_knit}()}, -\code{\link{tar_quarto}()}, -\code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, -\code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} -} -\concept{Literate programming targets} diff --git a/man/tar_quarto_rep.Rd b/man/tar_quarto_rep.Rd index 8e46a56..7b4b201 100644 --- a/man/tar_quarto_rep.Rd +++ b/man/tar_quarto_rep.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_quarto_rep.R +% Please edit documentation in R/tar_quarto_rep.R, R/tar_quarto_rep_raw.R \name{tar_quarto_rep} \alias{tar_quarto_rep} +\alias{tar_quarto_rep_raw} \title{Parameterized Quarto with dynamic branching.} \usage{ tar_quarto_rep( @@ -34,17 +35,44 @@ tar_quarto_rep( cue = targets::tar_option_get("cue"), description = targets::tar_option_get("description") ) + +tar_quarto_rep_raw( + name, + path, + working_directory = NULL, + execute_params = expression(NULL), + batches = NULL, + extra_files = character(0), + execute = TRUE, + cache = NULL, + cache_refresh = FALSE, + debug = FALSE, + quiet = TRUE, + quarto_args = NULL, + pandoc_args = NULL, + rep_workers = 1, + packages = targets::tar_option_get("packages"), + library = targets::tar_option_get("library"), + format = targets::tar_option_get("format"), + 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"), + retrieval = targets::tar_option_get("retrieval"), + cue = targets::tar_option_get("cue"), + description = targets::tar_option_get("description") +) } \arguments{ \item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} +\code{\link[=tar_quarto_rep]{tar_quarto_rep()}} expects an unevaluated symbol for the \code{name} +argument, and +\code{\link[=tar_quarto_rep_raw]{tar_quarto_rep_raw()}} expects a character string for \code{name}.} -\item{path}{Character string, file path to the Quarto source file. -Must have length 1.} +\item{path}{Character string, path to the Quarto source file.} \item{working_directory}{Optional character string, path to the working directory @@ -59,8 +87,14 @@ these functions will not know where to find the data.} \item{execute_params}{Code to generate a data frame or \code{tibble} with one row per rendered report -and one column per Quarto parameter. You may also include an -\code{output_file} column to specify the path of each rendered report. +and one column per Quarto parameter. +\code{\link[=tar_quarto_rep]{tar_quarto_rep()}} expects an unevaluated expression for the +\code{exectue_params} argument, whereas +\code{\link[=tar_quarto_rep_raw]{tar_quarto_rep_raw()}} expects an evaluated expression object. + +You may also include an +\code{output_file} column in the parameters +to specify the path of each rendered report. If included, the \code{output_file} column must be a character vector with one and only one output file for each row of parameters. If an \code{output_file} column is not included, @@ -75,14 +109,12 @@ that supplies the Quarto parameters.} \item{batches}{Number of batches. This is also the number of dynamic branches created during \code{tar_make()}.} -\item{extra_files}{Character vector of extra files that \code{targets} -should track for changes. If the content of one of these files changes, -then the report will rerun over all the parameters on the next -\code{tar_make()}. These files are \emph{extra} files, and they -do not include the Quarto -source document or rendered output document, -which are already tracked for changes. Examples include -bibliographies, style sheets, and supporting image files.} +\item{extra_files}{Character vector of extra files and +directories to track for changes. The target will be invalidated +(rerun on the next \code{tar_make()}) if the contents of these files changes. +No need to include anything already in the output of \code{\link[=tar_quarto_files]{tar_quarto_files()}}, +the list of file dependencies automatically detected through +\code{quarto::quarto_inspect()}.} \item{execute}{Whether to execute embedded code chunks.} @@ -246,6 +278,12 @@ See the "Target objects" section for background. \description{ Targets to render a parameterized Quarto document with multiple sets of parameters. + +\code{\link[=tar_quarto_rep]{tar_quarto_rep()}} expects an unevaluated symbol for the \code{name} +argument and an unevaluated expression for the \code{exectue_params} argument. +\code{\link[=tar_quarto_rep_raw]{tar_quarto_rep_raw()}} expects a character string for the \code{name} +argument and an evaluated expression object +for the \code{exectue_params} argument. } \details{ \code{tar_quarto_rep()} is an alternative to \code{tar_target()} for @@ -375,9 +413,14 @@ targets::tar_script({ library(tarchetypes) list( tar_quarto_rep( - report, + name = report, path = "report.qmd", execute_params = tibble::tibble(par = c(1, 2)) + ), + tar_quarto_rep_raw( + name = "report", + path = "report.qmd", + execute_params = quote(tibble::tibble(par = c(1, 2))) ) ) }, ask = FALSE) @@ -389,11 +432,7 @@ targets::tar_script({ Other Literate programming targets: \code{\link{tar_knit}()}, \code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, -\code{\link{tar_quarto_rep_raw}()}, \code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} +\code{\link{tar_render_rep}()} } \concept{Literate programming targets} diff --git a/man/tar_quarto_rep_raw.Rd b/man/tar_quarto_rep_raw.Rd deleted file mode 100644 index d8565be..0000000 --- a/man/tar_quarto_rep_raw.Rd +++ /dev/null @@ -1,383 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_quarto_rep_raw.R -\name{tar_quarto_rep_raw} -\alias{tar_quarto_rep_raw} -\title{Parameterized Quarto with dynamic branching (raw version).} -\usage{ -tar_quarto_rep_raw( - name, - path, - working_directory = NULL, - execute_params = expression(NULL), - batches = NULL, - extra_files = character(0), - execute = TRUE, - cache = NULL, - cache_refresh = FALSE, - debug = FALSE, - quiet = TRUE, - quarto_args = NULL, - pandoc_args = NULL, - rep_workers = 1, - packages = targets::tar_option_get("packages"), - library = targets::tar_option_get("library"), - format = targets::tar_option_get("format"), - 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"), - retrieval = targets::tar_option_get("retrieval"), - cue = targets::tar_option_get("cue"), - description = targets::tar_option_get("description") -) -} -\arguments{ -\item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} - -\item{path}{Character string, file path to the Quarto source file. -Must have length 1.} - -\item{working_directory}{Optional character string, -path to the working directory -to temporarily set when running the report. -The default is \code{NULL}, which runs the report from the -current working directory at the time the pipeline is run. -This default is recommended in the vast majority of cases. -To use anything other than \code{NULL}, you must manually set the value -of the \code{store} argument relative to the working directory in all calls -to \code{tar_read()} and \code{tar_load()} in the report. Otherwise, -these functions will not know where to find the data.} - -\item{execute_params}{Expression object with code to generate -a data frame or \code{tibble} with one row per rendered report -and one column per Quarto parameter. You may also include an -\code{output_file} column to specify the path of each rendered report. -If included, the \code{output_file} column must be a character vector -with one and only one output file for each row of parameters. -If an \code{output_file} column is not included, -then the output files are automatically determined using the parameters, -and the default file format is determined by the YAML front-matter -of the Quarto source document. Only the first file format is used, -the others are not generated. -Quarto parameters must not be named \code{tar_group} or \code{output_file}. -This \code{execute_params} argument is converted into the command for a target -that supplies the Quarto parameters.} - -\item{batches}{Number of batches to group the Quarto files. -For a large number of reports, increase the number of batches -to decrease target-level overhead. Defaults to the number of -reports to render (1 report per batch).} - -\item{extra_files}{Character vector of extra files that \code{targets} -should track for changes. If the content of one of these files changes, -then the report will rerun over all the parameters on the next -\code{tar_make()}. These files are \emph{extra} files, and they -do not include the Quarto -source document or rendered output document, -which are already tracked for changes. Examples include -bibliographies, style sheets, and supporting image files.} - -\item{execute}{Whether to execute embedded code chunks.} - -\item{cache}{Cache execution output (uses knitr cache and jupyter-cache -respectively for Rmd and Jupyter input files).} - -\item{cache_refresh}{Force refresh of execution cache.} - -\item{debug}{Leave intermediate files in place after render.} - -\item{quiet}{Suppress warning and other messages.} - -\item{quarto_args}{Character vector of other \code{quarto} CLI flag pass to the -command. This is mainly for advanced usage, e.g it can be useful for new -options added to quarto CLI and not yet supported as function argument.} - -\item{pandoc_args}{Additional command line options to pass to pandoc.} - -\item{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.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Character of length 1, \code{format} argument to \code{tar_target()} -to store the data frame of Quarto parameters.} - -\item{iteration}{Character of length 1, \code{iteration} argument -to \code{tar_target()} for the Quarto documents. Does not apply -to the target with Quarto parameters (whose iteration -is always \code{"group"}).} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} -} -\value{ -A list of target objects to render the Quarto -reports. Changes to the parameters, source file, dependencies, etc. -will cause the appropriate targets to rerun during \code{tar_make()}. -See the "Target objects" section for background. -} -\description{ -Targets to render a parameterized Quarto document -with multiple sets of parameters (raw version). Same as -\code{tar_quarto_rep()} except \code{name} is a character string, -\code{params} is an expression object, -and extra arguments to \code{quarto::quarto_render()} are passed through -the \code{args} argument instead of \code{...}. -} -\details{ -\code{tar_quarto_rep_raw()} is an alternative to \code{tar_target_raw()} for -parameterized Quarto reports that depend on other targets. -Parameters must be given as a data frame with one row per -rendered report and one column per parameter. An optional -\code{output_file} column may be included to set the output file path -of each rendered report. (See the \code{execute_params} argument for details.) - -The Quarto source should mention other dependency targets -\code{tar_load()} and \code{tar_read()} in the active code chunks -(which also allows you to render the report -outside the pipeline if the \verb{_targets/} data store already exists -and appropriate defaults are specified for the parameters). -(Do not use \code{tar_load_raw()} or \code{tar_read_raw()} for this.) -Then, \code{tar_quarto()} defines a special kind of target. It -1. Finds all the \code{tar_load()}/\code{tar_read()} dependencies in the report -and inserts them into the target's command. -This enforces the proper dependency relationships. -(Do not use \code{tar_load_raw()} or \code{tar_read_raw()} for this.) -2. Sets \code{format = "file"} (see \code{tar_target()}) so \code{targets} -watches the files at the returned paths and reruns the report -if those files change. -3. Configures the target's command to return the output -report files: the rendered document, the source file, -and then the \verb{*_files/} directory if it exists. -All these file paths -are relative paths so the project stays portable. -4. Forces the report to run in the user's current working directory -instead of the working directory of the report. -5. Sets convenient default options such as \code{deployment = "main"} -in the target and \code{quiet = TRUE} in \code{quarto::quarto_render()}. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\section{Literate programming limitations}{ - -Literate programming files are messy and variable, -so functions like \code{\link[=tar_render]{tar_render()}} have limitations: -* Child documents are not tracked for changes. -* Upstream target dependencies are not detected if \code{\link[=tar_read]{tar_read()}} -and/or \code{\link[=tar_load]{tar_load()}} are called from a user-defined function. -In addition, single target names must be mentioned and they must -be symbols. \code{tar_load("x")} and \code{tar_load(contains("x"))} may not -detect target \code{x}. -* Special/optional input/output files may not be detected in all cases. -* \code{\link[=tar_render]{tar_render()}} and friends are for local files only. They do not -integrate with the cloud storage capabilities of \code{targets}. -} - -\section{Quarto troubleshooting}{ - -If you encounter difficult errors, please read -\url{https://github.com/quarto-dev/quarto-r/issues/16}. -In addition, please try to reproduce the error using -\code{quarto::quarto_render("your_report.qmd", execute_dir = getwd())} -without using \code{targets} at all. Isolating errors this way -makes them much easier to solve. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -# Parameterized Quarto: -lines <- c( - "---", - "title: 'report.qmd source file'", - "output_format: html_document", - "params:", - " par: \"default value\"", - "---", - "Assume these lines are in a file called report.qmd.", - "```{r}", - "print(params$par)", - "```" -) -writeLines(lines, "report.qmd") # In tar_dir(), not the user's file space. -# The following pipeline will run the report for each row of params. -targets::tar_script({ - library(tarchetypes) - list( - tar_quarto_rep_raw( - "report", - path = "report.qmd", - execute_params = quote(tibble::tibble(par = c(1, 2))) - ) - ) -}, ask = FALSE) -# Then, run the targets pipeline as usual. -}) -} -} -\seealso{ -Other Literate programming targets: -\code{\link{tar_knit}()}, -\code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, -\code{\link{tar_quarto_rep}()}, -\code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} -} -\concept{Literate programming targets} diff --git a/man/tar_render.Rd b/man/tar_render.Rd index 662c5ae..1acc6a2 100644 --- a/man/tar_render.Rd +++ b/man/tar_render.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_render.R +% Please edit documentation in R/tar_render.R, R/tar_render_raw.R \name{tar_render} \alias{tar_render} +\alias{tar_render_raw} \title{Target with an R Markdown document.} \usage{ tar_render( @@ -24,28 +25,30 @@ tar_render( quiet = TRUE, ... ) + +tar_render_raw( + name, + path, + output_file = NULL, + working_directory = NULL, + packages = targets::tar_option_get("packages"), + library = targets::tar_option_get("library"), + error = targets::tar_option_get("error"), + deployment = "main", + priority = targets::tar_option_get("priority"), + resources = targets::tar_option_get("resources"), + retrieval = targets::tar_option_get("retrieval"), + cue = targets::tar_option_get("cue"), + description = targets::tar_option_get("description"), + quiet = TRUE, + render_arguments = quote(list()) +) } \arguments{ -\item{name}{Symbol, name of the target. -In \code{\link[targets:tar_target]{tar_target()}}, \code{name} is an unevaluated symbol, e.g. -\code{tar_target(name = data)}. -In \code{\link[targets:tar_target_raw]{tar_target_raw()}}, \code{name} is a character string, e.g. -\code{tar_target_raw(name = "data")}. - -A target name must be a valid name for a symbol in R, and it -must not start with a dot. Subsequent targets -can refer to this name symbolically to induce a dependency relationship: -e.g. \code{tar_target(downstream_target, f(upstream_target))} is a -target named \code{downstream_target} which depends on a target -\code{upstream_target} and a function \code{f()}. In addition, a target's -name determines its random number generator seed. In this way, -each target runs with a reproducible seed so someone else -running the same pipeline should get the same results, -and no two targets in the same pipeline share the same seed. -(Even dynamic branches have different names and thus different seeds.) -You can recover the seed of a completed target -with \code{tar_meta(your_target, seed)} and run \code{\link[targets:tar_seed_set]{tar_seed_set()}} -on the result to locally recreate the target's initial RNG state.} +\item{name}{Name of the target. +\code{\link[=tar_render]{tar_render()}} expects an unevaluated symbol for the \code{name} argument, +whereas +\code{\link[=tar_render_raw]{tar_render_raw()}} expects a character string for \code{name}.} \item{path}{Character string, file path to the R Markdown source file. Must have length 1.} @@ -185,6 +188,16 @@ For parameterized reports, it is recommended to supply a distinct \code{output_file} argument to each \code{tar_render()} call and set useful defaults for parameters in the R Markdown source. See the examples section for a demonstration.} + +\item{render_arguments}{Optional language object with a list +of named arguments to \code{rmarkdown::render()}. +Cannot be an expression object. +(Use \code{quote()}, not \code{expression()}.) +The reason for quoting is that these arguments may depend on +upstream targets whose values are not available at +the time the target is defined, and because \code{tar_render_raw()} +is the "raw" version of a function, we want to avoid +all non-standard evaluation.} } \value{ A target object with \code{format = "file"}. @@ -200,6 +213,13 @@ See the "Target objects" section for background. \description{ Shorthand to include an R Markdown document in a \code{targets} pipeline. + +\code{\link[=tar_render]{tar_render()}} expects an unevaluated symbol for the \code{name} argument, +and it supports named \code{...} arguments for \code{rmarkdown::render()} +arguments. +\code{\link[=tar_render_raw]{tar_render_raw()}} expects a character string for \code{name} and +supports an evaluated expression object +\code{render_arguments} for \code{rmarkdown::render()} arguments. } \details{ \code{tar_render()} is an alternative to \code{tar_target()} for @@ -300,7 +320,16 @@ targets::tar_script({ library(tarchetypes) list( tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_render(report, "report.Rmd", params = list(your_param = data)) + tar_render( + name = report, + "report.Rmd", + params = list(your_param = data) + ), + tar_render_raw( + name = "report2", + "report.Rmd", + params = quote(list(your_param = data)) + ) ) }, ask = FALSE) }) @@ -311,11 +340,7 @@ targets::tar_script({ Other Literate programming targets: \code{\link{tar_knit}()}, \code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, \code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} +\code{\link{tar_render_rep}()} } \concept{Literate programming targets} diff --git a/man/tar_render_raw.Rd b/man/tar_render_raw.Rd deleted file mode 100644 index c7dfcff..0000000 --- a/man/tar_render_raw.Rd +++ /dev/null @@ -1,256 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_render_raw.R -\name{tar_render_raw} -\alias{tar_render_raw} -\title{Target with an R Markdown document (raw version).} -\usage{ -tar_render_raw( - name, - path, - output_file = NULL, - working_directory = NULL, - packages = targets::tar_option_get("packages"), - library = targets::tar_option_get("library"), - error = targets::tar_option_get("error"), - deployment = "main", - priority = targets::tar_option_get("priority"), - resources = targets::tar_option_get("resources"), - retrieval = targets::tar_option_get("retrieval"), - cue = targets::tar_option_get("cue"), - description = targets::tar_option_get("description"), - quiet = TRUE, - render_arguments = quote(list()) -) -} -\arguments{ -\item{name}{Character of length 1, name of the target.} - -\item{path}{Character string, file path to the R Markdown source file. -Must have length 1.} - -\item{output_file}{Character string, file path to the rendered output file.} - -\item{working_directory}{Optional character string, -path to the working directory -to temporarily set when running the report. -The default is \code{NULL}, which runs the report from the -current working directory at the time the pipeline is run. -This default is recommended in the vast majority of cases. -To use anything other than \code{NULL}, you must manually set the value -of the \code{store} argument relative to the working directory in all calls -to \code{tar_read()} and \code{tar_load()} in the report. Otherwise, -these functions will not know where to find the data.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} - -\item{quiet}{An option to suppress printing during rendering from knitr, -pandoc command line and others. To only suppress printing of the last -"Output created: " message, you can set \code{rmarkdown.render.message} to -\code{FALSE}} - -\item{render_arguments}{Optional language object with a list -of named arguments to \code{rmarkdown::render()}. -Cannot be an expression object. -(Use \code{quote()}, not \code{expression()}.) -The reason for quoting is that these arguments may depend on -upstream targets whose values are not available at -the time the target is defined, and because \code{tar_render_raw()} -is the "raw" version of a function, we want to avoid -all non-standard evaluation.} -} -\value{ -A target object with \code{format = "file"}. -When this target runs, it returns a character vector -of file paths: the rendered document, the source file, -and then the \verb{*_files/} directory if it exists. -Unlike \code{rmarkdown::render()}, -all returned paths are \emph{relative} paths to ensure portability -(so that the project can be moved from one file system to another -without invalidating the target). -See the "Target objects" section for background. -} -\description{ -Shorthand to include an R Markdown document in a -\code{targets} pipeline (raw version) -} -\details{ -\code{tar_render_raw()} is just like \code{tar_render()} -except that it uses standard evaluation. The \code{name} argument -is a character vector, and the \code{render_arguments} argument -is a language object. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\section{Literate programming limitations}{ - -Literate programming files are messy and variable, -so functions like \code{\link[=tar_render]{tar_render()}} have limitations: -* Child documents are not tracked for changes. -* Upstream target dependencies are not detected if \code{\link[=tar_read]{tar_read()}} -and/or \code{\link[=tar_load]{tar_load()}} are called from a user-defined function. -In addition, single target names must be mentioned and they must -be symbols. \code{tar_load("x")} and \code{tar_load(contains("x"))} may not -detect target \code{x}. -* Special/optional input/output files may not be detected in all cases. -* \code{\link[=tar_render]{tar_render()}} and friends are for local files only. They do not -integrate with the cloud storage capabilities of \code{targets}. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -# Unparameterized R Markdown report: -lines <- c( - "---", - "title: 'report.Rmd source file'", - "output_format: html_document", - "---", - "Assume these lines are in report.Rmd.", - "```{r}", - "targets::tar_read(data)", - "```" -) -# Include the report in the pipeline as follows: -targets::tar_script({ - library(tarchetypes) - list( - tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_render_raw("report", "report.Rmd") - ) -}, ask = FALSE) -# Then, run the targets pipeline as usual. - -# Parameterized R Markdown: -lines <- c( - "---", - "title: 'report.Rmd source file with parameters.'", - "output_format: html_document", - "params:", - " your_param: \"default value\"", - "---", - "Assume these lines are in report.Rmd.", - "```{r}", - "print(params$your_param)", - "```" -) -# Include this parameterized report in the pipeline as follows. -targets::tar_script({ - library(tarchetypes) - list( - tar_target(data, data.frame(x = seq_len(26), y = letters)), - tar_render_raw( - "report", - "report.Rmd", - render_arguments = quote(list(params = list(your_param = data))) - ) - ) -}, ask = FALSE) -# Then, run the targets pipeline as usual. -}) -} -} -\seealso{ -Other Literate programming targets: -\code{\link{tar_knit}()}, -\code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, -\code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, -\code{\link{tar_render}()}, -\code{\link{tar_render_rep}()}, -\code{\link{tar_render_rep_raw}()} -} -\concept{Literate programming targets} diff --git a/man/tar_render_rep.Rd b/man/tar_render_rep.Rd index 3ac2b95..85663dc 100644 --- a/man/tar_render_rep.Rd +++ b/man/tar_render_rep.Rd @@ -1,7 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_render_rep.R +% Please edit documentation in R/tar_render_rep.R, R/tar_render_rep_raw.R \name{tar_render_rep} \alias{tar_render_rep} +\alias{tar_render_rep_raw} \title{Parameterized R Markdown with dynamic branching.} \usage{ tar_render_rep( @@ -27,14 +28,36 @@ tar_render_rep( quiet = TRUE, ... ) + +tar_render_rep_raw( + name, + path, + working_directory = NULL, + params = expression(NULL), + batches = NULL, + rep_workers = 1, + packages = targets::tar_option_get("packages"), + library = targets::tar_option_get("library"), + format = targets::tar_option_get("format"), + 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"), + retrieval = targets::tar_option_get("retrieval"), + cue = targets::tar_option_get("cue"), + description = targets::tar_option_get("description"), + quiet = TRUE, + args = list() +) } \arguments{ \item{name}{Name of the target. -\code{\link[=tar_rep]{tar_rep()}} expects unevaluated \code{name} and \code{command} arguments -(e.g. \code{tar_rep(name = sim, command = simulate())}) -whereas \code{\link[=tar_rep_raw]{tar_rep_raw()}} expects an evaluated string for \code{name} -and an evaluated expression object for \code{command} -(e.g. \code{tar_rep_raw(name = "sim", command = quote(simulate()))}).} +\code{\link[=tar_render_rep]{tar_render_rep()}} expects an unevaluated symbol for the \code{name} argument, +whereas +\code{\link[=tar_render_rep_raw]{tar_render_rep_raw()}} expects a character string for \code{name}.} \item{path}{Character string, file path to the R Markdown source file. Must have length 1.} @@ -202,6 +225,10 @@ Unlike \code{\link[=tar_render]{tar_render()}}, these arguments are evaluated wh is defined, not when it is run. (The only reason to delay evaluation in \code{\link[=tar_render]{tar_render()}} was to handle R Markdown parameters, and \code{tar_render_rep()} handles them differently.)} + +\item{args}{Named list of other arguments to \code{rmarkdown::render()}. +Must not include \code{params} or \code{output_file}. Evaluated when the target +is defined.} } \value{ A list of target objects to render the R Markdown @@ -212,6 +239,13 @@ See the "Target objects" section for background. \description{ Targets to render a parameterized R Markdown report with multiple sets of parameters. + +\code{\link[=tar_render_rep]{tar_render_rep()}} expects an unevaluated symbol for the \code{name} argument, +and it supports named \code{...} arguments for \code{rmarkdown::render()} +arguments. +\code{\link[=tar_render_rep_raw]{tar_render_rep_raw()}} expects a character string for \code{name} and +supports an evaluated expression object +\code{render_arguments} for \code{rmarkdown::render()} arguments. } \details{ \code{tar_render_rep()} is an alternative to \code{tar_target()} for @@ -329,9 +363,14 @@ targets::tar_script({ library(tarchetypes) list( tar_render_rep( - report, + name = report, "report.Rmd", params = tibble::tibble(par = c(1, 2)) + ), + tar_render_rep_raw( + name = "report2", + "report.Rmd", + params = quote(tibble::tibble(par = c(1, 2))) ) ) }, ask = FALSE) @@ -343,11 +382,7 @@ targets::tar_script({ Other Literate programming targets: \code{\link{tar_knit}()}, \code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, \code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, -\code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep_raw}()} +\code{\link{tar_render}()} } \concept{Literate programming targets} diff --git a/man/tar_render_rep_raw.Rd b/man/tar_render_rep_raw.Rd deleted file mode 100644 index 7c8a4e5..0000000 --- a/man/tar_render_rep_raw.Rd +++ /dev/null @@ -1,355 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_render_rep_raw.R -\name{tar_render_rep_raw} -\alias{tar_render_rep_raw} -\title{Parameterized R Markdown with dynamic branching (raw version).} -\usage{ -tar_render_rep_raw( - name, - path, - working_directory = NULL, - params = expression(NULL), - batches = NULL, - rep_workers = 1, - packages = targets::tar_option_get("packages"), - library = targets::tar_option_get("library"), - format = targets::tar_option_get("format"), - 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"), - retrieval = targets::tar_option_get("retrieval"), - cue = targets::tar_option_get("cue"), - description = targets::tar_option_get("description"), - quiet = TRUE, - args = list() -) -} -\arguments{ -\item{name}{Symbol, name of the target. -In \code{\link[targets:tar_target]{tar_target()}}, \code{name} is an unevaluated symbol, e.g. -\code{tar_target(name = data)}. -In \code{\link[targets:tar_target_raw]{tar_target_raw()}}, \code{name} is a character string, e.g. -\code{tar_target_raw(name = "data")}. - -A target name must be a valid name for a symbol in R, and it -must not start with a dot. Subsequent targets -can refer to this name symbolically to induce a dependency relationship: -e.g. \code{tar_target(downstream_target, f(upstream_target))} is a -target named \code{downstream_target} which depends on a target -\code{upstream_target} and a function \code{f()}. In addition, a target's -name determines its random number generator seed. In this way, -each target runs with a reproducible seed so someone else -running the same pipeline should get the same results, -and no two targets in the same pipeline share the same seed. -(Even dynamic branches have different names and thus different seeds.) -You can recover the seed of a completed target -with \code{tar_meta(your_target, seed)} and run \code{\link[targets:tar_seed_set]{tar_seed_set()}} -on the result to locally recreate the target's initial RNG state.} - -\item{path}{Character string, file path to the R Markdown source file. -Must have length 1.} - -\item{working_directory}{Optional character string, -path to the working directory -to temporarily set when running the report. -The default is \code{NULL}, which runs the report from the -current working directory at the time the pipeline is run. -This default is recommended in the vast majority of cases. -To use anything other than \code{NULL}, you must manually set the value -of the \code{store} argument relative to the working directory in all calls -to \code{tar_read()} and \code{tar_load()} in the report. Otherwise, -these functions will not know where to find the data.} - -\item{params}{Expression object with code to generate -a data frame or \code{tibble} with one row per rendered report -and one column per R Markdown parameter. You may also include an -\code{output_file} column to specify the path of each rendered report. -R Markdown parameters must not be named \code{tar_group} or \code{output_file}. -This \code{params} argument is converted into the command for a target -that supplies the R Markdown parameters.} - -\item{batches}{Number of batches to group the R Markdown files. -For a large number of reports, increase the number of batches -to decrease target-level overhead. Defaults to the number of -reports to render (1 report per batch).} - -\item{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.} - -\item{packages}{Character vector of packages to load right before -the target runs or the output data is reloaded for -downstream targets. Use \code{tar_option_set()} to set packages -globally for all subsequent targets you define.} - -\item{library}{Character vector of library paths to try -when loading \code{packages}.} - -\item{format}{Character of length 1, \code{format} argument to \code{tar_target()} -to store the data frame of R Markdown parameters.} - -\item{iteration}{Character of length 1, \code{iteration} argument -to \code{tar_target()} for the R Markdown documents. Does not apply -to the target with R Markdown parameters (whose iteration -is always \code{"group"}).} - -\item{error}{Character of length 1, what to do if the target -stops and throws an error. Options: -\itemize{ -\item \code{"stop"}: the whole pipeline stops and throws an error. -\item \code{"continue"}: the whole pipeline keeps going. -\item \code{"null"}: The errored target continues and returns \code{NULL}. -The data hash is deliberately wrong so the target is not -up to date for the next run of the pipeline. -\item \code{"abridge"}: any currently running targets keep running, -but no new targets launch after that. -\item \code{"trim"}: all currently running targets stay running. A queued -target is allowed to start if: -\enumerate{ -\item It is not downstream of the error, and -\item It is not a sibling branch from the same \code{\link[targets:tar_target]{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. \code{error = "trim"} is just like \code{error = "abridge"}, -but it allows potentially healthy regions of the dependency graph -to begin running. -(Visit \url{https://books.ropensci.org/targets/debugging.html} -to learn how to debug targets using saved workspaces.) -}} - -\item{memory}{Character of length 1, memory strategy. -If \code{"persistent"}, the target stays in memory -until the end of the pipeline (unless \code{storage} is \code{"worker"}, -in which case \code{targets} unloads the value from memory -right after storing it in order to avoid sending -copious data over a network). -If \code{"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. \code{format = "file"} with \code{repository = "aws"}), -this memory strategy applies to the -temporary local copy of the file: -\code{"persistent"} means it remains until the end of the pipeline -and is then deleted, -and \code{"transient"} means it gets deleted as soon as possible. -The former conserves bandwidth, -and the latter conserves local storage.} - -\item{garbage_collection}{Logical, whether to run \code{base::gc()} -just before the target runs.} - -\item{deployment}{Character of length 1. If \code{deployment} is -\code{"main"}, then the target will run on the central controlling R process. -Otherwise, if \code{deployment} is \code{"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 in \code{targets}, please visit -\url{https://books.ropensci.org/targets/crew.html}.} - -\item{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 \code{\link[targets:tar_make_future]{tar_make_future()}}).} - -\item{resources}{Object returned by \code{tar_resources()} -with optional settings for high-performance computing -functionality, alternative data storage formats, -and other optional capabilities of \code{targets}. -See \code{tar_resources()} for details.} - -\item{retrieval}{Character of length 1, only relevant to -\code{\link[targets:tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[targets:tar_make_future]{tar_make_future()}}. -Must be one of the following values: -\itemize{ -\item \code{"main"}: the target's dependencies are loaded on the host machine -and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. -}} - -\item{cue}{An optional object from \code{tar_cue()} to customize the -rules that decide whether the target is up to date.} - -\item{description}{Character of length 1, a custom free-form human-readable -text description of the target. Descriptions appear as target labels -in functions like \code{\link[targets:tar_manifest]{tar_manifest()}} and \code{\link[targets:tar_visnetwork]{tar_visnetwork()}}, -and they let you select subsets of targets for the \code{names} argument of -functions like \code{\link[targets:tar_make]{tar_make()}}. For example, -\code{tar_manifest(names = tar_described_as(starts_with("survival model")))} -lists all the targets whose descriptions start with the character -string \code{"survival model"}.} - -\item{quiet}{An option to suppress printing during rendering from knitr, -pandoc command line and others. To only suppress printing of the last -"Output created: " message, you can set \code{rmarkdown.render.message} to -\code{FALSE}} - -\item{args}{Named list of other arguments to \code{rmarkdown::render()}. -Must not include \code{params} or \code{output_file}. Evaluated when the target -is defined.} -} -\value{ -A list of target objects to render the R Markdown -reports. Changes to the parameters, source file, dependencies, etc. -will cause the appropriate targets to rerun during \code{tar_make()}. -See the "Target objects" section for background. -} -\description{ -Targets to render a parameterized R Markdown report -with multiple sets of parameters (raw version). Same as -\code{tar_render_rep()} except \code{name} is a character string, -\code{params} is an expression object, -and extra arguments to \code{rmarkdown::render()} are passed through -the \code{args} argument instead of \code{...}. -} -\details{ -\code{tar_render_rep_raw()} is an alternative to \code{tar_target_raw()} for -parameterized R Markdown reports that depend on other targets. -Parameters must be given as a data frame with one row per -rendered report and one column per parameter. An optional -\code{output_file} column may be included to set the output file path -of each rendered report. -The R Markdown source should mention other dependency targets -\code{tar_load()} and \code{tar_read()} in the active code chunks -(which also allows you to render the report -outside the pipeline if the \verb{_targets/} data store already exists -and appropriate defaults are specified for the parameters). -(Do not use \code{tar_load_raw()} or \code{tar_read_raw()} for this.) -Then, \code{tar_render()} defines a special kind of target. It -1. Finds all the \code{tar_load()}/\code{tar_read()} dependencies in the report -and inserts them into the target's command. -This enforces the proper dependency relationships. -(Do not use \code{tar_load_raw()} or \code{tar_read_raw()} for this.) -2. Sets \code{format = "file"} (see \code{tar_target()}) so \code{targets} -watches the files at the returned paths and reruns the report -if those files change. -3. Configures the target's command to return the output -report files: the rendered document, the source file, -and then the \verb{*_files/} directory if it exists. -All these file paths -are relative paths so the project stays portable. -4. Forces the report to run in the user's current working directory -instead of the working directory of the report. -5. Sets convenient default options such as \code{deployment = "main"} -in the target and \code{quiet = TRUE} in \code{rmarkdown::render()}. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of 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 \code{\link[=tar_rep]{tar_rep()}} -and friends give each \emph{replicate} its own unique seed. -Each replicate-specific seed is created -based on the dynamic parent target name, -\code{tar_option_get("seed")} (for \code{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, -\code{tar_rep(name = x, command = rnorm(1), batches = 100, reps = 1, ...)} -produces the same numerical output as -\code{tar_rep(name = x, command = rnorm(1), batches = 10, reps = 10, ...)} -(but with different batch names). -Other target factories with this seed scheme are \code{\link[=tar_rep2]{tar_rep2()}}, -\code{\link[=tar_map_rep]{tar_map_rep()}}, \code{\link[=tar_map2_count]{tar_map2_count()}}, \code{\link[=tar_map2_size]{tar_map2_size()}}, -and \code{\link[=tar_render_rep]{tar_render_rep()}}. -For the \verb{tar_map2_*()} functions, -it is possible to manually supply your own seeds -through the \code{command1} argument and then invoke them in your -custom code for \code{command2} (\code{set.seed()}, \code{withr::with_seed}, -or \code{withr::local_seed()}). For \code{\link[=tar_render_rep]{tar_render_rep()}}, -custom seeds can be supplied to the \code{params} argument -and then invoked in the individual R Markdown reports. -Likewise with \code{\link[=tar_quarto_rep]{tar_quarto_rep()}} and the \code{execute_params} argument. -} - -\section{Literate programming limitations}{ - -Literate programming files are messy and variable, -so functions like \code{\link[=tar_render]{tar_render()}} have limitations: -* Child documents are not tracked for changes. -* Upstream target dependencies are not detected if \code{\link[=tar_read]{tar_read()}} -and/or \code{\link[=tar_load]{tar_load()}} are called from a user-defined function. -In addition, single target names must be mentioned and they must -be symbols. \code{tar_load("x")} and \code{tar_load(contains("x"))} may not -detect target \code{x}. -* Special/optional input/output files may not be detected in all cases. -* \code{\link[=tar_render]{tar_render()}} and friends are for local files only. They do not -integrate with the cloud storage capabilities of \code{targets}. -} - -\examples{ -if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) { -targets::tar_dir({ # tar_dir() runs code from a temporary directory. -# Parameterized R Markdown: -lines <- c( - "---", - "title: 'report.Rmd source file'", - "output_format: html_document", - "params:", - " par: \"default value\"", - "---", - "Assume these lines are in a file called report.Rmd.", - "```{r}", - "print(params$par)", - "```" -) -# The following pipeline will run the report for each row of params. -targets::tar_script({ - library(tarchetypes) - list( - tar_render_rep_raw( - "report", - "report.Rmd", - params = quote(tibble::tibble(par = c(1, 2))) - ) - ) -}, ask = FALSE) -# Then, run the targets pipeline as usual. -}) -} -} -\seealso{ -Other Literate programming targets: -\code{\link{tar_knit}()}, -\code{\link{tar_quarto}()}, -\code{\link{tar_quarto_raw}()}, -\code{\link{tar_quarto_rep}()}, -\code{\link{tar_quarto_rep_raw}()}, -\code{\link{tar_render}()}, -\code{\link{tar_render_raw}()}, -\code{\link{tar_render_rep}()} -} -\concept{Literate programming targets} diff --git a/man/tar_rep.Rd b/man/tar_rep.Rd index 670b0b6..22118ff 100644 --- a/man/tar_rep.Rd +++ b/man/tar_rep.Rd @@ -400,12 +400,8 @@ targets::tar_read(x) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()}, \code{\link{tar_rep_map_raw}()} diff --git a/man/tar_rep2.Rd b/man/tar_rep2.Rd index b72d56b..ee9d1c4 100644 --- a/man/tar_rep2.Rd +++ b/man/tar_rep2.Rd @@ -391,12 +391,8 @@ targets::tar_read(aggregate) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep_map}()}, \code{\link{tar_rep_map_raw}()} diff --git a/man/tar_rep_map.Rd b/man/tar_rep_map.Rd index 12c1a08..1871b6d 100644 --- a/man/tar_rep_map.Rd +++ b/man/tar_rep_map.Rd @@ -310,12 +310,8 @@ targets::tar_read(aggregate) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map_raw}()} diff --git a/man/tar_rep_map_raw.Rd b/man/tar_rep_map_raw.Rd index fbb62d5..c1031b0 100644 --- a/man/tar_rep_map_raw.Rd +++ b/man/tar_rep_map_raw.Rd @@ -311,12 +311,8 @@ targets::tar_read(aggregate) Other branching: \code{\link{tar_map2}()}, \code{\link{tar_map2_count}()}, -\code{\link{tar_map2_count_raw}()}, -\code{\link{tar_map2_raw}()}, \code{\link{tar_map2_size}()}, -\code{\link{tar_map2_size_raw}()}, \code{\link{tar_map_rep}()}, -\code{\link{tar_map_rep_raw}()}, \code{\link{tar_rep}()}, \code{\link{tar_rep2}()}, \code{\link{tar_rep_map}()} diff --git a/man/tar_sub.Rd b/man/tar_sub.Rd index 0d2924a..e1689f6 100644 --- a/man/tar_sub.Rd +++ b/man/tar_sub.Rd @@ -1,14 +1,21 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_sub.R +% Please edit documentation in R/tar_sub.R, R/tar_sub_raw.R \name{tar_sub} \alias{tar_sub} +\alias{tar_sub_raw} \title{Create multiple expressions with symbol substitution.} \usage{ tar_sub(expr, values) + +tar_sub_raw(expr, values) } \arguments{ \item{expr}{Starting expression. Values are iteratively substituted -in place of symbols in \code{expr} to create each new expression.} +in place of symbols in \code{expr} to create each new expression. + +\code{\link[=tar_sub]{tar_sub()}} expects an unevaluated expression for +the \code{expr} object, whereas \code{\link[=tar_sub_raw]{tar_sub_raw()}} expects an +evaluated expression object.} \item{values}{List of values to substitute into \code{expr} to create the expressions. All elements of \code{values} must have the same length.} @@ -21,6 +28,10 @@ See the "Target objects" section for background. \description{ Loop over a grid of values and create an expression object from each one. Helps with general metaprogramming. + +\code{\link[=tar_sub]{tar_sub()}} expects an unevaluated expression for +the \code{expr} object, whereas \code{\link[=tar_sub_raw]{tar_sub_raw()}} expects an +evaluated expression object. } \section{Target objects}{ @@ -50,11 +61,10 @@ values <- list( file = list("file1.Rmd", "file2.Rmd") ) tar_sub(tar_render(name, file), values = values) +tar_sub_raw(quote(tar_render(name, file)), values = values) } \seealso{ Other Metaprogramming utilities: -\code{\link{tar_eval}()}, -\code{\link{tar_eval_raw}()}, -\code{\link{tar_sub_raw}()} +\code{\link{tar_eval}()} } \concept{Metaprogramming utilities} diff --git a/man/tar_sub_raw.Rd b/man/tar_sub_raw.Rd deleted file mode 100644 index 3db96d3..0000000 --- a/man/tar_sub_raw.Rd +++ /dev/null @@ -1,63 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tar_sub_raw.R -\name{tar_sub_raw} -\alias{tar_sub_raw} -\title{Create multiple expressions with symbol substitution (raw version).} -\usage{ -tar_sub_raw(expr, values) -} -\arguments{ -\item{expr}{Expression object with the starting expression. -Values are iteratively substituted -in place of symbols in \code{expr} to create each new expression.} - -\item{values}{List of values to substitute into \code{expr} to create -the expressions. All elements of \code{values} must have the same length.} -} -\value{ -A list of expression objects. Often, these expression objects -evaluate to target objects (but not necessarily). -See the "Target objects" section for background. -} -\description{ -Loop over a grid of values and create an expression object -from each one. Helps with general metaprogramming. Unlike \code{\link[=tar_sub]{tar_sub()}}, -which quotes the \code{expr} argument, \code{tar_sub_raw()} assumes \code{expr} -is an expression object. -} -\section{Target objects}{ - -Most \code{tarchetypes} 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 \url{https://books.ropensci.org/targets/}. -Please read the walkthrough at -\url{https://books.ropensci.org/targets/walkthrough.html} -to understand the role of target objects in analysis pipelines. - -For developers, -\url{https://wlandau.github.io/targetopia/contributing.html#target-factories} -explains target factories (functions like this one which generate targets) -and the design specification at -\url{https://books.ropensci.org/targets-design/} -details the structure and composition of target objects. -} - -\examples{ -# tar_map() is incompatible with tar_render() because the latter -# operates on preexisting tar_target() objects. By contrast, -# tar_eval_raw() and tar_sub_raw() iterate over code farther upstream. -values <- list( - name = lapply(c("name1", "name2"), as.symbol), - file = c("file1.Rmd", "file2.Rmd") -) -tar_sub_raw(quote(tar_render(name, file)), values = values) -} -\seealso{ -Other Metaprogramming utilities: -\code{\link{tar_eval}()}, -\code{\link{tar_eval_raw}()}, -\code{\link{tar_sub}()} -} -\concept{Metaprogramming utilities}