Run a report

Run a report. This will create a new directory in drafts/<reportname>, copy your declared resources there, run your script and check that all expected artefacts were created.

Usage

orderly_run(
  name,
  parameters = NULL,
  envir = NULL,
  echo = TRUE,
  search_options = NULL,
  root = NULL,
  locate = TRUE
)

Arguments

name: Name of the report to run. Any leading ./ src/ or trailing / path parts will be removed (e.g., if added by 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 environment that will be used to evaluate the report script; by default we use the global environment, which may not always be what is wanted.
echo: Optional logical to control printing output from source() to the console.
search_options: Optional control over locations, when used with orderly_dependency; converted into a orderly_search_options object, see Details.
root: The path to the root directory, or NULL (the default) to search for one from the current working directory if locate is TRUE. This function does require that the directory is configured for orderly, and not just outpack (see orderly_init for details).
locate: Logical, indicating if the configuration should be searched for. If TRUE and config is not given, then orderly looks in the working directory and up through its parents until it finds an .outpack directory

Value

The id of the created report (a string)

Locations used in dependency resolution

If your packet depends on other packets, you will want to control the locations that are used to find appropriate packets. The control for this is passed through this function and not as an argument to orderly_dependency because this is a property of the way that a packet is created and not of a packet itself; importantly different users may have different names for their locations so it makes little sense to encode the location name into the source code. Alternatively, you want to use different locations in different contexts (initial development where you want to include local copies packets as possible dependencies vs resolving dependencies only as they would be resolved on one of your locations!

Similarly, you might want to include packets that are known by other locations but are not currently downloaded onto this machine - pulling these packets in could take anything from seconds to hours depending on their size and the speed of your network connection (but not pulling in the packets could mean that your packet fails to run).

To allow for control over this you can pass in an argument search_options, which is a orderly_search_options object, and allows control over the names of the locations to use, whether metadata should be refreshed before we pull anything and if packets that are not currently downloaded should be considered candidates.

This has no effect when running interactively, in which case you can specify the search options (root specific) with orderly_interactive_set_search_options

Which packets might be selected from locations?

The search_options argument controls where outpack searches for packets with the given query and if anything might be moved over the network (or from one outpack archive to another). By default everything is resolved locally only; that is we can only depend on packets that are unpacked within our current archive. If you pass a search_options argument that contains allow_remote = TRUE (see orderly_search_options then packets that are known anywhere are candidates for using as dependencies and if needed we will pull the resolved files from a remote location. Note that even if the packet is not locally present this might not be needed - if you have the same content anywhere else in an unpacked packet we will reuse the same content without re-fetching.

If pull_metadata = TRUE, then we will refresh location metadata before pulling, and the location argument controls which locations are pulled from.

Equivalence to the old `use_draft` option

The above location handling generalises orderly (v1)'s old use_draft option, in terms of the location argument to orderly2::orderly_search_options`:

use_draft = TRUE is location = "local"
use_draft = FALSE is location = c(...) where you should provide all locations except local (setdiff(orderly2::orderly_location_list(), "local"))
use_draft = "newer" is location = NULL

(this last option was the one most people preferred so is the new default behaviour). In addition, you could resolve dependencies as they currently exist on production right now with the options:

location = "production", pull_metadata = TRUE, require_unpacked = FALSE

which updates your current metadata from production, then runs queries against only packets known on that remote, then depends on them even if you don't (yet) have them locally. This functionality was never available in orderly version 1, though we had intended to support it.

Running with a source tree separate from outpack root

Sometimes it is useful to run things from a different place on disk to your outpack root. We know of two cases where this has come up:

when running reports within a runner on a server, we make a clean clone of the source tree at a particular git reference into a new temporary directory and then run the report there, but have it insert into an orderly repo at a fixed and non-temporary location.
we have a user for whom it is more convenient torun their report on a hard drive but store the archive and metadata on a (larger) shared drive.

In the first instance, we have a source path at <src> which contains the file orderly_config.yml and the directory src/ with our source reports, and a separate path <root> which contains the directory .outpack/ with all the metadata - it may also have an unpacked archive, and a .git/ directory depending on the configuration. (Later this will make more sense once we support a "bare" outpack layout.)

Manually setting report source directory

To manually set the report source directory, you will need to set the path of the directory as the ORDERLY_REPORT_SRC environment variable.

Examples

# Create a simple example:
path <- orderly2::orderly_example("default")
#> ✔ Created orderly root at '/tmp/RtmprnCT52/file171620ae99bd'

# Run the 'data' task:
orderly2::orderly_run("data", root = path)
#> Error in root_open(root, locate, require_orderly = is.na(env_root_src),     call = environment()): Directory does not exist: '/tmp/RtmprnCT52/file171620ae99bd'

# After running, a finished packet appears in the archive:
fs::dir_tree(path)
#> Error: [ENOENT] Failed to search directory '/tmp/RtmprnCT52/file171620ae99bd': no such file or directory

# and we can query the metadata:
orderly2::orderly_metadata_extract(name = "data", root = path)
#> Error in root_open(root, locate = locate, require_orderly = FALSE, call = environment()): Directory does not exist: '/tmp/RtmprnCT52/file171620ae99bd'