tar_seed_get()

DESCRIPTION

@@ -12,7 +12,7 @@ Description: Pipeline tools coordinate the pieces of computationally
   The methodology in this package
   borrows from GNU 'Make' (2015, ISBN:978-9881443519)
   and 'drake' (2018, <doi:10.21105/joss.00550>).
-Version: 1.3.2.9000
+Version: 1.3.2.9001
 License: MIT + file LICENSE
 URL: https://docs.ropensci.org/targets/, https://github.com/ropensci/targets
 BugReports: https://github.com/ropensci/targets/issues

NAMESPACE

@@ -474,6 +474,7 @@ export(tar_resources_url)
 export(tar_runtime_object)
 export(tar_script)
 export(tar_seed)
+export(tar_seed_get)
 export(tar_seed_set)
 export(tar_sitrep)
 export(tar_skipped)

NEWS.md

@@ -1,6 +1,7 @@
-# targets 1.3.2.9000 (development)
+# targets 1.3.2.9001 (development)
 
 * Add function `tar_seed_set()` which sets a seed and the default RNG algorithms.
+* Deprecate `tar_seed()` in favor of the new `tar_seed_get()` function.
 
 # targets 1.3.2
 

R/tar_seed.R

@@ -1,26 +1,13 @@
-#' @title Get the random number generator seed of the target currently running.
+#' @title Deprecated: get the seed of the current target.
 #' @export
-#' @family utilities
-#' @description Get the random number generator seed
-#'   of the target currently running.
-#' @details A target's random number generator seed
-#'   is a deterministic function of its name. 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 retrieve the seed of a completed target
-#'   with `tar_meta(your_target, seed)`
-#'   and run [tar_seed_set()] on the result to locally
-#'   recreate the target's initial RNG state.
+#' @keywords internal
+#' @description Deprecated on 2023-10-12 (version 1.3.2.9001).
+#'   Use [tar_seed_get()] instead.
 #' @return Integer of length 1. If invoked inside a `targets` pipeline,
 #'   the return value is the seed of the target currently running,
 #'   which is a deterministic function of the target name. Otherwise,
 #'   the return value is `default`.
-#' @param default Integer, value to return if `tar_seed()`
-#'   is called on its own outside a `targets` pipeline.
-#'   Having a default lets users run things without [tar_make()],
-#'   which helps peel back layers of code and troubleshoot bugs.
+#' @inheritParams tar_seed_get
 #' @examples
 #' tar_seed()
 #' tar_seed(default = 123L)
@@ -32,12 +19,9 @@
 #' })
 #' }
 tar_seed <- function(default = 1L) {
-  default <- as.integer(default)
-  tar_assert_int(default)
-  tar_assert_scalar(default)
-  if_any(
-    !is.null(tar_runtime$target),
-    tar_runtime$target$command$seed,
-    as.integer(default)
+  tar_warn_deprecate(
+    "tar_seed() was deprecated on 2023-10-12 (version 1.3.2.9001). ",
+    "Use tar_seed_get() instead."
   )
+  tar_seed_get(default = default)
 }

R/tar_seed_get.R

@@ -0,0 +1,43 @@
+#' @title Get the random number generator seed of the target currently running.
+#' @export
+#' @family pseudo-random number generation
+#' @description Get the random number generator seed
+#'   of the target currently running.
+#' @details A target's random number generator seed
+#'   is a deterministic function of its name. 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 retrieve the seed of a completed target
+#'   with `tar_meta(your_target, seed)`
+#'   and run [tar_seed_set()] on the result to locally
+#'   recreate the target's initial RNG state.
+#' @return Integer of length 1. If invoked inside a `targets` pipeline,
+#'   the return value is the seed of the target currently running,
+#'   which is a deterministic function of the target name. Otherwise,
+#'   the return value is `default`.
+#' @param default Integer, value to return if `tar_seed_get()`
+#'   is called on its own outside a `targets` pipeline.
+#'   Having a default lets users run things without [tar_make()],
+#'   which helps peel back layers of code and troubleshoot bugs.
+#' @examples
+#' tar_seed_get()
+#' tar_seed_get(default = 123L)
+#' if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
+#' tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
+#' tar_script(tar_target(returns_seed, tar_seed_get()), ask = FALSE)
+#' tar_make()
+#' tar_read(returns_seed)
+#' })
+#' }
+tar_seed_get <- function(default = 1L) {
+  default <- as.integer(default)
+  tar_assert_int(default)
+  tar_assert_scalar(default)
+  if_any(
+    !is.null(tar_runtime$target),
+    tar_runtime$target$command$seed,
+    as.integer(default)
+  )
+}

R/tar_seed_set.R

@@ -1,6 +1,6 @@
 #' @title Set a seed to run a target.
 #' @export
-#' @family seeds
+#' @family pseudo-random number generation
 #' @description `targets` generates its own target-specific seeds
 #'   using [tar_seed_create()]. Use [tar_seed_set()] to set one of
 #'   these seeds in R.

tests/testthat/test-tar_seed.R

@@ -1,16 +1,3 @@
-tar_test("tar_seed() outside a pipeline", {
-  expect_equal(tar_seed(), 1L)
-  expect_equal(tar_seed(default = 123L), 123L)
-})
-
-tar_test("tar_seed() inside a pipeline", {
-  x <- target_init("x", quote(targets::tar_seed(default = 1L)))
-  local_init(pipeline_init(list(x)))$run()
-  expect_true(is.integer(target_read_value(x)$object))
-  seed <- target_read_value(x)$object
-  expect_false(seed == 1L)
-  tar_destroy()
-  x <- target_init("x", quote(targets::tar_seed(default = 1L)))
-  local_init(pipeline_init(list(x)))$run()
-  expect_identical(target_read_value(x)$object, seed)
+tar_test("deprecate tar_seed()", {
+  expect_warning(tar_seed(), class = "tar_condition_deprecate")
 })