Resolve, default-fill, and apply the path list used by setupProject().
setupPaths(
name,
paths,
inProject,
standAlone = TRUE,
libPaths = NULL,
updateRprofile = getOption("SpaDES.project.updateRprofile", TRUE),
Restart = getOption("SpaDES.project.Restart", FALSE),
overwrite = FALSE,
envir = parent.frame(),
callingEnv = sys.frame(-2),
useGit = getOption("SpaDES.project.useGit", FALSE),
verbose = getOption("Require.verbose", 1L),
dots,
defaultDots,
...
)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"
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.
A logical. If TRUE, then the current directory is
inside the paths[["projectPath"]].
A logical. Passed to Require::standAlone. This keeps all
packages installed in a project-level library, if TRUE. Default is TRUE.
Deprecated. Use paths = list(packagePath = ...).
Logical. Should the paths$packagePath be set in the .Rprofile
file for this project. Note: if paths$packagePath is within the tempdir(),
then there will be a warning, indicating this won't persist. If the user is
using Rstudio and the paths$projectPath is not the root of the current
Rstudio project, then a warning will be given, indicating the .Rprofile may not
be read upon restart.
Logical or character. If either TRUE or a character,
and if the projectPath is not the current path, and the session is in
RStudio and interactive, it will try to restart Rstudio in the projectPath with
a new Rstudio project. If character, it should represent the filename
of the script that contains the setupProject call that should be copied to
the new folder and opened. If TRUE, it will use the active file as the one
that should be copied to the new projectPath and opened in the Rstudio project.
If successful, this will create an RStudio Project file (and .Rproj.user
folder), restart with a new Rstudio session with that new project and with a root
path (i.e. working directory) set to projectPath. Default is FALSE, and no
RStudio Project is created.
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.
An environment within which to look for objects. If called alone,
the function should use its own internal environment. If called from another
function, e.g., setupProject, then the envir should be the internal
transient environment of that function.
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.
(if not FALSE, then experimental still). There are two levels at which a project
can use GitHub, either the projectPath and/or the modules. Any given
project can have one or the other, or both of these under git control. If "both",
then this function will assume that git submodules will be used for the modules.
A logical or "sub" for submodule. If "sub", then this function
will attempt to clone the identified modules as git submodules. This will only
work if the projectPath is a git repository. If the project is already a git
repository because the user has set that up externally to this function call, then
this function will add the modules as git submodules. If it is not already,
it will use git clone for each module. After git clone or submodule add are run,
it will run git checkout for the named branch and then git pull
to get and change branch for each module, according to its specification in
modules. If FALSE, this function will download modules with getModules.
NOTE: CREATING A
GIT REPOSITORY AT THE PROJECT LEVEL AND SETTING MODULES AS GIT SUBMODULES IS
EXPERIMENTAL. IT IS FINE IF THE PROJECT HAS BEEN MANUALLY SET UP TO BE
A GIT REPOSITORY WITH SUBMODULES: THIS FUNCTION WILL ONLY EVALUTE PATHS. This can
be set with the option(SpaDES.project.useGit = xxx).
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.
setupPaths returns a list of paths that are created. projectPath will be
assumed to be the base of other non-temporary and non-R-library paths. This means
that all paths that are directly used by simInit are assumed to be relative
to the projectPath. If a user chooses to specify absolute paths, then they will
be returned as is. It is also called for its
side effect which is to call setPaths, with each of these paths as an argument.
See table for details. If a user supplies extra paths not useable by SpaDES.core::simInit,
these will added as an attribute ("extraPaths") to the paths element
in the returned object. These will still exist directly in the returned list
if a user uses setupPaths directly, but these will not be returned with
setupProject because setupProject is intended to be used with SpaDES.core::simInit.
In addition, three paths will be added to this same attribute automatically:
projectPath, packagePath, and .prevLibPaths which is the previous value for
.libPaths() before changing to packagePath.
setupPaths will fill in any paths that are not explicitly supplied by the
user as a named list. These paths that can be set are:
projectPath, packagePath, cachePath, inputPath,
modulePath, outputPath, rasterPath, scratchPath, terraPath.
These are grouped thematically into three groups of paths:
projectPath and packagePath affect the project, regardless
of whether a user uses SpaDES modules. cachePath, inputPath, outputPath and
modulePath are all used by SpaDES within module contexts. scratchPath,
rasterPath and terraPath are all "temporary" or "scratch" directories.
| Path | Default if not supplied by user | Effects |
| Project Level Paths | ||
projectPath | if getwd() is name, then just getwd; if not
file.path(getwd(), name) | If current project is not this project
and using Rstudio, then the current
project will close and a new project will
open in the same Rstudio session, unless
Restart = FALSE |
packagePath | file.path(tools::R_user_dir("data"), name, "packages", version$platform, substr(getRversion(), 1, 3)) | appends this path to .libPaths(packagePath),
unless standAlone = TRUE, in which case,
it will set .libPaths(packagePath, include.site = FALSE) to this path |
| —— | ———– | —– |
| Module Level Paths | ||
cachePath | file.path(projectPath, "cache") | options(reproducible.cachePath = cachePath) |
inputPath | file.path(projectPath, "inputs") | options(spades.inputPath = inputPath) |
modulePath | file.path(projectPath, "modules") | options(spades.inputPath = outputPath) |
outputPath | file.path(projectPath, "outputs") | options(spades.inputPath = modulePath) |
| —— | ———– | —– |
| Temporary Paths | ||
scratchPath | file.path(tempdir(), name) | |
rasterPath | file.path(scratchPath, "raster") | sets (rasterOptions(tmpdir = rasterPath)) |
terraPath | file.path(scratchPath, "terra") | sets (terraOptions(tempdir = terraPath)) |
| —— | ———– | —– |
| Other Paths | ||
logPath | file.path(outputPath(sim), "log") | sets options("spades.logPath") accessible by logPath(sim) |
tilePath | Not implemented yet | Not implemented yet |
setupProject() for the high-level wrapper, setup_family for an overview.