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)

Arguments

sim

A simList object from which to extract element(s) or in which to replace element(s).

x

A list with a number of named elements, referred to as the metadata. See details.

Value

Updated simList object.

Required metadata elements

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 becharacter(0)
or
NA.
If a character vector is provided, then these must be thenames of the modules located in the same file path as this
parent module that will be loaded during thesimInit
.
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 tonumeric_version
if a character or numeric are supplied).
The module developer should update manually this with each changethat is made to the module. See
http://semver.org/
for a widely accepted standard for version numbering.
spatialExtent
The spatial extent of the module supplied via
raster::extent
. 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"). This
MUST be specified. It indicates what '1' unit of timemeans for this module.
SpaDESinterprets this
and if modules have differenttimeunit
valuesthen it will correctly schedule each module, using the
smallest (currently the default) timeunit as the'model' timeunit in the
spadescall.
citation
List of character strings specifying module citation information.Alternatively, a list of filenames of
.bibor 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.
reqdPkgs
List of R package names required by the module. Thesepackages will be loaded when
simInitis called.
Require
will be used internallyto load if available, and install if not available.
BecauseRequire
can also download fromGitHub.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 byrbind
-ing the outputs of multiple
defineParametercalls. These parameters indicate
the default values that will be used unless a module useroverrides them with the
paramsargument in the
simInit
call. The minimum and maximum arecurrently used by the
SpaDES.shiny::shinefunction and the
POM
function, and they should indicate the rangeof values that are reasonable scientifically.
inputObjects
Adata.frame
specifying the data objects expected asinputs to the module,
with columnsobjectName
(classcharacter
),
objectClass(class
character),
sourceURL
(classcharacter
), andother
(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.
ThesourceURL
gives the developer the opportunityto identify the source of a data file that can be used
with the model. This URL will beused if the user calls
downloadData(or
downloadModule(..., data = TRUE)
. If the raw datamust be modified, the developer can use create a
function called.inputObjects
in their module. Thatfunction will be run during the
simInitcall. The
developer should ensure that if the object is suppliedby 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
Adata.frame
specifying the data objects output bythe module, with columns identical to those in
inputObjects
. LikeinputObjects
above,this only identifies the objects that this module will output
into thesimList
.The module developer must create the necessary functions
that will cause these objects to be put into the
simList.

See also

moduleDefaults

Examples

# NOT RUN {
  ## a default version of the defineModule is created with a call to newModule
  newModule("test", path = tempdir())

  ## view the resulting module file
  if (interactive()) file.edit(file.path(tempdir(), "test", "test.R"))

  # The default defineModule created by newModule is currently (SpaDES version 1.3.1.9044):
  defineModule(sim, list(
    name = "test",
    description = "insert module description here",
    keywords = c("insert key words here"),
    authors = c(person(c("First", "Middle"), "Last",
                       email = "email@example.com", role = c("aut", "cre"))),
    childModules = character(0),
    version = list(SpaDES = "1.3.1.9044", test = "0.0.1"),
    spatialExtent = raster::extent(rep(NA_real_, 4)),
    timeframe = as.POSIXlt(c(NA, NA)),
    timeunit = NA_character_, # e.g., "year",
    citation = list("citation.bib"),
    documentation = list("README.txt", "test.Rmd"),
    reqdPkgs = list(),
    parameters = rbind(
      #defineParameter("paramName", "paramClass", value, min, max,
      # "parameter description")),
      defineParameter(".plotInitialTime", "numeric", NA, NA, NA,
      "This describes the simulation time at which the first plot event should occur"),
      defineParameter(".plotInterval", "numeric", NA, NA, NA,
      "This describes the simulation time at which the first plot event should occur"),
      defineParameter(".saveInitialTime", "numeric", NA, NA, NA,
      "This describes the simulation time at which the first save event should occur"),
      defineParameter(".saveInterval", "numeric", NA, NA, NA,
      "This describes the simulation time at which the first save event should occur")
    ),
    inputObjects = bind_rows(
      expectsInput(objectName = NA_character_, objectClass = NA_character_,
        sourceURL = NA_character_, desc = NA_character_, other = NA_character_)
    ),
    outputObjects = bind_rows(
      createsOutput(objectName = NA_character_, objectClass = NA_character_,
        desc = NA_character_, other = NA_character_)
    )
  ))

# }