Develop an orderly report — orderly_develop

The functions orderly_develop_start, orderly_develop_status and orderly_develop_clean provide a workflow for developing a report in much the same way as one might write code outside of orderly. orderly_develop_start will copy all files required (global resources and dependencies) into the report source directory, as well as collect all data and parameters - at this point the directory can be developed in directly. It will also load all declared packages, and source all code files listed in the packages: and sources: sections of your orderly.yml. orderly_develop_status provides information about the status of files in the directory, while orderly_develop_clean deletes all copied files.

Usage

orderly_develop_start(
  name = NULL,
  parameters = NULL,
  envir = parent.frame(),
  root = NULL,
  locate = TRUE,
  instance = NULL,
  use_draft = FALSE,
  remote = NULL
)

orderly_develop_status(name = NULL, root = NULL, locate = TRUE)

orderly_develop_clean(name = NULL, root = NULL, locate = TRUE)

Arguments

name: Name of the report to develop (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.
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).

Value

A character vector with the full path to the directory, invisibly.

Details

These functions are designed to work within a report's src directory. For example, for a report analysis they will alter or report on the directory src/analysis. It is intended that orderly_develop_start can be run repeatedly; doing this will refresh the contents of the directory if upstream files have been updated.

Some degree of care should be used while using these functions.

Because orderly_develop_start copies files into your source tree you should be careful to add these files to your .gitignore files so that they are not included if using git. Rerunning orderly_develop_start will copy a fresh copy of dependencies into your tree, overwriting files that are there without warning.

Repeatedly running orderly_develop_start is "safe", in that it will re-run through the setup steps, but beware that sourcing functions is additive and never subtractive. If you delete (or rename) a function within a source file, it will not be removed from your global environment. Similarly, environment variables will be loaded each time you call this, but no deletions will happen. When in doubt, restart your R session.

Note that these functions are much more permissive as to the state of your orderly.yml than orderly_run() - in particular, they will run, with a message, even if you have not yet defined a script: or any artefacts:.

The orderly_develop_clean function will delete dependencies without warning.

Examples

path <- orderly::orderly_example("demo")

# This report uses a dependency - it requires that the file
# incoming.csv exists.  This file is created from the report 'other'
orderly::orderly_develop_status("use_dependency", root = path)
#>       filename       type present derived
#> 1  orderly.yml    orderly    TRUE   FALSE
#> 2     script.R     script    TRUE   FALSE
#> 3 incoming.csv dependency   FALSE    TRUE
#> 4    graph.png   artefact   FALSE    TRUE
#> 5     info.rds   artefact   FALSE    TRUE

# Copy the required dependencies over, in this case from a draft report
orderly::orderly_run("other", list(nmin = 0), root = path, echo = FALSE)
#> [ name       ]  other
#> [ id         ]  20230621-105028-e7f9ceb9
#> [ sources    ]  functions.R
#> [ parameter  ]  nmin: 0
#> [ start      ]  2023-06-21 10:50:28
#> [ data       ]  source => extract: 20 x 2
#> [ parameter  ]  nmin: 0
#> [ end        ]  2023-06-21 10:50:28
#> [ elapsed    ]  Ran report in 0.02376294 secs
#> [ artefact   ]  summary.csv: 3fac8347e152c84c96e6676413c718b7
#> [ ...        ]  graph.png: a70cdfd037035a0b34e71b921fc9de42
#> [1] "20230621-105028-e7f9ceb9"
orderly::orderly_develop_start("use_dependency", root = path,
                               use_draft = TRUE)
#> [ name       ]  use_dependency
#> [ depends    ]  other@20230621-105028-e7f9ceb9:summary.csv -> incoming.csv

# Files have been copied across into the source directory
orderly::orderly_develop_status("use_dependency", root = path)
#>       filename       type present derived
#> 1  orderly.yml    orderly    TRUE   FALSE
#> 2     script.R     script    TRUE   FALSE
#> 3 incoming.csv dependency    TRUE    TRUE
#> 4    graph.png   artefact   FALSE    TRUE
#> 5     info.rds   artefact   FALSE    TRUE

# The report can then be developed as needed, interactively.  After
# we're happy things can be cleaned up with
orderly::orderly_develop_clean("use_dependency", root = path)
#> [ remove     ]  incoming.csv