Specify a new module's metadata as well as object and package dependencies. Packages are loaded during this call. Any or all of these can be missing, with missing values set to defaults
defineModule(sim, x)
# S4 method for simList,list
defineModule(sim, x)A simList object from which to extract element(s) or in which to replace element(s).
A list with a number of named elements, referred to as the metadata. See details.
Updated simList object.
name | Module name. Must match the filename (without the .R extension).
This is currently not parsed by SpaDES;
it is for human readers only. |
description | Brief description of the module. This is currently not parsed by SpaDES; it is for human readers only. |
keywords | Author-supplied keywords. This is currently not parsed by SpaDES; it is for human readers only. |
childModules | If this contains any character vector, then it will
be treated as a parent module. If this is a parent module,
then only this list entry will be read. For normal,
i.e., 'child modules', this should be character(0) or
NA.
If a character vector is provided, then these must be the
names of the modules located in the same file path as this
parent module that will be loaded during the simInit. |
authors | Module author information (as a vector of person()
objects. This is currently not parsed by SpaDES;
it is for human readers only. |
version | Module version number (will be coerced to numeric_version()
if a character or numeric are supplied).
The module developer should update manually this with each change
that is made to the module. See https://semver.org/
for a widely accepted standard for version numbering. |
spatialExtent | The spatial extent of the module supplied via
terra::ext. This is currently unimplemented.
Once implemented, this should define what spatial region this
module is scientifically reasonable to be used in. |
timeframe | Vector (length 2) of POSIXt dates specifying the temporal extent
of the module. Currently unimplemented.
Once implemented, this should define what time frame this
module is scientifically reasonable to be used for. |
timeunit | Time scale of the module (e.g., "day", "year"). If this is
not specified, then .timeunitDefault() will be used.
It indicates what '1' unit of time
means for this module. SpaDES interprets this
and if modules have different timeunit values
then it will correctly schedule each module, using the
smallest (currently the default) timeunit as the
'model' timeunit in the spades call. |
citation | List of character strings specifying module citation information.
Alternatively, a list of filenames of .bib or similar files.
This is currently not parsed by SpaDES;
it is for human readers only. |
documentation | List of filenames referring to module documentation sources. This is currently not parsed by SpaDES; it is for human readers only. |
loadOrder | Named list of length 0, 1, or 2, with names being after and before.
Each element should be a character string/vector naming 1 or more
modules that will be loaded after or before this module.
after and before are used from the current module's
perspective. So, list(after = c("Biomass_core")) means that
this module must come after "Biomass_core". This should only
be used when there are cyclic dependencies (2 or more modules
have 1 or more objects that is in both inputObjects and
outputObjects of both/all modules) between this module
and other modules. In cases where the dependencies are not cyclic,
SpaDES is able to resolve the order correctly. |
reqdPkgs | List of R package names required by the module. These
packages will be loaded when simInit is called.
Require::Require() will be used internally
to load if available, and install if not available.
Because Require::Require() can also download from
GitHub.com, these packages can specify package names stored
on GitHub, e.g., "PredictiveEcology/SpaDES.core@development". |
parameters | A data.frame specifying the parameters used in the module.
Usually produced by rbind-ing the outputs of multiple
defineParameter() calls. These parameters indicate
the default values that will be used unless a module user
overrides them with the params argument in the
simInit() call. The minimum and maximum are
currently used by the SpaDES.shiny::shine function and the
POM function, and they should indicate the range
of values that are reasonable scientifically. |
inputObjects | A data.frame specifying the data objects expected as
inputs to the module,
with columns objectName (class character),
objectClass (class character),
sourceURL (class character), and other
(currently spades does nothing with this column).
This data.frame identifies the objects that are expected,
but does not do any loading of that object into the simList.
The sourceURL gives the developer the opportunity
to identify the source of a data file that can be used
with the model. This URL will be
used if the user calls downloadData (or
downloadModule(..., data = TRUE). If the raw data
must be modified, the developer can use create a
function called .inputObjects in their module. That
function will be run during the simInit call. The
developer should ensure that if the object is supplied
by the module user as an argument in the simInit, then
the .inputObjects should not be run, i.e., use an
(is.null(sim$xxx))). |
outputObjects | A data.frame specifying the data objects output by
the module, with columns identical to those in
inputObjects. Like inputObjects above,
this only identifies the objects that this module will output
into the simList.
The module developer must create the necessary functions
that will cause these objects to be put into the
simList. |
# \donttest{
## a default version of the defineModule is created with a call to newModule
newModule("test", path = tempdir(), open = FALSE)
#> New module test created at /tmp/RtmpNobduY
#> * edit module code in test.R
#> * write tests for your module code in tests/
#> * describe and document your module in test.Rmd
#> * tell others how to cite your module by editing citation.bib
#> * choose a license for your module; see LICENSE.md
## view the resulting module file
if (interactive()) file.edit(file.path(tempdir(), "test", "test.R"))
# }