orderly_run: Run a report

Description

Run a report. This will create a new directory in drafts/<reportname>, copy your declared resources there, extract data from databases (if you are using them), run your script and check that all expected artefacts were created. Once successfully run you can use orderly_commit to move it to the archive directory.

Usage

orderly_run(name, parameters = NULL, envir = NULL, root = NULL,
  locate = TRUE, echo = TRUE, id_file = NULL, fetch = FALSE,
  ref = NULL, message = NULL)

Arguments

name

Name of the report to run (see orderly_list).

parameters

Parameters passed to the report. A named list of parameters declared in the orderly.yml.

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 if locate is TRUE.

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 orderly_config.yml file.

echo

Print the result of running the R code to the console

id_file

Write the identifier into a file

fetch

Logical, indicating if git should be fetched before checking out the reference ref.

ref

A git reference to use for this run (see Details)

message

An optional character string containing a message explaining why the report was run

Value

The id of the newly created report

Details

If ref is provided then before running a report orderly will try to check out (as a detached HEAD) ref, interpreted as a git reference. This can be a commit, tag, or a branch name (including remote). The working directory must be clean according to git status and this will require some careful use of .gitignore to exclude draft, archive, data and orderly.sqlite. The git tree will revert back to the original branch at completion (or failure to complete) the report.

Parameters are passed to the report as a named list, for example

id <- orderly::orderly_run("other", list(nmin = 0.2), root = path)

(see the examples). The names of the parameters (here, nmin) must correspond to declared parameters in the orderly.yml. It is an error if parameters without a default are omitted, and it is an error if unknown parameters are provided.

Examples

Run this code

# NOT RUN {
path <- orderly::orderly_example("demo")

# To run most reports, provide the report name (and the path if
# not running in the working directory, as is the case here):
id <- orderly::orderly_run("minimal", root = path)

# Every report gets a unique identifier, based on the time (it is
# ISO 8601 time with random hex appended to end)
id

# After being run, a report is a "draft" and will exist in the
# drafts directory:
orderly::orderly_list_drafts(root = path)

# Draft reports are always stored in the path
# <root>/draft/<name>/<id>, so we have
dir(file.path(path, "draft", "minimal", id))

# which contains the files when the report was run.

# If a report has parameters, then these must be passed in as a
# named list.
id <- orderly::orderly_run("other", list(nmin = 0.2), root = path)

# These parameters can be used in SQL queries or in the report
# code.
# }