Return the vertices and edges of a pipeline dependency graph.
Source:R/tar_network.R
tar_network.Rd
Analyze the pipeline defined in the target script file
(default: _targets.R
)
and return the vertices and edges of the directed acyclic graph
of dependency relationships.
Usage
tar_network(
targets_only = FALSE,
names = NULL,
shortcut = FALSE,
allow = NULL,
exclude = NULL,
outdated = TRUE,
reporter = targets::tar_config_get("reporter_outdated"),
seconds_reporter = targets::tar_config_get("seconds_reporter"),
callr_function = callr::r,
callr_arguments = targets::tar_callr_args_default(callr_function, reporter),
envir = parent.frame(),
script = targets::tar_config_get("script"),
store = targets::tar_config_get("store")
)
Arguments
- targets_only
Logical, whether to restrict the output to just targets (
FALSE
) or to also include imported global functions and objects.- names
Names of targets. The graph visualization will operate only on these targets (and unless
shortcut
isTRUE
, all the targets upstream as well). Selecting a small subgraph usingnames
could speed up the load time of the visualization. Unlikeallow
,names
is invoked before the graph is generated. Set to NULL to check/run all the targets (default). Otherwise, the object supplied tonames
should be atidyselect
expression likeany_of()
orstarts_with()
fromtidyselect
itself, ortar_described_as()
to select target names based on their descriptions.- shortcut
Logical of length 1, how to interpret the
names
argument. Ifshortcut
isFALSE
(default) then the function checks all targets upstream ofnames
as far back as the dependency graph goes. IfTRUE
, then the function only checks the targets innames
and uses stored metadata for information about upstream dependencies as needed.shortcut = TRUE
increases speed if there are a lot of up-to-date targets, but it assumes all the dependencies are up to date, so please use with caution. Also,shortcut = TRUE
only works if you setnames
.- allow
Optional, define the set of allowable vertices in the graph. Unlike
names
,allow
is invoked only after the graph is mostly resolved, so it will not speed up execution. Set toNULL
to allow all vertices in the pipeline and environment (default). Otherwise, you can supply symbols ortidyselect
helpers likestarts_with()
.- exclude
Optional, define the set of exclude vertices from the graph. Unlike
names
,exclude
is invoked only after the graph is mostly resolved, so it will not speed up execution. Set toNULL
to exclude no vertices. Otherwise, you can supply symbols ortidyselect
helpers likeany_of()
andstarts_with()
.- outdated
Logical, whether to show colors to distinguish outdated targets from up-to-date targets. (Global functions and objects still show these colors.) Looking for outdated targets takes a lot of time for large pipelines with lots of branches, and setting
outdated
toFALSE
is a nice way to speed up the graph if you only want to see dependency relationships and pipeline progress.- reporter
Character of length 1, name of the reporter to user. Controls how messages are printed as targets are checked. Choices:
"silent"
: print nothing."forecast"
: print running totals of the checked and outdated targets found so far.
- seconds_reporter
Positive numeric of length 1 with the minimum number of seconds between times when the reporter prints progress messages to the R console.
- callr_function
A function from
callr
to start a fresh clean R process to do the work. Set toNULL
to run in the current session instead of an external process (but restart your R session just before you do in order to clear debris out of the global environment).callr_function
needs to beNULL
for interactive debugging, e.g.tar_option_set(debug = "your_target")
. However,callr_function
should not beNULL
for serious reproducible work.- callr_arguments
A list of arguments to
callr_function
.- envir
An environment, where to run the target R script (default:
_targets.R
) ifcallr_function
isNULL
. Ignored ifcallr_function
is anything other thanNULL
.callr_function
should only beNULL
for debugging and testing purposes, not for serious runs of a pipeline, etc.The
envir
argument oftar_make()
and related functions always overrides the current value oftar_option_get("envir")
in the current R session just before running the target script file, so whenever you need to set an alternativeenvir
, you should always set it withtar_option_set()
from within the target script file. In other words, if you calltar_option_set(envir = envir1)
in an interactive session and thentar_make(envir = envir2, callr_function = NULL)
, thenenvir2
will be used.- script
Character of length 1, path to the target script file. Defaults to
tar_config_get("script")
, which in turn defaults to_targets.R
. When you set this argument, the value oftar_config_get("script")
is temporarily changed for the current function call. Seetar_script()
,tar_config_get()
, andtar_config_set()
for details about the target script file and how to set it persistently for a project.- store
Character of length 1, path to the
targets
data store. Defaults totar_config_get("store")
, which in turn defaults to_targets/
. When you set this argument, the value oftar_config_get("store")
is temporarily changed for the current function call. Seetar_config_get()
andtar_config_set()
for details about how to set the data store path persistently for a project.
Value
A list with two data frames: vertices
and edges
. The
vertices data frame has one row per target and columns with the
the type of the target or object (stem, branch, map, cross, function,
or object), each target's description, and each target's status
(up to date, outdated, dispatched, completed, canceled, or errored),
as well as metadata if available (seconds of runtime, bytes of
storage, and number of dynamic branches).
The edges data frame has one row for every edge and columns to
and
from
to mark the starting and terminating vertices.
Dependency graph
The dependency graph of a pipeline is a directed acyclic graph (DAG)
where each node indicates a target or global object and each directed
edge indicates where a downstream node depends on an upstream node.
The DAG is not always a tree, but it never contains a cycle because
no target is allowed to directly or indirectly depend on itself.
The dependency graph should show a natural progression of work from
left to right. targets
uses static code analysis to create the graph,
so the order of tar_target()
calls in the _targets.R
file
does not matter. However, targets does not support self-referential
loops or other cycles. For more information on the dependency graph,
please read
https://books.ropensci.org/targets/targets.html#dependencies.
See also
Other inspect:
tar_deps()
,
tar_manifest()
,
tar_outdated()
,
tar_sitrep()
,
tar_validate()
Examples
if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
library(targets)
library(tarchetypes)
tar_option_set()
list(
tar_target(y1, 1 + 1),
tar_target(y2, 1 + 1, description = "y2 info"),
tar_target(z, y1 + y2, description = "z info")
)
}, ask = FALSE)
tar_network(targets_only = TRUE)
})
}