docs

R/tar_config_get.R

@@ -8,6 +8,7 @@
 #'   or the default value if the setting is not available.
 #'   The data type of the return value depends on your choice
 #'   of `name`.
+#' @inheritSection tar_meta Storage access
 #' @inheritSection tar_config_set Configuration
 #' @inheritParams tar_config_set
 #' @param name Character of length 1, name of the specific

R/tar_config_set.R

@@ -3,6 +3,7 @@
 #' @family configuration
 #' @description `tar_config_set()` writes special custom settings
 #'   for the current project to an optional YAML configuration file.
+#' @inheritSection tar_meta Storage access
 #' @section Configuration:
 #'   For several key functions like [tar_make()], the
 #'   default values of arguments are controlled though

R/tar_config_unset.R

@@ -6,6 +6,7 @@
 #'   from the optional YAML configuration file.
 #'   After that, [tar_option_get()] will return the original
 #'   default values for those settings for the project.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` (invisibly)
 #' @inheritSection tar_config_set Configuration
 #' @inheritParams tar_config_set

R/tar_crew.R

@@ -4,6 +4,7 @@
 #' @description For the most recent run of the pipeline with [tar_make()]
 #'   where a `crew` controller was started, get summary-level information
 #'   of the workers.
+#' @inheritSection tar_meta Storage access
 #' @return A data frame one row per `crew` worker and the following columns:
 #'   * `controller`: name of the `crew` controller.
 #'   * `launches`: number of times the worker was launched.

R/tar_delete.R

@@ -18,6 +18,7 @@
 #'   For patterns recorded in the metadata, all the branches
 #'   will be deleted. For patterns no longer in the metadata,
 #'   branches are left alone.
+#' @inheritSection tar_meta Storage access
 #' @inheritParams tar_validate
 #' @param names Names of the targets to remove from `_targets/objects/`.
 #'   You can supply symbols

R/tar_destroy.R

@@ -25,6 +25,7 @@
 #'   input/output files tracked with `tar_target(..., format = "file")`).
 #'   The next run of the pipeline will start from scratch,
 #'   and it will not skip any targets.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` (invisibly).
 #' @inheritParams tar_validate
 #' @param destroy Character of length 1, what to destroy. Choices:

R/tar_edit.R

@@ -6,7 +6,7 @@
 #' @details The target script file is an R code file
 #'   that defines the pipeline. The default path is `_targets.R`,
 #'   but the default for the current project
