Run a report

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 = NULL,
  parameters = NULL,
  envir = NULL,
  root = NULL,
  locate = TRUE,
  echo = TRUE,
  message = NULL,
  instance = NULL,
  use_draft = FALSE,
  remote = NULL,
  tags = NULL
)

Arguments

name: Name of the report to run (see orderly_list()). A leading src/ will be removed if provided, allowing easier use of autocomplete. Alternatively, the default of NULL is useful if you have already set the working directory to be the source directory.
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 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
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.
use_draft: Should draft reports be used for dependencies? This should be used only in development. Valid values are logical (TRUE, FALSE) or use the string newer to use draft reports where they are newer than archive reports. For consistency, always and never are equivalent to TRUE and FALSE, respectively.
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 running orderly_pull_dependencies(), then orderly_run with remote = NULL, as the pull/run approach will use the latest report in your archive but the remote = "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 in orderly.yml and must be present in orderly_config.yml.

Value

The id of the newly created report

Details

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.

Environment variables that are created in orderly_envir.yml will be available while the report runs. Those that begin with ORDERLY_ will be saved into the orderly_run.rds within the $env section (except for any that match the patterns "TOKEN", "PAT" or "PASS").

Examples

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)
#> [ name       ]  minimal
#> [ id         ]  20230621-105037-a888d8b4
#> [ start      ]  2023-06-21 10:50:37
#> [ data       ]  source => dat: 20 x 2
#> 
#> > 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:37
#> [ elapsed    ]  Ran report in 0.01624155 secs
#> [ artefact   ]  mygraph.png: 175369b2bcf4115f343c8ad746c0c072

# Every report gets a unique identifier, based on the time (it is
# ISO 8601 time with random hex appended to end)
id
#> [1] "20230621-105037-a888d8b4"

# After being run, a report is a "draft" and will exist in the
# drafts directory:
orderly::orderly_list_drafts(root = path)
#>      name                       id
#> 1 minimal 20230621-105037-a888d8b4

# Draft reports are always stored in the path
# <root>/draft/<name>/<id>, so we have
dir(file.path(path, "draft", "minimal", id))
#> [1] "mygraph.png"     "orderly.yml"     "orderly_run.rds" "script.R"       

# 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)
#> [ name       ]  other
#> [ id         ]  20230621-105037-b6d52021
#> [ sources    ]  functions.R
#> [ parameter  ]  nmin: 0.2
#> [ start      ]  2023-06-21 10:50:37
#> [ data       ]  source => extract: 19 x 2
#> [ parameter  ]  nmin: 0.2
#> 
#> > extract$number <- extract$number + rnorm(1)
#> 
#> > write.csv(extract, "summary.csv", row.names = TRUE)
#> 
#> > png("graph.png")
#> 
#> > par(mar = c(15, 4, 0.5, 0.5))
#> 
#> > do_plot(extract)
#> 
#> > dev.off()
#> agg_png 
#>       2 
#> [ end        ]  2023-06-21 10:50:37
#> [ elapsed    ]  Ran report in 0.01738548 secs
#> [ artefact   ]  summary.csv: 08a4566d063098080bfd318f675926f2
#> [ ...        ]  graph.png: 9d98e56ce7726a1523c1b03eb0e4efb4

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

Usage

Arguments

Value

Details

See also

Examples