SpaDES (version 1.3.1)

defineModule: Define a new module.

Description

Specify a new module's metadata as well as object and package dependecies. Packages are loaded during this call.

Usage

defineModule(sim, x)
# S4 method for .simList,list
defineModule(sim, x)

Arguments

sim

A simList object.

x

A named list containing the parameters used to construct a new .moduleDeps object.

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 http://semver.org/ for a widely accepted standard for version numering.
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 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 refering 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. These packages will be loaded when simInit is called.	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 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.	name

Examples

# NOT RUN {
  # a default version of the defineModule is created with a call to newModule

  newModule("test", path = tempdir())
  # file.edit(file.path(tempdir(), "test", "test.R"))

  # The default defineModule created by newModule is currently (SpaDES version 1.2.0.9010):
  defineModule(sim, list(
    name = "test",
    description = "insert module description here",
    keywords = c("insert key words here"),
    authors = c(person(c("First", "Middle"), "Last",
                     email="[e-mail]", role=c("aut", "cre"))),
    childModules = character(0),
    version = numeric_version("1.2.0.9010"),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 = data.frame(
      objectName = NA_character_,
      objectClass = NA_character_,
      sourceURL = "",
      other = NA_character_,
      stringsAsFactors = FALSE
    ),
    outputObjects = data.frame(
      objectName = NA_character_,
      objectClass = NA_character_,
      other = NA_character_,
      stringsAsFactors = FALSE
    )
  ))

# }
# NOT RUN {
# }