R/setupProject.R
setupFunctions.RdSource the functions supplied to setupProject() so they are available
to subsequent setup* steps and to the user's session.
setupFunctions(
functions,
name,
sideEffects,
paths,
overwrite = FALSE,
envir = parent.frame(),
callingEnv = sys.frame(-2),
verbose = getOption("Require.verbose", 1L),
dots,
defaultDots,
...
)A set of function definitions to be used within setupProject.
These will be returned as a list element. If function definitions require non-base
packages, prefix the function call with the package e.g., terra::rast. When
using setupProject, the functions argument is evaluated after paths, so
it cannot be used to define functions that help specify paths.
Optional. If supplied, the name of the project. If not supplied, an
attempt will be made to extract the name from the paths[["projectPath"]].
If this is a GitHub project, then it should indicate the full Github
repository and branch name, e.g., "PredictiveEcology/WBI_forecasts@ChubatyPubNum12"
Optional. This can be an expression or one or more file names or
a code chunk surrounded by {...}.
If a non-text file name is specified (e.g., not .txt or .R currently),
these files will simply be downloaded, using their relative path as specified
in the github notation. They will be downloaded or accessed locally at that
relative path.
If these file names represent scripts (*.txt or .R), this/these will be parsed and evaluated,
but nothing is returned (i.e., any assigned objects are not returned). This is intended
to be used for operations like cloud authentication or configuration functions
that are run for their side effects only.
a list with named elements, specifically, modulePath, projectPath,
packagePath and all others that are in SpaDES.core::setPaths()
(i.e., inputPath, outputPath, scratchPath, cachePath, rasterTmpDir).
Each of these has a sensible default, which will be overridden but any user
supplied values.
See setup.
Logical vector or character vector, however, only getModule will respond
to a vector of values. If length-one TRUE, then all files that were previously downloaded
will be overwritten throughout the sequence of setupProject – including those downloaded via sideEffects.
If a length > 1 logical or character vector, these will be passed to getModule: only the named
modules will be overwritten or the logical vector of the modules.
NOTE: if length > 1, no other file specified anywhere in setupProject will be
overwritten except a module matching the vector names() (because
only setupModules is currently responsive to a vector). To have fine grained control,
a user can just manually delete a file, then rerun.
The environment where setupProject is called from. Defaults to
parent.frame() which should be fine in most cases and user shouldn't need
to set this
The environment from which the function was called. Defaults to sys.frame(-2)
which represents the case where the inner setup* functions are called inside
setupProject, which was called by a user.
Numeric or logical indicating how verbose should the function
be. If -1 or -2, then as little verbosity as possible. If 0 or FALSE,
then minimal outputs; if 1 or TRUE, more outputs; 2 even more. NOTE: in
Require function, when verbose >= 2, also returns details as if
returnDetails = TRUE (for backwards compatibility).
Any other named objects passed as a list a user might want for other elements.
A named list of any arbitrary R objects.
These can be supplied to give default values to objects that
are otherwise passed in with the ..., i.e., not specifically named for these
setup* functions. If named objects are supplied as top-level arguments, then
the defaultDots will be overridden. This can be particularly useful if the
arguments passed to ... do not always exist, but rely on external e.g., batch
processing to optionally fill them. See examples.
further named arguments that acts like objects, but a different
way to specify them. These can be anything. The general use case
is to create the objects that are would be passed to
SpaDES.core::simInit, or SpaDES.core::simInitAndSpades,
(e.g. studyAreaName or objects) or additional objects to be passed to the simulation
(in older versions of SpaDES.core, these were passed as a named list
to the objects argument). Order matters. These are sequentially evaluated,
and also any arguments that are specified before the named arguments
e.g., name, paths, will be evaluated prior to any of the named arguments,
i.e., "at the start" of the setupProject.
If placed after the first named argument, then they will be evaluated at the
end of the setupProject, so can access all the packages, objects, etc.
setupFunctions returns NULL. All functions will be placed in envir.
setupFunctions will source the functions supplied, with a parent environment being
the internal temporary environment of the setupProject, i.e., they will have
access to all the objects in the call.
setupProject() for the high-level wrapper, setup_family for an overview.