Declare orderly parameters. You should only have one call to this
within your file! Typically you'd put the call to this function
very close to the top so that it's easy to scan, though the order
does not really matter. Parameters are scalar atomic values
(e.g. a string, number or boolean) and defaults must be present
literally (i.e., they may not come from a variable
itself). Provide NULL if you do not have a default, in which
case this parameter will be required.
Value
A list of parameters. This list is "strict" so accessing
elements that are not present will throw an error rather than
returning NULL.
Parameters and variables
Prior to orderly 1.99.61, parameters are always available as variables in the execution environment. In order to harmonise the R and Python versions of orderly, we are moving away from this, at least by default. The recommended way of using parameters is to assign it to a variable, for example:
This defines two parameters, debug (with a default) and
replicates (without a default). In the running report, you can
access these by subsetting the pars object (e.g., pars$debug
or pars[["replicates"]]).
To get the old behaviour, do not assign to a variable:
This will create two bindings in the environment (debug and
replicates) but will also generate a deprecation warning and we
will remove support in a release of orderly 2.x. If you really want
the old behaviour, you can achieve it by writing:
Behaviour in interactive sessions
We want you to be able to run through an orderly report
interactively, e.g. via source(), by copy/paste or via the "Run"
or "Source" button in RStudio. This is not very compatible with
use of orderly parameters, because normally you'd provide these to
orderly_run(), so we need a mechanism to get the parameters from
you.
The behaviour differs if you have assigned the result of
orderly_parameters to a variable or are using the (deprecated)
behaviour of exporting parameters as variables.
New behaviour
Suppose that you are assigning to pars. The first time we run
though your code we won't see a value of pars and we'll prompt
for values for each parameter. Those that have default values in
your list will offer these values to make selection of parameters
faster.
On subsequent calls, pars will be present with the values you
used previously; these will be reused. If you want to be
re-prompted, delete pars (i.e., rm("pars")) or assign NULL
(i.e., pars <- NULL).
Old behaviour
This is now deprecated, and you should update your code.
When running interactively (i.e., via source() or running an
orderly file session by copy/paste or in Rstudio), the
orderly_parameters() function has different behaviour, and
this behaviour depends on whether parameters will be exported to the
environment or not.
First, we look in the current environment (most likely the global
environment) for values of your parameters - that is, variables
bound to the names of your parameters. For any parameters that
are not found we will look at the default values and use these
if possible, but if not possible then we will either error or
prompt based on the global option
orderly_interactive_parameters_missing_error. If this is
TRUE, then we will ask you to enter a value for the parameters
(strings will need to be entered with quotes).