Pack up and run orderly reports to run elsewhere. By using these functions you can safely copy all requirements of an orderly report into a portable archive and run them on another machine (perhaps a cluster or HPC), then import the completed archive into your orderly tree. There is considerable overhead to using these functions (mostly due to transport costs) so they are intended primarily for very computationally demanding patterns.
Usage
orderly_bundle_pack(
path,
name,
parameters = NULL,
envir = NULL,
root = NULL,
locate = TRUE,
message = NULL,
instance = NULL,
remote = NULL,
tags = NULL
)
orderly_bundle_run(path, workdir = tempfile(), echo = TRUE, envir = NULL)
orderly_bundle_import(path, root = NULL, locate = TRUE)
orderly_bundle_list(path)Arguments
- path
A path, whose interpretation depends on the function:
orderly_bundle_pack: A directory to save bundles to. If it does not exist it will be created for you.orderly_bundle_run: The path to the packed bundle (a zip file created byorderly_bundle_pack)orderly_bundle_import: The path to unpack and import (a zip file created byorderly_bundle_run)orderly_bundle_list: The path to a directory that might contain either incomplete or complete bundles (created by eitherorderly_bundle_packororderly_bundle_run)- name
Name of the report to pack (see
orderly_list(). A leadingsrc/will be removed if provided, allowing easier use of autocomplete.- parameters
Parameters passed to the report. A named list of parameters declared in the
orderly.yml. Each parameter must be a scalar character, numeric, integer or logical.- envir
The parent of the environment that will be used to evaluate the report script; by default a new environment will be made with the global environment as the parent.
- root
The path to an orderly root directory, or
NULL(the default) to search for one from the current working directory iflocateisTRUE.- locate
Logical, indicating if the configuration should be searched for. If
TRUEandconfigis not given, then orderly looks in the working directory and up through its parents until it finds anorderly_config.ymlfile.- message
An optional character string containing a message explaining why the report was run
- instance
Select instance of the source database to be used, where multiple instances are configured. Use a single unnamed character string to indicate an instance to match. If given, then this name must be present in all databases where instances are listed in
orderly_config.yml, and will be ignored by all database where instances are not given. See the "orderly" vignette for further information.- remote
Remote to use to resolve dependencies. Use this in order to run a report with the same dependencies as are available on a remote server, particularly when using
id = "latest". Note that this is not the same as runningorderly_pull_dependencies(), thenorderly_runwithremote = NULL, as the pull/run approach will use the latest report in your archive but theremote = "remote"approach will use the latest approach in the remote archive (which might be less recent).- tags
Character vector of tags to add to the report. Tags are immutable and cannot be removed once the report is run. Tags added here will be in addition to any tags listed in the
tags:field inorderly.ymland must be present inorderly_config.yml.- workdir
The path in which to run bundles. If it does not exist it will be created for you. The completed bundle will be saved in this directory as
<id>.zip.- echo
Print the result of running the R code to the console
Value
For orderly_bundle_pack and
orderly_bundle_run, a list with elements path (the
path to the bundle) and id (its orderly id). For
orderly_bundle_list a data.frame with key information
about the report in the bundles (id, name, parameters, status,
time). The function orderly_bundle_import is called for
its side effect only and does not return anything useful.
Examples
path <- orderly::orderly_example("minimal")
# A working directory to export bundles to:
workdir <- tempfile()
# Pack up the "example" report to go:
res <- orderly::orderly_bundle_pack(workdir, "example", root = path)
#> [ name ] example
#> [ id ] 20230621-105024-920cdc5c
#> [ start ] 2023-06-21 10:50:24
#> [ data ] source => dat: 20 x 2
#> [ bundle pack ] 20230621-105024-920cdc5c
# The return value is a list with the id and the path to the zip
# file created:
res
#> $id
#> [1] "20230621-105024-920cdc5c"
#>
#> $path
#> [1] "/tmp/RtmpGRuIRx/file471bb49bc8/20230621-105024-920cdc5c.zip"
#>
# A list of reports bundled in this directory and their status
orderly::orderly_bundle_list(workdir)
#> id name parameters status time
#> 1 20230621-105024-920cdc5c example incomplete 2023-06-21 10:50:24
# Run the bundle (this would ordinarily be done on another computer)
zip <- orderly::orderly_bundle_run(res$path, workdir)
#> [ start ] 2023-06-21 10:50:24
#>
#> > png("mygraph.png")
#>
#> > par(mar = c(15, 4, 0.5, 0.5))
#>
#> > barplot(setNames(dat$number, dat$name), las = 2)
#>
#> > dev.off()
#> agg_png
#> 2
#> [ end ] 2023-06-21 10:50:24
#> [ elapsed ] Ran report in 0.0115788 secs
#> [ artefact ] mygraph.png: 175369b2bcf4115f343c8ad746c0c072
zip
#> $id
#> [1] "20230621-105024-920cdc5c"
#>
#> $path
#> [1] "/tmp/RtmpGRuIRx/file471bb49bc8/20230621-105024-920cdc5c.zip"
#>
#> $filename
#> [1] "20230621-105024-920cdc5c.zip"
#>
# The status has now been updated to reflect the status
orderly::orderly_bundle_list(workdir)
#> id name parameters status time
#> 1 20230621-105024-920cdc5c example complete 2023-06-21 10:50:24
# We can import this into the orderly tree
orderly::orderly_bundle_import(zip$path, root = path)
#> [ import ] example:20230621-105024-920cdc5c
# This has now been included in your orderly archive and the
# workdir can be safely deleted
unlink(workdir, recursive = TRUE)
orderly::orderly_list_archive(path)
#> name id
#> 1 example 20230621-105024-920cdc5c