orderly_develop_start {orderly} | R Documentation |
Develop an orderly report
Description
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
|
parameters |
Parameters passed to the report. A named list of
parameters declared in the |
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 |
locate |
Logical, indicating if the configuration should be
searched for. If |
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
|
use_draft |
Should draft reports be used for dependencies?
This should be used only in development. Valid values are
logical ( |
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 |
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.
Value
A character vector with the full path to the directory, invisibly.
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)
# Copy the required dependencies over, in this case from a draft report
orderly::orderly_run("other", list(nmin = 0), root = path, echo = FALSE)
orderly::orderly_develop_start("use_dependency", root = path,
use_draft = TRUE)
# Files have been copied across into the source directory
orderly::orderly_develop_status("use_dependency", root = path)
# 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)