From 251dd44841681ea7ffcdf226085d79ca8628009a Mon Sep 17 00:00:00 2001 From: wlandau Date: Thu, 12 Oct 2023 12:13:21 -0400 Subject: [PATCH] tar_seed_get() --- DESCRIPTION | 2 +- NAMESPACE | 1 + NEWS.md | 3 +- R/tar_seed.R | 34 ++++++------------- R/tar_seed_get.R | 43 ++++++++++++++++++++++++ R/tar_seed_set.R | 2 +- man/tar_active.Rd | 1 - man/tar_backoff.Rd | 1 - man/tar_call.Rd | 1 - man/tar_cancel.Rd | 1 - man/tar_definition.Rd | 1 - man/tar_envir.Rd | 1 - man/tar_group.Rd | 1 - man/tar_name.Rd | 1 - man/tar_path.Rd | 1 - man/tar_path_script.Rd | 1 - man/tar_path_script_support.Rd | 1 - man/tar_path_store.Rd | 1 - man/tar_path_target.Rd | 1 - man/tar_seed.Rd | 40 +++-------------------- man/tar_seed_get.Rd | 52 ++++++++++++++++++++++++++++++ man/tar_seed_set.Rd | 6 +++- man/tar_source.Rd | 1 - man/tar_store.Rd | 1 - tests/testthat/test-tar_seed.R | 17 ++-------- tests/testthat/test-tar_seed_get.R | 16 +++++++++ 26 files changed, 137 insertions(+), 94 deletions(-) create mode 100644 R/tar_seed_get.R create mode 100644 man/tar_seed_get.Rd create mode 100644 tests/testthat/test-tar_seed_get.R diff --git a/DESCRIPTION b/DESCRIPTION index c64a65df2..1a9099447 100644 --- a/DESCRIPTION +++ b/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, ). -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 diff --git a/NAMESPACE b/NAMESPACE index 51c1a10ef..44e16f924 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index c936e8f06..178d50e72 100644 --- a/NEWS.md +++ b/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 diff --git a/R/tar_seed.R b/R/tar_seed.R index 79874033d..aa68f82ff 100644 --- a/R/tar_seed.R +++ b/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) } diff --git a/R/tar_seed_get.R b/R/tar_seed_get.R new file mode 100644 index 000000000..0178ba149 --- /dev/null +++ b/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) + ) +} diff --git a/R/tar_seed_set.R b/R/tar_seed_set.R index 49535f5b3..1c6a82019 100644 --- a/R/tar_seed_set.R +++ b/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. diff --git a/man/tar_active.Rd b/man/tar_active.Rd index d4c545c09..e595395b0 100644 --- a/man/tar_active.Rd +++ b/man/tar_active.Rd @@ -42,7 +42,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_backoff.Rd b/man/tar_backoff.Rd index 7efc2286b..84c279529 100644 --- a/man/tar_backoff.Rd +++ b/man/tar_backoff.Rd @@ -69,7 +69,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_call.Rd b/man/tar_call.Rd index 1f2153dff..5486ff859 100644 --- a/man/tar_call.Rd +++ b/man/tar_call.Rd @@ -46,7 +46,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_cancel.Rd b/man/tar_cancel.Rd index 0e23a6797..2cc77b356 100644 --- a/man/tar_cancel.Rd +++ b/man/tar_cancel.Rd @@ -39,7 +39,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_definition.Rd b/man/tar_definition.Rd index e1af0cbf5..9233ea1a4 100644 --- a/man/tar_definition.Rd +++ b/man/tar_definition.Rd @@ -75,7 +75,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_envir.Rd b/man/tar_envir.Rd index e4e1f42cd..272993db9 100644 --- a/man/tar_envir.Rd +++ b/man/tar_envir.Rd @@ -56,7 +56,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_group.Rd b/man/tar_group.Rd index 45619a6ea..f77c57a9f 100644 --- a/man/tar_group.Rd +++ b/man/tar_group.Rd @@ -87,7 +87,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_name.Rd b/man/tar_name.Rd index e158099b7..aca90f3af 100644 --- a/man/tar_name.Rd +++ b/man/tar_name.Rd @@ -45,7 +45,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_path.Rd b/man/tar_path.Rd index 3f8d75ff4..f2e142e8f 100644 --- a/man/tar_path.Rd +++ b/man/tar_path.Rd @@ -89,7 +89,6 @@ Other utilities: \code{\link{tar_path_script}()}, \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_path_script.Rd b/man/tar_path_script.Rd index 8c744794f..411ece3e9 100644 --- a/man/tar_path_script.Rd +++ b/man/tar_path_script.Rd @@ -41,7 +41,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_path_script_support.Rd b/man/tar_path_script_support.Rd index bfab90e51..6b2aa5715 100644 --- a/man/tar_path_script_support.Rd +++ b/man/tar_path_script_support.Rd @@ -56,7 +56,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_path_store.Rd b/man/tar_path_store.Rd index 523310672..d338ce6cf 100644 --- a/man/tar_path_store.Rd +++ b/man/tar_path_store.Rd @@ -41,7 +41,6 @@ Other utilities: \code{\link{tar_path_script}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_path_target.Rd b/man/tar_path_target.Rd index 84d3dd7f8..ee0b9b6be 100644 --- a/man/tar_path_target.Rd +++ b/man/tar_path_target.Rd @@ -88,7 +88,6 @@ Other utilities: \code{\link{tar_path_script}()}, \code{\link{tar_path_store}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()}, \code{\link{tar_store}()} } diff --git a/man/tar_seed.Rd b/man/tar_seed.Rd index 7466293bb..13efe6cb5 100644 --- a/man/tar_seed.Rd +++ b/man/tar_seed.Rd @@ -2,12 +2,12 @@ % Please edit documentation in R/tar_seed.R \name{tar_seed} \alias{tar_seed} -\title{Get the random number generator seed of the target currently running.} +\title{Deprecated: get the seed of the current target.} \usage{ tar_seed(default = 1L) } \arguments{ -\item{default}{Integer, value to return if \code{tar_seed()} +\item{default}{Integer, value to return if \code{tar_seed_get()} is called on its own outside a \code{targets} pipeline. Having a default lets users run things without \code{\link[=tar_make]{tar_make()}}, which helps peel back layers of code and troubleshoot bugs.} @@ -19,20 +19,8 @@ which is a deterministic function of the target name. Otherwise, the return value is \code{default}. } \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 \code{tar_meta(your_target, seed)} -and run \code{\link[=tar_seed_set]{tar_seed_set()}} on the result to locally -recreate the target's initial RNG state. +Deprecated on 2023-10-12 (version 1.3.2.9001). +Use \code{\link[=tar_seed_get]{tar_seed_get()}} instead. } \examples{ tar_seed() @@ -45,22 +33,4 @@ tar_read(returns_seed) }) } } -\seealso{ -Other utilities: -\code{\link{tar_active}()}, -\code{\link{tar_backoff}()}, -\code{\link{tar_call}()}, -\code{\link{tar_cancel}()}, -\code{\link{tar_definition}()}, -\code{\link{tar_envir}()}, -\code{\link{tar_group}()}, -\code{\link{tar_name}()}, -\code{\link{tar_path_script_support}()}, -\code{\link{tar_path_script}()}, -\code{\link{tar_path_store}()}, -\code{\link{tar_path_target}()}, -\code{\link{tar_path}()}, -\code{\link{tar_source}()}, -\code{\link{tar_store}()} -} -\concept{utilities} +\keyword{internal} diff --git a/man/tar_seed_get.Rd b/man/tar_seed_get.Rd new file mode 100644 index 000000000..aec36d1e9 --- /dev/null +++ b/man/tar_seed_get.Rd @@ -0,0 +1,52 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/tar_seed_get.R +\name{tar_seed_get} +\alias{tar_seed_get} +\title{Get the random number generator seed of the target currently running.} +\usage{ +tar_seed_get(default = 1L) +} +\arguments{ +\item{default}{Integer, value to return if \code{tar_seed_get()} +is called on its own outside a \code{targets} pipeline. +Having a default lets users run things without \code{\link[=tar_make]{tar_make()}}, +which helps peel back layers of code and troubleshoot bugs.} +} +\value{ +Integer of length 1. If invoked inside a \code{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 \code{default}. +} +\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 \code{tar_meta(your_target, seed)} +and run \code{\link[=tar_seed_set]{tar_seed_set()}} on the result to locally +recreate the target's initial RNG state. +} +\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) +}) +} +} +\seealso{ +Other pseudo-random number generation: +\code{\link{tar_seed_set}()} +} +\concept{pseudo-random number generation} diff --git a/man/tar_seed_set.Rd b/man/tar_seed_set.Rd index 1786a909b..5049074f6 100644 --- a/man/tar_seed_set.Rd +++ b/man/tar_seed_set.Rd @@ -32,4 +32,8 @@ sample(10) tar_seed_set(seed) sample(10) } -\concept{seeds} +\seealso{ +Other pseudo-random number generation: +\code{\link{tar_seed_get}()} +} +\concept{pseudo-random number generation} diff --git a/man/tar_source.Rd b/man/tar_source.Rd index 6d1bc41d6..6397a7acd 100644 --- a/man/tar_source.Rd +++ b/man/tar_source.Rd @@ -93,7 +93,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_store}()} } \concept{utilities} diff --git a/man/tar_store.Rd b/man/tar_store.Rd index fbb8c3824..871c8d4cd 100644 --- a/man/tar_store.Rd +++ b/man/tar_store.Rd @@ -46,7 +46,6 @@ Other utilities: \code{\link{tar_path_store}()}, \code{\link{tar_path_target}()}, \code{\link{tar_path}()}, -\code{\link{tar_seed}()}, \code{\link{tar_source}()} } \concept{utilities} diff --git a/tests/testthat/test-tar_seed.R b/tests/testthat/test-tar_seed.R index 55fb20a0f..a7e0275bd 100644 --- a/tests/testthat/test-tar_seed.R +++ b/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") }) diff --git a/tests/testthat/test-tar_seed_get.R b/tests/testthat/test-tar_seed_get.R new file mode 100644 index 000000000..dc5a3710c --- /dev/null +++ b/tests/testthat/test-tar_seed_get.R @@ -0,0 +1,16 @@ +tar_test("tar_seed_get() outside a pipeline", { + expect_equal(tar_seed_get(), 1L) + expect_equal(tar_seed_get(default = 123L), 123L) +}) + +tar_test("tar_seed_get() inside a pipeline", { + x <- target_init("x", quote(targets::tar_seed_get(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_get(default = 1L))) + local_init(pipeline_init(list(x)))$run() + expect_identical(target_read_value(x)$object, seed) +})