defineModule: Define a new module.
In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

defineModule

R Documentation

Define a new module.

Description

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

Usage

defineModule(sim, x)

## S4 method for signature '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 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`.

Author(s)

Alex Chubaty

Examples


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

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

SpaDES.core documentation built on Nov. 10, 2023, 5:08 p.m.