-#'   can be configured with [tar_config_set()].
+#'   can be configured with [tar_config_set()]
 #' @inheritParams tar_validate
 tar_edit <- function(script = targets::tar_config_get("script")) {
   # Covered in tests/interactive/test-tar_edit.R # nolint

R/tar_errored.R

@@ -3,6 +3,7 @@
 #' @family progress
 #' @description List targets whose progress is `"errored"`.
 #' @return A character vector of errored targets.
+#' @inheritSection tar_meta Storage access
 #' @inheritParams tar_progress
 #' @param names Optional, names of the targets. If supplied, the
 #'   function restricts its output to these targets.

R/tar_glimpse.R

@@ -9,6 +9,7 @@
 #'   renders faster. Also, `tar_glimpse()` omits functions and other global
 #'   objects by default (but you can include them with `targets_only = FALSE`).
 #' @inheritSection tar_network Dependency graph
+#' @inheritSection tar_meta Storage access
 #' @return A `visNetwork` HTML widget object.
 #' @inheritParams tar_network
 #' @param targets_only Logical, whether to restrict the output to just targets

R/tar_invalidate.R

@@ -14,6 +14,7 @@
 #'   For patterns recorded in the metadata, all the branches
 #'   will be invalidated. For patterns no longer in the metadata,
 #'   branches are left alone.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` (invisibly).
 #' @inheritParams tar_validate
 #' @param names Names of the targets to remove from the metadata list.

R/tar_load.R

@@ -8,7 +8,7 @@
 #'   [tar_load_everything()] is shorthand for `tar_load(everything())`
 #'   to load all targets.
 #' @return Nothing.
-#' @inheritSection tar_read Limited scope
+#' @inheritSection tar_meta Storage access
 #' @inheritParams tar_load_raw
 #' @param names Names of the targets to load.
 #'   You may supply `tidyselect` helpers like [any_of()] and [starts_with()].

R/tar_load_everything.R

@@ -4,7 +4,6 @@
 #' @description Shorthand for `tar_load(everything())` to load all
 #'   targets with entries in the metadata.
 #' @return Nothing.
-#' @inheritSection tar_read Limited scope
 #' @inheritParams tar_load
 #' @examples
 #' if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN

R/tar_load_globals.R

@@ -13,6 +13,7 @@
 #'   in `tar_option_get("packages")` (default: `(.packages())`)
 #'   using `library()` with `lib.loc` defined in `tar_option_get("library")`
 #'   (default: `NULL`).
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` (invisibly).
 #' @inheritParams tar_config_set
 #' @param envir Environment to source the target script (default: `_targets.R`).

R/tar_load_raw.R

@@ -5,7 +5,7 @@
 #'   Do not use in `knitr` or R Markdown reports with `tarchetypes::tar_knit()`
 #'   or `tarchetypes::tar_render()`.
 #' @return Nothing.
-#' @inheritSection tar_read Limited scope
+#' @inheritSection tar_meta Storage access
 #' @inheritParams tar_read
 #' @param names Character vector, names of the targets to load.
 #'   Names are expected to appear in the metadata in `_targets/meta`.

R/tar_make.R

@@ -8,6 +8,7 @@
 #'   back into R, and see
 #'   <https://docs.ropensci.org/targets/reference/index.html#clean>
 #'   to manage output files.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` except if `callr_function = callr::r_bg()`, in which case
 #'   a handle to the `callr` background process is returned. Either way,
 #'   the value is invisibly returned.

R/tar_make_clustermq.R

@@ -19,6 +19,7 @@
 #'   or <https://books.ropensci.org/targets/hpc.html>.
 #'   `clustermq` is not a strict dependency of `targets`,
 #'   so you must install `clustermq` yourself.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` except if `callr_function = callr::r_bg()`, in which case
 #'   a handle to the `callr` background process is returned. Either way,
 #'   the value is invisibly returned.

R/tar_make_future.R

@@ -10,6 +10,7 @@
 #'   so you must install `future` yourself.
 #' @details To configure `tar_make_future()` with a computing cluster,
 #'   see the `future.batchtools` package documentation.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` except if `callr_function = callr::r_bg()`, in which case
 #'   a handle to the `callr` background process is returned. Either way,
 #'   the value is invisibly returned.

R/tar_manifest.R

@@ -3,6 +3,7 @@
 #' @family inspect
 #' @description Along with [tar_visnetwork()] and [tar_glimpse()],
 #'   `tar_manifest()` helps check that you constructed your pipeline correctly.
+#' @inheritSection tar_meta Storage access
 #' @return A data frame of information about the targets in the pipeline.
 #'   Rows appear in topological order (the order they will run
 #'   without any influence from parallel computing or priorities).

R/tar_mermaid.R

@@ -6,6 +6,7 @@
 #' @details `mermaid.js` is a JavaScript library for constructing
 #'   static visualizations of graphs.
 #' @inheritSection tar_network Dependency graph
+#' @inheritSection tar_meta Storage access
 #' @return A character vector of lines of code of the `mermaid.js` graph.
 #'   You can visualize the graph by copying the text
 #'   into a public online `mermaid.js` editor or a `mermaid` GitHub code chunk

R/tar_meta.R

@@ -6,6 +6,18 @@
 #'   [tar_progress()] shows information on targets that are running.
 #'   That is why the number of branches may disagree between [tar_meta()]
 #'   and [tar_progress()] for actively running pipelines.
+#' @inheritSection tar_meta Storage access
+#' @section Storage access:
+#'   Several functions like `tar_make()`, `tar_read()`, `tar_load()`,
+#'   `tar_meta()`, and `tar_progress()` read or modify
+#'   the local data store of the pipeline.
+#'   The local data store is in flux while a pipeline is running,
+#'   and depending on how distributed computing or cloud computing is set up,
+#'   not all targets can even reach it. So please do not call these
+#'   functions from inside a target as part of a running
+#'   pipeline. The only exception is literate programming
+#'   target factories in the `tarchetypes` package such as `tar_render()`
+#'   and `tar_quarto()`.
 #' @return A data frame with one row per target/object and the selected fields.
 #' @inheritParams tar_validate
 #' @param names Optional, names of the targets. If supplied, `tar_meta()`

R/tar_objects.R

@@ -4,6 +4,7 @@
 #' @description List targets currently saved to `_targets/objects/`
 #'   or the cloud. Does not include local files
 #'   with `tar_target(..., format = "file", repository = "local")`.
+#' @inheritSection tar_meta Storage access
 #' @return Character vector of targets saved to `_targets/objects/`.
 #' @inheritParams tar_validate
 #' @param names Optional `tidyselect` selector such as

R/tar_outdated.R

@@ -8,6 +8,7 @@
 #' @details Requires that you define a pipeline
 #'   with a target script file (default: `_targets.R`).
 #'   (See [tar_script()] for details.)
+#' @inheritSection tar_meta Storage access
 #' @return Names of the outdated targets.
 #' @param names Names of the targets. `tar_outdated()` will check
 #'   these targets and all upstream ancestors in the dependency graph.

R/tar_poll.R

@@ -3,6 +3,7 @@
 #' @family progress
 #' @description Print the information in [tar_progress_summary()]
 #'   at regular intervals.
+#' @return `NULL` (invisibly). Called for its side effects.
 #' @inheritParams tar_progress_summary
 #' @param interval Number of seconds to wait between iterations
 #'   of polling progress.

R/tar_process.R

@@ -11,6 +11,7 @@
 #'   check the status with `tar_pid() %in% ps::ps_pids()`
 #'   before running another call to [tar_make()]
 #'   for the same project.
+#' @inheritSection tar_meta Storage access
 #' @return A data frame with metadata on the most recent main R process
 #'   to orchestrate the targets of the current project.
 #'   The output includes the `pid` of the main process.

R/tar_progress.R

@@ -3,6 +3,7 @@
 #' @family progress
 #' @description Read a project's target progress data for the most recent
 #'   run of [tar_make()] or similar. Only the most recent record is shown.
+#' @inheritSection tar_meta Storage access
 #' @return A data frame with one row per target and the following columns:
 #'   * `name`: name of the target.
 #'   * `type`: type of target: `"stem"` for non-branching targets,

R/tar_prune.R

@@ -5,6 +5,7 @@
 #' @description Remove target values from `_targets/objects/` and the cloud
 #'   and remove target metadata from `_targets/meta/meta`
 #'   for targets that are no longer part of the pipeline.
+#' @inheritSection tar_meta Storage access
 #' @details
 #'   `tar_prune()` is useful if you recently worked through
 #'   multiple changes to your project and are now trying to

R/tar_read.R

@@ -4,14 +4,7 @@
 #' @description Read a target's return value from its file in
 #'   `_targets/objects/`. For dynamic files (i.e. `format = "file"`)
 #'   the paths are returned.
-#' @section Limited scope:
-#'   `tar_read()` and `tar_load()`
-#'   are only for exploratory analysis and literate programming,
-#'   and `tar_read_raw()` and `tar_load_raw()` are only
-#'   for exploratory analysis. `targets` automatically
-#'   loads the correct dependencies into memory when the pipeline
-#'   is running, so invoking these functions
-#'   from inside a target is rarely advisable.
+#' @inheritSection tar_meta Storage access
 #' @return The target's return value from its file in
 #'   `_targets/objects/`, or the paths to the custom files and directories
 #'   if `format = "file"` was set.

R/tar_read_raw.R

@@ -7,7 +7,7 @@
 #' @return The target's return value from its file in
 #'   `_targets/objects/`, or the paths to the custom files and directories
 #'   if `format = "file"` was set.
-#' @inheritSection tar_read Limited scope
+#' @inheritSection tar_meta Storage access
 #' @inheritParams tar_validate
 #' @param name Character, name of the target to read.
 #' @param branches Integer of indices of the branches to load

R/tar_source.R

@@ -8,6 +8,7 @@
 #'   `tar_source()` recursively looks for files ending
 #'   in `.R` or `.r`, and it runs each with
 #'   `eval(parse(text = readLines(script_file, warn = FALSE)), envir)`.
+#' @inheritSection tar_meta Storage access
 #' @return `NULL` (invisibly)
 #' @param files Character vector of file and directory paths
 #'   to look for R scripts to run. Paths must either be absolute

R/tar_visnetwork.R

@@ -4,6 +4,7 @@
 #' @description Visualize the pipeline dependency graph with a `visNetwork`
 #'   HTML widget.
 #' @inheritSection tar_network Dependency graph
+#' @inheritSection tar_meta Storage access
 #' @return A `visNetwork` HTML widget object.
 #' @inheritParams tar_glimpse
 #' @inheritParams tar_network