Package 'SpaDES.core'

Categorized overview of the SpaDES.core package

Description

This package allows implementation a variety of simulation-type models, with a focus on spatially explicit models. The core simulation components are built upon a discrete event simulation framework that facilitates modularity, and easily enables the user to include additional functionality by running user-built simulation modules. Included are numerous tools to visualize various spatial data formats, as well as non-spatial data. Much work has been done to speed up the core of the DES, with current benchmarking as low as 56 microseconds overhead for each event (including scheduling, sorting event queue, spawning event etc.) or 38 microseconds if there is no sorting (i.e., no sorting occurs under simple conditions). Under most event conditions, therefore, the DES itself will contribute very minimally compared to the content of the events, which may often be milliseconds to many seconds each event.

Bug reports: https://github.com/PredictiveEcology/SpaDES.core/issues

Module repository: https://github.com/PredictiveEcology/SpaDES-modules

Wiki: https://github.com/PredictiveEcology/SpaDES/wiki

Details

1 Spatial discrete event simulation (SpaDES)

A collection of top-level functions for doing spatial discrete event simulation.

1.1 Simulations

There are two workhorse functions that initialize and run a simulation, and third function for doing multiple spades runs:

simInit()	Initialize a new simulation
spades()	Run a discrete event simulation
experiment	In SpaDES.experiment package. Run multiple spades() calls
experiment2	In SpaDES.experiment package. Run multiple spades() calls

1.2 Events

Within a module, important simulation functions include:

scheduleEvent()	Schedule a simulation event
scheduleConditionalEvent()	Schedule a conditional simulation event
removeEvent	Remove an event from the simulation queue (not yet implemented)

2 The simList object class

The principle exported object class is the simList. All SpaDES simulations operate on this object class.

simList()	The simList class

3 simList methods

Collections of commonly used functions to retrieve or set slots (and their elements) of a simList() object are summarized further below.

3.1 Simulation parameters

globals()	List of global simulation parameters.
params()	Nested list of all simulation parameter.
P()	Namespaced version of params() (i.e., do not have to specify module name).

3.2 loading from disk, saving to disk

inputs()	List of loaded objects used in simulation. (advanced)
outputs()	List of objects to save during simulation. (advanced)

3.3 objects in the simList

ls(), objects()	Names of objects referenced by the simulation environment.
ls.str()	List the structure of the simList objects.
objs()	List of objects referenced by the simulation environment.

3.4 Simulation paths

Accessor functions for the paths slot and its elements.

cachePath()	Global simulation cache path.
modulePath()	Global simulation module path.
inputPath()	Global simulation input path.
outputPath()	Global simulation output path.
rasterPath()	Global simulation temporary raster path.
paths()	Global simulation paths (cache, modules, inputs, outputs, rasters).

3.5 Simulation times

Accessor functions for the simtimes slot and its elements.

time()	Current simulation time, in units of longest module.
start()	Simulation start time, in units of longest module.
end()	Simulation end time, in units of longest module.
times()	List of all simulation times (current, start, end), in units of longest module..

3.6 Simulation event queues

Accessor functions for the events and completed slots. By default, the event lists are shown when the simList object is printed, thus most users will not require direct use of these methods.

events()	Scheduled simulation events (the event queue). (advanced)
current()	Currently executing event. (advanced)
completed()	Completed simulation events. (advanced)
elapsedTime()	The amount of clock time that modules & events use

3.7 Modules, dependencies, packages

Accessor functions for the depends, modules, and .loadOrder slots. These are included for advanced users.

depends()	List of simulation module dependencies. (advanced)
modules()	List of simulation modules to be loaded. (advanced)
packages()	Vector of required R libraries of all modules. (advanced)

3.8 simList environment

The simList() has a slot called .xData which is an environment. All objects in the simList are actually in this environment, i.e., the simList is not a list. In R, environments use pass-by-reference semantics, which means that copying a simList object using normal R assignment operation (e.g., sim2 <- sim1), will not copy the objects contained within the .xData slot. The two objects (sim1 and sim2) will share identical objects within that slot. Sometimes, this not desired, and a true copy is required.

envir()	Access the environment of the simList directly (advanced)
copy()	Deep copy of a simList. (advanced)

3.9 Checkpointing

Accessor method	Module	Description
checkpointFile()	checkpoint	Name of the checkpoint file. (advanced)
checkpointInterval()	checkpoint	The simulation checkpoint interval. (advanced)

3.10 Progress Bar

progressType()	.progress	Type of graphical progress bar used. (advanced)
progressInterval()	.progress	Interval for the progress bar. (advanced)

4 Module operations

4.1 Creating, distributing, and downloading modules

Modules are the basic unit of SpaDES. These are generally created and stored locally, or are downloaded from remote repositories, including our SpaDES-modules repository on GitHub.

checksums()	Verify (and optionally write) checksums for a module's data files.
downloadModule()	Open all modules nested within a base directory.
getModuleVersion()	Get the latest module version # from module repository.
newModule()	Create new module from template.
newModuleDocumentation()	Create empty documentation for a new module.
openModules()	Open all modules nested within a base directory.
moduleMetadata()	Shows the module metadata.
zipModule()	Zip a module and its associated files.

4.2 Module metadata

Each module requires several items to be defined. These comprise the metadata for that module (including default parameter specifications, inputs and outputs), and are currently written at the top of the module's .R file.

defineModule()	Define the module metadata
defineParameter()	Specify a parameter's name, value and set a default
expectsInput()	Specify an input object's name, class, description, sourceURL and other specifications
createsOutput()	Specify an output object's name, class, description and other specifications

There are also accessors for many of the metadata entries:

timeunit()	Accesses metadata of same name
citation()	Accesses metadata of same name
documentation()	Accesses metadata of same name
reqdPkgs()	Accesses metadata of same name
inputObjects()	Accesses metadata of same name
outputObjects()	Accesses metadata of same name

4.3 Module dependencies

Once a set of modules have been chosen, the dependency information is automatically calculated once simInit is run. There are several functions to assist with dependency information:

depsEdgeList()	Build edge list for module dependency graph
depsGraph()	Build a module dependency graph using igraph

5 Module functions

A collection of functions that help with making modules can be found in the suggested SpaDES.tools package, and are summarized below.

5.1 Spatial spreading/distances methods

Spatial contagion is a key phenomenon for spatially explicit simulation models. Contagion can be modelled using discrete approaches or continuous approaches. Several SpaDES.tools functions assist with these:

SpaDES.tools::adj()	An optimized (i.e., faster) version of terra::adjacent()
SpaDES.tools::cir()	Identify pixels in a circle around a SpatialPoints*() object
directionFromEachPoint()	Fast calculation of direction and distance surfaces
SpaDES.tools::distanceFromEachPoint()	Fast calculation of distance surfaces
SpaDES.tools::rings()	Identify rings around focal cells (e.g., buffers and donuts)
SpaDES.tools::spokes()	Identify outward radiating spokes from initial points
SpaDES.tools::spread()	Contagious cellular automata
SpaDES.tools::spread2()	Contagious cellular automata, different algorithm, more robust
SpaDES.tools::wrap()	Create a torus from a grid

5.2 Spatial agent methods

Agents have several methods and functions specific to them:

SpaDES.tools::crw()	Simple correlated random walk function
SpaDES.tools::heading()	Determines the heading between ⁠SpatialPoints*⁠
quickPlot::makeLines()	Makes SpatialLines object for, e.g., drawing arrows
move()	A meta function that can currently only take "crw"
specificNumPerPatch()	Initiate a specific number of agents per patch

5.3 GIS operations

In addition to the vast amount of GIS operations available in R (mostly from contributed packages such as sf, terra, (also sp, raster), maps, maptools and many others), we provide the following GIS-related functions:

equalExtent()	Assess whether a list of extents are all equal

5.4 'Map-reduce'–type operations

These functions convert between reduced and mapped representations of the same data. This allows compact representation of, e.g., rasters that have many individual pixels that share identical information.

SpaDES.tools::rasterizeReduced()	Convert reduced representation to full raster.

5.5 Colours in ⁠Raster*⁠ objects

We likely will not want the default colours for every map. Here are several helper functions to add to, set and get colours of ⁠Raster*⁠ objects:

setColors()	Set colours for plotting ⁠Raster*⁠ objects
getColors()	Get colours in a ⁠Raster*⁠ objects
divergentColors()	Create a colour palette with diverging colours around a middle

5.6 Random Map Generation

It is often useful to build dummy maps with which to build simulation models before all data are available. These dummy maps can later be replaced with actual data maps.

SpaDES.tools::neutralLandscapeMap()	Creates a random map using Gaussian random fields
SpaDES.tools::randomPolygons()	Creates a random polygon with specified number of classes

5.7 Checking for the existence of objects

SpaDES modules will often require the existence of objects in the simList. These are helpers for assessing this:

checkObject()	Check for a existence of an object within a simList
reproducible::checkPath()	Checks the specified filepath for formatting consistencies

5.8 SELES-type approach to simulation

These functions are essentially skeletons and are not fully implemented. They are intended to make translations from SELES (https://www.gowlland.ca/). You must know how to use SELES for these to be useful:

agentLocation()	Agent location
SpaDES.tools::initiateAgents()	Initiate agents into a SpatialPointsDataFrame
numAgents()	Number of agents
probInit()	Probability of initiating an agent or event
transitions()	Transition probability

5.9 Miscellaneous

Functions that may be useful within a SpaDES context:

SpaDES.tools::inRange()	Test whether a number lies within range ⁠[a,b]⁠
layerNames()	Get layer names for numerous object classes
numLayers()	Return number of layers
paddedFloatToChar()	Wrapper for padding (e.g., zeros) floating numbers to character

6 Caching simulations and simulation components

Simulation caching uses the reproducible package.

Caching can be done in a variety of ways, most of which are up to the module developer. However, the one most common usage would be to cache a simulation run. This might be useful if a simulation is very long, has been run once, and the goal is just to retrieve final results. This would be an alternative to manually saving the outputs.

See example in spades(), achieved by using cache = TRUE argument.

reproducible::Cache()	Caches a function, but often accessed as argument in spades()
reproducible::showCache()	Shows information about the objects in the cache
reproducible::clearCache()	Removes objects from the cache
reproducible::keepCache()	Keeps only the objects described

A module developer can build caching into their module by creating cached versions of their functions.

7 Plotting

Much of the underlying plotting functionality is provided by quickPlot.

There are several user-accessible plotting functions that are optimized for modularity and speed of plotting:

Commonly used:

Plot()	The workhorse plotting function

Simulation diagrams:

eventDiagram()	Gantt chart representing the events in a completed simulation.
moduleDiagram()	Network diagram of simplified module (object) dependencies.
objectDiagram()	Sequence diagram of detailed object dependencies.

Other useful plotting functions:

clearPlot()	Helpful for resolving many errors
clickValues()	Extract values from a raster object at the mouse click location(s)
clickExtent()	Zoom into a raster or polygon map that was plotted with Plot()
clickCoordinates()	Get the coordinates, in map units, under mouse click
dev()	Specify which device to plot on, making a non-RStudio one as default
newPlot()	Open a new default plotting device
rePlot()	Re-plots all elements of device for refreshing or moving plot

8 File operations

In addition to R's file operations, we have added several here to aid in bulk loading and saving of files for simulation purposes:

loadFiles()	Load simulation objects according to a file list
rasterToMemory()	Read a raster from file to RAM
saveFiles()	Save simulation objects according to outputs and parameters

9 Sample modules included in package

Several dummy modules are included for testing of functionality. These can be found with file.path(find.package("SpaDES.core"), "sampleModules").

randomLandscapes	Imports, updates, and plots several raster map layers
caribouMovement	A simple agent-based (a.k.a., individual-based) model
fireSpread	A simple model of a spatial spread process

10 Package options

SpaDES packages use the following options() to configure behaviour:

• spades.browserOnError: If TRUE, the default, then any error rerun the same event with debugonce called on it to allow editing to be done. When that browser is continued (e.g., with 'c'), then it will save it reparse it into the simList and rerun the edited version. This may allow a spades call to be recovered on error, though in many cases that may not be the correct behaviour. For example, if the simList gets updated inside that event in an iterative manner, then each run through the event will cause that iteration to occur. When this option is TRUE, then the event will be run at least 3 times: the first time makes the error, the second time has debugonce and the third time is after the error is addressed. TRUE is likely somewhat slower.

• reproducible.cachePath: The default local directory in which to cache simulation outputs. Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/cache⁠).

• spades.inputPath: The default local directory in which to look for simulation inputs. Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/inputs⁠).

• spades.debug: The default debugging value debug argument in spades(). Default is TRUE.

• spades.lowMemory: If true, some functions will use more memory efficient (but slower) algorithms. Default FALSE.

• spades.moduleCodeChecks: Should the various code checks be run during simInit. These are passed to codetools::checkUsage(). Default is given by the function, plus these :list(suppressParamUnused = FALSE, suppressUndefined = TRUE, suppressPartialMatchArgs = FALSE, suppressNoLocalFun = TRUE, skipWith = TRUE).

• spades.modulePath: The default local directory where modules and data will be downloaded and stored. Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/modules⁠).

• spades.moduleRepo: The default GitHub repository to use when downloading modules via downloadModule. Default "PredictiveEcology/SpaDES-modules".

• spades.nCompleted: The maximum number of completed events to retain in the completed event queue. Default 1000L.

• spades.outputPath: The default local directory in which to save simulation outputs. Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/outputs⁠).

• spades.recoveryMode: If this a numeric greater than 0 or TRUE, then the discrete event simulator will take a snapshot of the objects in the simList that might change (based on metadata outputObjects for that module), prior to initiating every event. This will allow the user to be able to recover in case of an error or manual interruption (e.g., Esc). If this is numeric, a copy of that number of "most recent events" will be maintained so that the user can recover and restart more than one event in the past, i.e., redo some of the "completed" events. Default is TRUE, i.e., it will keep the state of the simList at the start of the current event. This can be recovered with restartSpades and the differences can be seen in a hidden object in the stashed simList. There is a message which describes how to find that.

• spades.switchPkgNamespaces: Should the search path be modified to ensure a module's required packages are listed first? Default FALSE to keep computational overhead down. If TRUE, there should be no name conflicts among package objects, but it is much slower, especially if the events are themselves fast.

• spades.tolerance: The default tolerance value used for floating point number comparisons. Default .Machine$double.eps^0.5.

• spades.useragent: The default user agent to use for downloading modules from GitHub.com. Default "https://github.com/PredictiveEcology/SpaDES".

Author(s)

Maintainer: Eliot J B McIntire [email protected] (ORCID)

Authors:

• Alex M Chubaty [email protected] (ORCID)

Other contributors:

• Yong Luo [email protected] [contributor]

• Steve Cumming [email protected] [contributor]

• Ceres Barros [email protected] (ORCID) [contributor]

• His Majesty the King in Right of Canada, as represented by the Minister of Natural Resources Canada [copyright holder]

See Also

spadesOptions()

---

.addChangedAttr for simList objects

Description

This will evaluate which elements in the simList object changed following this Cached function call. It will add a named character string as an attribute attr(x, ".Cache")$changed, indicating which ones changed. When this function is subsequently called again, only these changed objects will be returned. All other simList objects will remain unchanged.

Usage

## S4 method for signature 'simList'
.addChangedAttr(object, preDigest, origArguments, ...)

Arguments

object	Any R object returned from a function
preDigest	The full, element by element hash of the input arguments to that same function, e.g., from .robustDigest
origArguments	These are the actual arguments (i.e., the values, not the names) that were the source for preDigest
...	Anything passed to methods.

Value

returns the object with attribute added

See Also

reproducible::.addChangedAttr

---

.addTagsToOutput for simList objects

Description

See reproducible::.addTagsToOutput().

Usage

## S4 method for signature 'simList'
.addTagsToOutput(object, outputObjects, FUN, preDigestByClass)

Arguments

object	Any R object returned from a function
outputObjects	Optional character vector indicating which objects to return. This is only relevant for list, environment (or similar) objects
FUN	A function
preDigestByClass	A list, usually from .preDigestByClass

Value

modified object, with attributes added

Author(s)

Eliot McIntire

---

.cacheMessage for simList objects

Description

See reproducible::.cacheMessage().

Usage

## S4 method for signature 'simList'
.cacheMessage(
  object,
  functionName,
  fromMemoise = getOption("reproducible.useMemoise", TRUE),
  verbose = getOption("reproducible.verbose")
)

Arguments

object	Any R object returned from a function
functionName	A character string indicating the function name
fromMemoise	Logical. If TRUE, the message will be about recovery from memoised copy
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠

See Also

reproducible::.cacheMessage

---

.checkCacheRepo for simList objects

Description

See reproducible::.checkCacheRepo().

Usage

## S4 method for signature 'list'
.checkCacheRepo(object, create = FALSE)

Arguments

object	Any R object returned from a function
create	Logical. If TRUE, then it will create the path for cache.

Value

character string representing a directory path to the cache repo

See Also

reproducible::.checkCacheRepo

---

File extensions map

Description

How to load various types of files in R.

This function has two roles:

1. to proceed with the loading of files that are in a simList; or

2. as a shortcut to simInit(inputs = filelist).

A data.frame with information on how to load various types of files in R, containing the columns:

• exts: the file extension;

• fun: the function to use for files with this file extension;

• package: the package from which to load fun.

Usage

.fileExtensions()

loadFiles(sim, filelist, ...)

## S4 method for signature 'simList,missing'
loadFiles(sim, filelist, ...)

## S4 method for signature 'missing,ANY'
loadFiles(sim, filelist, ...)

## S4 method for signature 'missing,missing'
loadFiles(sim, filelist, ...)

.saveFileExtensions()

Arguments

sim	simList object.
filelist	list or data.frame to call loadFiles directly from the filelist as described in Details
...	Additional arguments.

Value

data.frame of file extension, package, and function mappings

the modified sim, invisibly.

data.frame

Note

Generally not intended to be used by users.

Author(s)

Eliot McIntire and Alex Chubaty

See Also

inputs()

Examples

library(SpaDES.core)

# Load random maps included with package
filelist <- data.frame(
  files = dir(getMapPath(tempdir()), full.names = TRUE),
  functions = "rasterToMemory",
  package = "SpaDES.core"
)
sim1 <- loadFiles(filelist = filelist) # loads all the maps to sim1 simList

# Second, more sophisticated. All maps loaded at time = 0, and the last one is reloaded
#  at time = 10 and 20 (via "intervals").
# Also, pass the single argument as a list to all functions...
#  specifically, when add "native = TRUE" as an argument to the raster function
files <- dir(getMapPath(tempdir()), full.names = TRUE)
arguments <- I(rep(list(lyrs = 1), length(files)))
filelist <- data.frame(
   files = files,
   functions = "terra::rast",
   objectName = NA,
   arguments = arguments,
   loadTime = 0,
   intervals = c(rep(NA, length(files)-1), 10)
)

sim2 <- loadFiles(filelist = filelist) # only does the time = 0 loading; see next
end(sim2) <- 10
sim2 <- spades(sim2) # loads the object at time 10

# if we extend the end time and continue running, it will load an object scheduled
#  at time = 10, and it will also schedule a new object loading at 20 because
#  interval = 10
end(sim2) <- 20
sim2 <- spades(sim2) # loads the percentPine map 2 more times, once at 10, once at 20

---

Find simList in a nested list

Description

This is recursive, so it will find the all simLists even if they are deeply nested.

Usage

.findSimList(x)

Arguments

x	any object, used here only when it is a list with at least one simList in it

---

Guess package of a function

Description

Guess package of a function

Usage

.guessPkgFun(bsf)

Arguments

bsf	character. A function name

Value

character. The package and function name as "pkg::bsf"

---

.parseElems for simList class objects

Description

See quickPlot::.parseElems().

Usage

## S4 method for signature 'simList'
.parseElems(tmp, elems, envir)

Arguments

tmp	A evaluated object
elems	A character string to be parsed
envir	An environment

Value

An object, parsed from a character string and an environment.

See Also

quickPlot::.parseElems

---

Pre-digesting method for simList

Description

Takes a snapshot of simList objects.

Usage

## S4 method for signature 'simList'
.preDigestByClass(object)

Arguments

object

Any R object returned from a function

Details

See reproducible::.preDigestByClass().

Value

character vector corresponding to the names of objects stored in the .xData slot

Author(s)

Eliot McIntire

See Also

reproducible::.preDigestByClass

---

.prepareOutput for simList objects

Description

See reproducible::.prepareOutput().

Usage

## S4 method for signature 'simList'
.prepareOutput(object, cachePath, ...)

Arguments

object	Any R object returned from a function
cachePath	A repository used for storing cached objects. This is optional if Cache is used inside a SpaDES module.
...	Anything passed to methods.

Value

the modified object

See Also

reproducible::.prepareOutput

---

The SpaDES.core variable to switch between quick and robust checking

Description

A variable that can be use by module developers and model users to switch between a quick check of functions like downloadData, Cache. The module developer must actually use this in their code.

Usage

.quickCheck

Format

An object of class logical of length 1.

---

Generate random strings

Description

Generate a vector of random alphanumeric strings each of an arbitrary length.

Usage

.rndstr(n = 1, len = 8)

rndstr(n, len, characterFirst)

## S4 method for signature 'numeric,numeric,logical'
rndstr(n, len, characterFirst)

## S4 method for signature 'numeric,numeric,missing'
rndstr(n, len)

## S4 method for signature 'numeric,missing,logical'
rndstr(n, characterFirst)

## S4 method for signature 'missing,numeric,logical'
rndstr(len, characterFirst)

## S4 method for signature 'numeric,missing,missing'
rndstr(n)

## S4 method for signature 'missing,numeric,missing'
rndstr(len)

## S4 method for signature 'missing,missing,logical'
rndstr(characterFirst)

## S4 method for signature 'missing,missing,missing'
rndstr(n, len, characterFirst)

Arguments

n	Number of strings to generate (default 1). Will attempt to coerce to integer value.
len	Length of strings to generate (default 8). Will attempt to coerce to integer value.
characterFirst	Logical, if TRUE, then a letter will be the first character of the string (useful if being used for object names).

Value

Character vector of random strings.

Author(s)

Alex Chubaty and Eliot McIntire

Examples

set.seed(11)
rndstr()
rndstr(len = 10)
rndstr(characterFirst = FALSE)
rndstr(n = 5, len = 10)
rndstr(n = 5)
rndstr(n = 5, characterFirst = TRUE)
rndstr(len = 10, characterFirst = TRUE)
rndstr(n = 5, len = 10, characterFirst = TRUE)

---

.robustDigest for simList objects

Description

This is intended to be used within the Cache function, but can be used to evaluate what a simList would look like once it is converted to a repeatably digestible object.

Usage

## S4 method for signature 'simList'
.robustDigest(object, .objects, length, algo, quick, classOptions)

Arguments

object	an object to digest.
.objects	Character vector of objects to be digested. This is only applicable if there is a list, environment (or similar) with named objects within it. Only this/these objects will be considered for caching, i.e., only use a subset of the list, environment or similar objects. In the case of nested list-type objects, this will only be applied outermost first.
length	Numeric. If the element passed to Cache is a Path class object (from e.g., asPath(filename)) or it is a Raster with file-backing, then this will be passed to digest::digest, essentially limiting the number of bytes to digest (for speed). This will only be used if quick = FALSE. Default is getOption("reproducible.length"), which is set to Inf.
algo	The algorithms to be used; currently available choices are md5, which is also the default, sha1, crc32, sha256, sha512, xxhash32, xxhash64, murmur32, spookyhash, blake3, crc32c, xxh3_64, and xxh3_128.
quick	Logical or character. If TRUE, no disk-based information will be assessed, i.e., only memory content. See Details section about quick in Cache().
classOptions	Optional list. This will pass into .robustDigest for specific classes. Should be options that the .robustDigest knows what to do with.

Details

See reproducible::.robustDigest(). This method strips out stuff from a simList class object that would make it otherwise not reproducibly digestible between sessions, operating systems, or machines. This will likely still not allow identical digest results across R versions.

Author(s)

Eliot McIntire

See Also

reproducible::.robustDigest()

---

.tagsByClass for simList objects

Description

See reproducible::.tagsByClass(). Adds current moduleName, eventType, eventTime, and ⁠function:spades⁠ as userTags.

Usage

## S4 method for signature 'simList'
.tagsByClass(object)

Arguments

object

Any R object returned from a function

Author(s)

Eliot McIntire

See Also

reproducible::.tagsByClass

---

Methods for .wrap and .unwrap

Description

Methods for .wrap and .unwrap

Usage

## S3 method for class 'simList'
.wrap(
  obj,
  cachePath,
  preDigest,
  drv = getOption("reproducible.drv", NULL),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose"),
  outputObjects = NULL,
  ...
)

## S3 method for class '.simDeps'
.wrap(obj, ...)

## S3 method for class '.simDeps'
.unwrap(obj, ...)

## S3 method for class '.moduleDeps'
.wrap(obj, ...)

## S3 method for class '.moduleDeps'
.unwrap(obj, ...)

## S3 method for class 'simList'
.unwrap(
  obj,
  cachePath,
  cacheId,
  drv = getOption("reproducible.drv", NULL),
  conn = getOption("reproducible.conn", NULL),
  ...
)

Arguments

obj	Any arbitrary R object.
cachePath	A repository used for storing cached objects. This is optional if Cache is used inside a SpaDES module.
preDigest	The list of preDigest that comes from CacheDigest of an object
drv	an object that inherits from DBIDriver, or an existing DBIConnection object (in order to clone an existing connection).
conn	A DBIConnection object, as returned by dbConnect().
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠
outputObjects	Optional character vector indicating which objects to return. This is only relevant for list, environment (or similar) objects
...	Other arguments. Can be in the form of tagKey = tagValue, such as, class = "numeric" to find all entries that are numerics in the cache. Note: the special cases of cacheId and fun have their own named arguments in these functions. Also can be regexp = xx, where xx is TRUE if the user is passing a regular expression. Otherwise, userTags will need to be exact matches. Default is missing, which is the same as TRUE. If there are errors due to regular expression problem, try FALSE. For cc, it is passed to clearCache, e.g., ask, userTags. For showCache, it can also be sorted = FALSE to return the object unsorted.
cacheId	An optional character vector describing the cacheIds to extract. Only entries with this/these cacheIds will be returned. If useDBI(FALSE), this will also be dramatically faster than using userTags, for a large cache.

Value

The same object as passed into the function, but dealt with so that it can be saved to disk.

---

Extract an intact simList but with subset of objects

Description

This is copies the non-object components of a simList (e.g., events, etc.) then selects only the objects listed in i using Copy(mget(i, envir(sim))) and adds them to the returned simList.

Usage

## S4 method for signature 'simList,character,ANY'
x[i, j, ..., drop = TRUE]

Arguments

x	A simList
i	A character vector of objects to select.
j	Not used.
...	Not used.
drop	Not used.

Value

The [ method returns a complete simList class with all the slots copied from the original, but only the named objects in i are returned.

Author(s)

Eliot McIntire

Examples

s <- simInit()
s$a <- 1
s$b <- 2
s$d <- 3
s[c("a", "d")] # a simList with only 2 objects

---

All equal method for simList objects

Description

This function removes a few attributes that are added internally by SpaDES.core and are not relevant to the all.equal. One key element removed is any time stamps, as these are guaranteed to be different. A possibly very important argument to pass to the ... is check.attributes = FALSE which will allow successful comparisons of many objects that might have pointers.

Usage

## S3 method for class 'simList'
all.equal(target, current, ...)

Arguments

target	R object.
current	other R object, to be compared with target.
...	further arguments for different methods, notably the following two, for numerical comparison:

Value

See base::all.equal()

---

Test whether there should be any plotting from .plots module parameter

Description

This will do all the various tests needed to determine whether plotting of one sort or another will occur. Testing any of the types as listed in Plots() argument types. Only the first 3 letters of the type are required.

Usage

anyPlotting(.plots)

Arguments

.plots

Usually will be the P(sim)$.plots is used within a module.

Value

logical of length 1

---

Append attributes

Description

Ordinary base lists and vectors do not retain their attributes when subsetted or appended. This function appends items to a list while preserving the attributes of items in the list (but not of the list itself).

Usage

append_attr(x, y)

## S4 method for signature 'list,list'
append_attr(x, y)

Arguments

x, y	A list of items with optional attributes.

Details

Similar to updateList but does not require named lists.

Value

An updated list with attributes.

Author(s)

Alex Chubaty and Eliot McIntire

Examples

tmp1 <- list("apple", "banana")
tmp1 <- lapply(tmp1, `attributes<-`, list(type = "fruit"))
tmp2 <- list("carrot")
tmp2 <- lapply(tmp2, `attributes<-`, list(type = "vegetable"))
append_attr(tmp1, tmp2)
rm(tmp1, tmp2)

---

Simple wrapper around data.table::rbindlist

Description

This simply sets defaults to fill = TRUE, and use.names = TRUE.

Usage

bindrows(...)

Arguments

...	one or more data.frame, data.table, or list objects

Value

a data.table object

---

Check for the existence of a remote module

Description

Looks in the remote repo for a module named name.

Usage

checkModule(name, repo)

## S4 method for signature 'character,character'
checkModule(name, repo)

## S4 method for signature 'character,missing'
checkModule(name)

Arguments

name	Character string giving the module name.
repo	GitHub repository name. Default is "PredictiveEcology/SpaDES-modules", which is specified by the global option spades.moduleRepo.

Value

a character vector of module file paths (invisibly).

Author(s)

Eliot McIntire and Alex Chubaty

---

Check for the existence of a module locally

Description

Looks the module path for a module named name, and checks for existence of all essential module files listed below.

Usage

checkModuleLocal(name, path, version)

## S4 method for signature 'character,character,character'
checkModuleLocal(name, path, version)

## S4 method for signature 'character,ANY,ANY'
checkModuleLocal(name, path, version)

Arguments

name	Character string giving the module name.
path	Local path to modules directory. Default is specified by the global option spades.modulePath.
version	Character specifying the desired module version.

Details

• ‘data/CHECKSUMS.txt’

• ‘name.R’

Value

Logical indicating presence of the module (invisibly).

Author(s)

Alex Chubaty

---

Uses "." if getPath not set

Description

Will compare default in spadesOptions to getPaths ... these will be same if use has not set them. For such case, use ".". They will be different if the user has used setPaths. If that is the case, then use getPaths()[["modulePath"]]

Usage

checkModulePath()

---

Check for existence of object(s) referenced by a objects slot of a simList object

Description

Check that a named object exists in the provide simList environment slot, and optionally has desired attributes.

Usage

checkObject(sim, name, object, layer, ...)

## S4 method for signature 'simList,ANY,ANY'
checkObject(sim, name, object, layer, ...)

## S4 method for signature 'simList,character,missing'
checkObject(sim, name, object, layer, ...)

## S4 method for signature 'missing,ANY,ANY'
checkObject(sim, name, object, layer, ...)

Arguments

sim	A simList() object.
name	A character string specifying the name of an object to be checked.
object	An object. This is mostly used internally, or with layer, because it will fail if the object does not exist.
layer	Character string, specifying a layer name in a Raster, if the name is a ⁠Raster*⁠ object.
...	Additional arguments. Not implemented.

Value

Invisibly return TRUE indicating object exists; FALSE if not.

Author(s)

Alex Chubaty and Eliot McIntire

See Also

library().

Examples

sim <- simInit()
sim$a <- 1
sim$b <- list(d = 1)
sim$r <- terra::rast(terra::ext(0,2,0,2), res = 1, vals = 2)
sim$s <- c(sim$r, terra::rast(terra::ext(0,2,0,2), res = 1, vals = 3))
names(sim$s) <- c("r1", "r2") # give layer names
(checkObject(sim, name = "a")) # TRUE
(checkObject(sim, name = "b", layer = "d")) # TRUE
(checkObject(sim, name = "d")) # FALSE
(checkObject(sim, name = "r")) # TRUE
(checkObject(sim, object = sim$s)) # TRUE
(checkObject(sim, object = sim$s, layer = "r1")) # TRUE

---

Check use and existence of parameters passed to simulation.

Description

Checks that all parameters passed are used in a module, and that all parameters used in a module are passed.

Usage

checkParams(sim, coreParams, ...)

## S4 method for signature 'simList,list'
checkParams(sim, coreParams, ...)

Arguments

sim	A simList simulation object.
coreParams	List of default core parameters.
...	Additional arguments. Not implemented.

Value

Invisibly return TRUE indicating object exists; FALSE if not. Sensible messages are produced identifying missing parameters.

Author(s)

Alex Chubaty

---

Simulation checkpoints

Description

Save and reload the current state of the simulation, including the state of the random number generator, by scheduling checkpoint events.

Usage

checkpointFile(sim)

## S4 method for signature 'simList'
checkpointFile(sim)

checkpointFile(sim) <- value

## S4 replacement method for signature 'simList'
checkpointFile(sim) <- value

checkpointInterval(sim)

## S4 method for signature 'simList'
checkpointInterval(sim)

checkpointInterval(sim) <- value

## S4 replacement method for signature 'simList'
checkpointInterval(sim) <- value

doEvent.checkpoint(sim, eventTime, eventType, debug = FALSE)

checkpointLoad(file)

.checkpointSave(sim, file)

Arguments

sim	A simList simulation object.
value	The parameter value to be set (in the corresponding module and param).
eventTime	A numeric specifying the time of the next event.
eventType	A character string specifying the type of event: one of either "init", "load", or "save".
debug	Optional logical flag determines whether sim debug info will be printed (default debug = FALSE).
file	The checkpoint file.

Value

Returns the modified simList object.

Note

Checkpoint files are intended to be used locally, and do not invoke the simulation archiving tools to bundle and subsequently extract simulation files (e.g., file-backed rasters).

RNG save code adapted from: http://www.cookbook-r.com/Numbers/Saving_the_state_of_the_random_number_generator/ and https://stackoverflow.com/q/13997444/1380598

Author(s)

Alex Chubaty

See Also

.Random.seed.

Other functions to access elements of a 'simList' object: .addDepends(), envir(), events(), globals(), inputs(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

---

Calculate checksum for a module's data files

Description

Verify (and optionally write) checksums for data files in a module's ‘data/’ subdirectory. The file ‘data/CHECKSUMS.txt’ contains the expected checksums for each data file. Checksums are computed using reproducible:::.digest, which is simply a wrapper around digest::digest.

Usage

checksums(module, path, ...)

Arguments

module	Character string giving the name of the module.
path	Character string giving the path to the module directory.
...	Passed to reproducible::Checksums(), notably, write, quickCheck, checksumFile and files.

Details

Modules may require data that for various reasons cannot be distributed with the module source code. In these cases, the module developer should ensure that the module downloads and extracts the data required. It is useful to not only check that the data files exist locally but that their checksums match those expected.

Note

In version 1.2.0 and earlier, two checksums per file were required because of differences in the checksum hash values on Windows and Unix-like platforms. Recent versions use a different (faster) algorithm and only require one checksum value per file. To update your ‘CHECKSUMS.txt’ files using the new algorithm:

1. specify your module (moduleName <- "my_module");

2. use a temporary location to ensure all modules get fresh copies of the data (tmpdir <- file.path(tempdir(), "SpaDES_modules"));

3. download your module's data to the temp dir (downloadData(moduleName, tmpdir));

4. initialize a dummy simulation to ensure any 'data prep' steps in the .inputObjects section are run (simInit(modules = moduleName));

5. recalculate your checksums and overwrite the file (checksums(moduleName, tmpdir, write = TRUE));

6. copy the new checksums file to your working module directory (the one not in the temp dir) (file.copy(from = file.path(tmpdir, moduleName, 'data', 'CHECKSUMS.txt'), to = file.path('path/to/my/moduleDir', moduleName, 'data', 'CHECKSUMS.txt'), overwrite = TRUE)).

---

A citation method for SpaDES modules

Description

This is a wrapper around utils::citation() for cases with package is a character string. Otherwise, it takes a simList.

Usage

citation(package, lib.loc = NULL, auto = NULL, module = character())

## S4 method for signature 'simList'
citation(package, lib.loc = NULL, auto = NULL, module = character())

## S4 method for signature 'character'
citation(package, lib.loc = NULL, auto = NULL, module = character())

Arguments

package	For compatibility with utils::citation(). This can be a simList or a character string for a package name.
lib.loc	a character vector with path names of R libraries, or the directory containing the source for package, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.
auto	a logical indicating whether the default citation auto-generated from the package ‘DESCRIPTION’ metadata should be used or not, or NULL (default), indicating that a ‘CITATION’ file is used if it exists, or an object of class "packageDescription" with package metadata (see below).
module	Optional character string indicating which module params should come from.

Value

The citation information for a SpaDES module.

---

Filter objects by class

Description

Based on https://stackoverflow.com/a/5158978/1380598.

Usage

classFilter(x, include, exclude, envir)

## S4 method for signature 'character,character,character,environment'
classFilter(x, include, exclude, envir)

## S4 method for signature 'character,character,character,missing'
classFilter(x, include, exclude)

## S4 method for signature 'character,character,missing,environment'
classFilter(x, include, envir)

## S4 method for signature 'character,character,missing,missing'
classFilter(x, include)

Arguments

x	Character vector of object names to filter, possibly from ls.
include	Class(es) to include, as a character vector.
exclude	Optional class(es) to exclude, as a character vector.
envir	The environment ins which to search for objects. Default is the calling environment.

Value

Vector of object names matching the class filter.

Note

inherits() is used internally to check the object class, which can, in some cases, return results inconsistent with is. See https://stackoverflow.com/a/27923346/1380598. These (known) cases are checked manually and corrected.

Author(s)

Alex Chubaty

Examples

## from local (e.g., function) environment
local({
  e <- environment()
  a <- list(1:10)     # class `list`
  b <- letters        # class `character`
  d <- stats::runif(10)      # class `numeric`
  f <- sample(1L:10L) # class `numeric`, `integer`
  g <- lm( jitter(d) ~ d ) # class `lm`
  h <- glm( jitter(d) ~ d ) # class `lm`, `glm`
  classFilter(ls(), include=c("character", "list"), envir = e)
  classFilter(ls(), include = "numeric", envir = e)
  classFilter(ls(), include = "numeric", exclude = "integer", envir = e)
  classFilter(ls(), include = "lm", envir = e)
  classFilter(ls(), include = "lm", exclude = "glm", envir = e)
  rm(a, b, d, e, f, g, h)
})

## from another environment (can be omitted if .GlobalEnv)
e = new.env(parent = emptyenv())
e$a <- list(1:10)     # class `list`
e$b <- letters        # class `character`
e$d <- stats::runif(10)      # class `numeric`
e$f <- sample(1L:10L) # class `numeric`, `integer`
e$g <- lm( jitter(e$d) ~ e$d ) # class `lm`
e$h <- glm( jitter(e$d) ~ e$d ) # class `lm`, `glm`
classFilter(ls(e), include=c("character", "list"), envir = e)
classFilter(ls(e), include = "numeric", envir = e)
classFilter(ls(e), include = "numeric", exclude = "integer", envir = e)
classFilter(ls(e), include = "lm", envir = e)
classFilter(ls(e), include = "lm", exclude = "glm", envir = e)
rm(a, b, d, f, g, h, envir = e)
rm(e)

---

clearCache for simList objects

Description

This will take the cachePath(object) and pass

Usage

## S4 method for signature 'simList'
clearCache(
  x,
  userTags = character(),
  after = NULL,
  before = NULL,
  fun = NULL,
  cacheId = NULL,
  ask = getOption("reproducible.ask"),
  useCloud = FALSE,
  cloudFolderID = getOption("reproducible.cloudFolderID", NULL),
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose"),
  ...
)

## S4 method for signature 'simList'
showCache(
  x,
  userTags = character(),
  after = NULL,
  before = NULL,
  fun = NULL,
  cacheId = NULL,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose"),
  ...
)

## S4 method for signature 'simList'
keepCache(
  x,
  userTags = character(),
  after = NULL,
  before = NULL,
  ask = getOption("reproducible.ask"),
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose"),
  ...
)

Arguments

x	A simList or a directory containing a valid Cache repository. Note: For compatibility with Cache argument, cachePath can also be used instead of x, though x will take precedence.
userTags	Character vector. If used, this will be used in place of the after and before. Specifying one or more userTag here will clear all objects that match those tags. Matching is via regular expression, meaning partial matches will work unless strict beginning (^) and end ($) of string characters are used. Matching will be against any of the 3 columns returned by showCache(), i.e., artifact, tagValue or tagName. Also, if length(userTags) > 1, then matching is by and. For or matching, use | in a single character string. See examples.
after	A time (POSIX, character understandable by data.table). Objects cached after this time will be shown or deleted.
before	A time (POSIX, character understandable by data.table). Objects cached before this time will be shown or deleted.
fun	An optional character vector describing the function name to extract. Only functions with this/these functions will be returned.
cacheId	An optional character vector describing the cacheIds to extract. Only entries with this/these cacheIds will be returned. If useDBI(FALSE), this will also be dramatically faster than using userTags, for a large cache.
ask	Logical. If FALSE, then it will not ask to confirm deletions using clearCache or keepCache. Default is TRUE
useCloud	Logical. If TRUE, then every object that is deleted locally will also be deleted in the cloudFolderID, if it is non-NULL
cloudFolderID	A googledrive dribble of a folder, e.g., using drive_mkdir(). If left as NULL, the function will create a cloud folder with name from last two folder levels of the cachePath path, : paste0(basename(dirname(cachePath)), "_", basename(cachePath)). This cloudFolderID will be added to options("reproducible.cloudFolderID"), but this will not persist across sessions. If this is a character string, it will treat this as a folder name to create or use on GoogleDrive.
drv	an object that inherits from DBIDriver, or an existing DBIConnection object (in order to clone an existing connection).
conn	A DBIConnection object, as returned by dbConnect().
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠
...	Other arguments. Can be in the form of tagKey = tagValue, such as, class = "numeric" to find all entries that are numerics in the cache. Note: the special cases of cacheId and fun have their own named arguments in these functions. Also can be regexp = xx, where xx is TRUE if the user is passing a regular expression. Otherwise, userTags will need to be exact matches. Default is missing, which is the same as TRUE. If there are errors due to regular expression problem, try FALSE. For cc, it is passed to clearCache, e.g., ask, userTags. For showCache, it can also be sorted = FALSE to return the object unsorted.

Value

A data.table object showing the subset of items in the cache, located at cachePath of the sim object, if sim is provided, or located in cachePath. For clearCache (invoked for its side effect of clearing objects matching userTags, or those between after or before), the returned data.table shows the removed items (invisibly).

---

Convert standard module code into an R package

Description

EXPERIMENTAL – USE WITH CAUTION. This function attempts to convert a SpaDES module to the closest rendition of the same functionality, but in an R package. The main change is that instead of SpaDES.core parsing the functions using custom parsing tools, it will use pkgload::load_all on the package functions. These

Usage

convertToPackage(
  module = NULL,
  path = getOption("spades.modulePath"),
  buildDocuments = TRUE
)

Arguments

module	Character string of module name, without path
path	Character string of modulePath. Defaults to getOption("spades.modulePath").
buildDocuments	A logical. If TRUE, the default, then the documentation will be built, if any exists, using roxygen2::roxygenise.

Details

convertToPackage will:

1. move any functions that were defined within the main module file (moduleName.R) into the R folder, with the same name, but ending with Fns.R;

2. keep the defineModule(...) function call with all the metadata in the same file, moduleName.R, but with all other content removed, i.e., only the defineModule(...) will be here.

3. build documentation from all the roxygen2 tags

4. places one roxygen2 tag, ⁠@export⁠ in front of the doEvent.moduleName function, so that the function can be found by SpaDES.core

5. All other functions will be kept "private", i.e., not exported, unless the user manually adds ⁠@export⁠, as per a normal package

6. will make a DESCRIPTION file from the SpaDES module metadata

7. will make a NAMESPACE file from the roxygen2 tags (e.g., ⁠@export⁠)

A user can continue to use the module code as before, i.e., by editing it and putting browser() etc. It will be parsed during simInit. Because the functions are "in a package", they are automatically namespaced with each other, so that when you want to use a function from that package, there is no need to put a prefix with the package name.

This function does not install anything (e.g., devtools::install). After running this function, simInit will automatically detect that this is now a package and will load the functions (via pkgload::load_all) from the source files. This will have the effect that it emulates the "non-package" behaviour of a SpaDES module exactly. After running this function, current tests show no impact on module behaviour, other than event-level and module-level Caching will show changes and will be rerun. Function-level Caching appears unaffected. In other words, this should cause no changes to running the module code via simInit and spades.

This function will create and fill a minimal DESCRIPTION file. This will leave the defineModule function call as the only code in the main module file. This defineModule and a doEvent.xxx are the only 2 elements that are required for an R package to be considered a SpaDES module. With these changes, the module should still function normally, but will be able to act like an R package, e.g., for writing function documentation with roxygen2, using the testthat infrastructure, etc.

This function is intended to be run once for a module that was created using the "standard" SpaDES module structure (e.g., from a newModule call). There is currently no way to "revert" the changes from R (though it can be done using version control utilities if all files are under version control, e.g., GitHub). Currently SpaDES.core identifies a module as being a package if it has a DESCRIPTION file, or if it has been installed to the .libPaths() e.g., via devtools::install or the like. So one can simply remove the package from .libPaths and delete the DESCRIPTION file and SpaDES.core will treat it as a normal module.

Value

Invoked for its side effects. There will be a new or modified DESCRIPTION file in the root directory of the module. Any functions that were in the main module script (i.e., the .R file whose filename is the name of the module and is in the root directory of the module) will be moved to individual .R files in the R folder. Any function with a dot prefix will have the dot removed in its respective filename, but the function name is unaffected.

Currently, SpaDES.core does not install the package under any circumstances. It will load it via pkgdown::load_all, and optionally (option("spades.moduleDocument" = TRUE)) build documentation via roxygen2::roxygenise within the simInit call. This means that any modifications to source code will be read in during the simInit call, as is the practice when a module is not a package.

invoked for the side effect of converting a module to a package

Reverting

Currently, this is not a reversible process. We recommend trying one module at a time, running your code. If all seems to work, then great. Commit the changes. If things don't seem to work, then revert the changes and continue on as before. Ideally, file a bug report on the SpaDES.core GitHub.com pages.

Currently

Exported functions

The only function that will be exported by default is the doEvent.xxx, where xxx is the module name. If any other module is to be exported, it must be explicitly exported with e.g., ⁠@export⁠, and then building the NAMESPACE file, e.g., via devtools::document(moduleRootPath). NOTE: as long as all the functions are being used inside each other, and they all can be traced back to a call in doEvent.xxx, then there is no need to export anything else.

DESCRIPTION

The DESCRIPTION file that is created (destroying any existing DESCRIPTION file) with this function will have several elements that a user may wish to change. Notably, all packages that were in reqdPkgs in the SpaDES module metadata will be in the Imports section of the DESCRIPTION. To accommodate the need to see these functions, a new R script, imports.R will be created with ⁠@import⁠ for each package in reqdPkgs of the module metadata. However, if a module already has used ⁠@importFrom⁠ for importing a function from a package, then the generic ⁠@import⁠ will be omitted for that (those) package(s). So, a user should likely follow standard R package best practices and use ⁠@importFrom⁠ to identify the specific functions that are required within external packages, thereby limiting function name collisions (and the warnings that come with them).

Other elements of a standard DESCRIPTION file that will be missing or possibly inappropriately short are Title, Description, URL, BugReports.

Installing as a package

There is no need to "install" the source code as a package because simInit will load it on the fly. But, there may be reasons to install it, e.g., to have access to individual functions, help manual, running tests etc. To do this, simply use the devtools::install(pathToModuleRoot). Even if it is installed, simInit will nevertheless run pkgload::load_all to ensure the spades call will be using the current source code.

Examples

if (requireNamespace("ggplot2") && requireNamespace("pkgload") ) {
  tmpdir <- tempdir2()
  newModule("test", tmpdir, open = FALSE)
  convertToPackage("test", path = tmpdir)
  pkgload::load_all(file.path(tmpdir, "test"))
  pkgload::unload("test")
}

---

Copy for simList class objects

Description

Because a simList works with an environment to hold all objects, all objects within that slot are pass-by-reference. That means it is not possible to simply copy an object with an assignment operator: the two objects will share the same objects. As one simList object changes so will the other. When this is not the desired behaviour, use this function.

Usage

## S4 method for signature 'simList'
Copy(object, objects, queues, modules, ...)

Arguments

object	An R object (likely containing environments) or an environment.
objects	Whether the objects contained within the simList environment should be copied. Default TRUE, which may be slow.
queues	Logical. Should the events queues (events, current, completed) be deep copied via data.table::copy()
modules	Logical. Should list of modules be copied.
...	Only used for custom Methods

Details

simList objects can contain a lot of information, much of which could be in pass-by-reference objects (e.g., data.table class), and objects that are file-backed, such as some ⁠Raster*⁠-class objects. For all the objects that are file-backed, it is likely very important to give unique file-backed directories. This should be passed here, which gets passed on to the many methods of Copy in reproducible.

Value

a copy of object

Note

uses capital C, to limit confusion with e.g., data.table::copy().

Author(s)

Eliot McIntire

See Also

reproducible::Copy()

reproducible::Copy()

---

Create a copy of an existing module

Description

Create a copy of an existing module

Usage

copyModule(from, to, path, ...)

## S4 method for signature 'character,character,character'
copyModule(from, to, path, ...)

## S4 method for signature 'character,character,missing'
copyModule(from, to, path, ...)

Arguments

from	The name of the module to copy.
to	The name of the copy.
path	The path to a local module directory. Defaults to the path set by the spades.modulePath option. See setPaths().
...	Additional arguments to file.copy, e.g., overwrite = TRUE.

Value

Invisible logical indicating success (TRUE) or failure (FALSE).

Author(s)

Alex Chubaty

---

Define an output object of a module

Description

Used to specify an output object's name, class, description and other specifications.

Usage

createsOutput(objectName, objectClass, desc, ...)

## S4 method for signature 'ANY,ANY,ANY'
createsOutput(objectName, objectClass, desc, ...)

## S4 method for signature 'character,character,character'
createsOutput(objectName, objectClass, desc, ...)

Arguments

objectName	Character string to define the output object's name.
objectClass	Character string to specify the output object's class.
desc	Text string providing a brief description of the output object. If there are extra spaces or carriage returns, these will be stripped, allowing for multi-line character strings without using paste or multiple quotes.
...	Other specifications of the output object.

Value

A data.frame suitable to be passed to outputObjects in a module's metadata.

Author(s)

Yong Luo

Examples

outputObjects <- bindrows(
  createsOutput(objectName = "outputObject1", objectClass = "character",
                desc = "this is for example"),
  createsOutput(objectName = "outputObject2", objectClass = "numeric",
                desc = "this is for example",
                otherInformation = "I am the second output object")
)

---

Alternative way to define events in SpaDES.core

Description

There are two ways to define what occurs during an event: defining a function called doEvent.moduleName, where moduleName is the actual module name. This approach is the original approach used in SpaDES.core, and it must have an explicit switch statement branching on eventType. The newer approach (still experimental) uses defineEvent(). Instead of creating, doEvent.moduleName(), it creates one function for each event, each with the name doEvent.moduleName.eventName. This may be a little bit cleaner, but both with still work.

Usage

defineEvent(
  sim,
  eventName = "init",
  code,
  moduleName = NULL,
  envir = parent.frame()
)

Arguments

sim	A simList
eventName	Character string of the desired event name to define. Default is "init"
code	An expression that defines the code to execute during the event. This will be captured, and pasted into a new function (doEvent.moduleName.eventName), remaining unevaluated until that new function is called.
moduleName	Character string of the name of the module. If this function is used within a module, then it will try to find the module name.
envir	An optional environment to specify where to put the resulting function. The default will place a function called doEvent.moduleName.eventName in the module function location, i.e., sim$.mods[[moduleName]]. However, if this location does not exist, then it will place it in the parent.frame(), with a message. Normally, especially, if used within SpaDES module code, this should be left missing.

See Also

defineModule(), simInit(), scheduleEvent()

Examples

sim <- simInit()

# these put the functions in the parent.frame() which is .GlobalEnv for an interactive user
defineEvent(sim, "init", moduleName = "thisTestModule", code = {
  sim <- Init(sim) # initialize
  # Now schedule some different event for "current time", i.e., will
  #   be put in the event queue to run *after* this current event is finished
  sim <- scheduleEvent(sim, time(sim), "thisTestModule", "grow")
}, envir = envir(sim))

defineEvent(sim, "grow", moduleName = "thisTestModule", code = {
  sim <- grow(sim) # grow
  # Now schedule this same event for "current time plus 1", i.e., a "loop"
  sim <- scheduleEvent(sim, time(sim) + 1, "thisTestModule", "grow") # for "time plus 1"
})

Init <- function(sim) {
  sim$messageToWorld <- "Now the sim has an object in it that can be accessed"
  sim$size <- 1 # initializes the size object --> this can be anything, Raster, list, whatever
  message(sim$messageToWorld)
  return(sim)   # returns all the things you added to sim as they are in the simList
}

grow <- function(sim) {
  sim$size <- sim$size + 1 # increments the size
  message(sim$size)
  return(sim)
}

# schedule that first "init" event
sim <- scheduleEvent(sim, 0, "thisTestModule", "init")
# Look at event queue
events(sim) # shows the "init" we just added

  # this is skipped when running in automated tests; it is fine in interactive use
  out <- spades(sim)

---

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 this module must be after or before. 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

See Also

moduleDefaults(), defineEvent()

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"))

---

Define a parameter used in a module

Description

Used to specify a parameter's name, value, and set a default. The min and max arguments are ignored by simInit or spades; they are for human use only. To ensure that a user cannot set parameters outside of a range of values, the module developer should use assertions in their module code.

Usage

defineParameter(name, class, default, min, max, desc, ...)

Arguments

name	Character string giving the parameter name.
class	Character string giving the parameter class.
default	The default value to use when none is specified by the user. Non-standard evaluation is used for the expression.
min	With max, used to define a suitable range of values. Non-standard evaluation is used for the expression. These are not tested by simInit or spades. These are primarily for human use, i.e., to tell a module user what values the module expects.
max	With min, used to define a suitable range of values. Non-standard evaluation is used for the expression. These are not tested by simInit or spades. These are primarily for human use, i.e., to tell a module user what values the module expects.
desc	Text string providing a brief description of the parameter. If there are extra spaces or carriage returns, these will be stripped, allowing for multi-line character strings without using paste or multiple quotes.
...	A convenience that allows writing a long desc without having to use paste; any character strings after desc will be pasted together with desc.

Value

a data.frame

Note

Be sure to use the correct NA type: logical (NA), integer (NA_integer_), real (NA_real_), complex (NA_complex_), or character (NA_character_). See NA().

Author(s)

Alex Chubaty and Eliot McIntire

See Also

P(), params() for accessing these parameters in a module.

Examples

parameters = rbind(
  defineParameter("lambda", "numeric", 1.23, desc = "intrinsic rate of increase"),
  defineParameter("P", "numeric", 0.2, 0, 1, "probability of attack"),

  # multi-line desc without quotes on each line -- spaces and carriage returns are stripped
  defineParameter("rate", "numeric", 0.2, 0, 1,
                  "rate of arrival. This is in individuals
                  per day. This can be modified
                  by the user"),
  # multi-line desc with quotes on each line
  defineParameter("times", "numeric", 0.2, 0, 1,
                  desc = "The times during the year ",
                         "that events will occur ",
                         "with possibility of random arrival times")

)


# Create a new module, then access parameters using `P`
tmpdir <- file.path(tempdir(), "test")
checkPath(tmpdir, create = TRUE)

# creates a  new, "empty" module -- it has defaults for everything that is required
newModule("testModule", tmpdir, open = FALSE)

# Look at new module code -- see defineParameter
if (interactive()) file.edit(file.path(tmpdir, "testModule", "testModule.R"))

# initialize the simList
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Some things not necessary in this example, if not interactive (like plotting)
  opts <- if (interactive()) list() else
    options(spades.plot = NA, spades.useRequire = FALSE,
            spades.moduleCodeChecks = FALSE)
  mySim <- simInit(modules = "testModule",
                   paths = list(modulePath = tmpdir))

  # Access one of the parameters -- because this line is not inside a module
  #  function, we must specify the module name. If used within a module,
  #  we can omit the module name
  P(mySim, module = "testModule") # gets all params in a module
  P(mySim, ".useCache", "testModule") # just one param
  options(opts)
}
unlink(tmpdir, recursive = TRUE)

---

Build edge list for module dependency graph

Description

Build edge list for module dependency graph

Usage

depsEdgeList(sim, plot)

## S4 method for signature 'simList,logical'
depsEdgeList(sim, plot)

## S4 method for signature 'simList,missing'
depsEdgeList(sim, plot)

Arguments

sim	A simList object.
plot	Logical indicating whether the edgelist (and subsequent graph) will be used for plotting. If TRUE, duplicated rows (i.e., multiple object dependencies between modules) are removed so that only a single arrow is drawn connecting the modules. Default is FALSE.

Value

A data.table whose first two columns give a list of edges and remaining columns the attributes of the dependency objects (object name, class, etc.).

Author(s)

Alex Chubaty

---

Build a module dependency graph

Description

Build a module dependency graph

Usage

depsGraph(sim, plot)

## S4 method for signature 'simList,logical'
depsGraph(sim, plot)

## S4 method for signature 'simList,missing'
depsGraph(sim)

Arguments

sim	A simList object.
plot	Logical indicating whether the edgelist (and subsequent graph) will be used for plotting. If TRUE, duplicated rows (i.e., multiple object dependencies between modules) are removed so that only a single arrow is drawn connecting the modules. Default is FALSE.

Value

An igraph() object.

Author(s)

Alex Chubaty

---

SpaDES time units

Description

SpaDES modules commonly use approximate durations that divide with no remainder among themselves. For example, models that simulate based on a "week" timestep, will likely want to fall in lock step with a second module that is a "year" timestep. Since, weeks, months, years don't really have this behaviour because of: leap years, leap seconds, not quite 52 weeks in a year, months that are of different duration, etc. We have generated a set of units that work well together that are based on the astronomical or "Julian" year. In an astronomical year, leap years are added within each year with an extra 1/4 day, (i.e., 1 year == 365.25 days); months are defined as year/12, and weeks as year/52.

Usage

dhour(x)

dmin(x)

dday(x)

dyears(x)

## S4 method for signature 'numeric'
dyears(x)

dmonths(x)

## S4 method for signature 'numeric'
dmonths(x)

dweeks(x)

## S4 method for signature 'numeric'
dweeks(x)

dweek(x)

dmonth(x)

dyear(x)

dsecond(x)

dNA(x)

## S4 method for signature 'ANY'
dNA(x)

Arguments

x	numeric. Number of the desired units

Details

When these units are not correct, a module developer can create their own time unit, and create a function to calculate the number of seconds in that unit using the "d" prefix (for duration), following the lubridate package standard: ddecade <- function(x) lubridate::duration(dyear(10)). Then the module developer can use "decade" as the module's time unit.

Value

Number of seconds within each unit

Author(s)

Eliot McIntire

---

Download module data

Description

Download external data for a module if not already present in the module directory, or if there is a checksum mismatch indicating that the file is not the correct one.

Usage

downloadData(
  module,
  path,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE,
  files = NULL,
  checked = NULL,
  urls = NULL,
  children = NULL,
  ...
)

## S4 method for signature 'character,character,logical'
downloadData(
  module,
  path,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE,
  files = NULL,
  checked = NULL,
  urls = NULL,
  children = NULL,
  ...
)

## S4 method for signature 'character,missing,missing'
downloadData(module, quickCheck, overwrite, files, checked, urls, children)

## S4 method for signature 'character,missing,logical'
downloadData(
  module,
  quiet,
  quickCheck,
  overwrite,
  files,
  checked,
  urls,
  children
)

## S4 method for signature 'character,character,missing'
downloadData(
  module,
  path,
  quickCheck,
  overwrite,
  files,
  checked,
  urls,
  children
)

Arguments

module	Character string giving the name of the module.
path	Character string giving the path to the module directory.
quiet	Logical. This is passed to download.file. Default is FALSE.
quickCheck	Logical. If TRUE, then the check with local data will only use file.size instead of digest::digest. This is faster, but potentially much less robust.
overwrite	Logical. Should local data files be overwritten in case they exist? Default is FALSE.
files	A character vector of length 1 or more if only a subset of files should be checked in the ‘CHECKSUMS.txt’ file.
checked	The result of a previous checksums call. This should only be used when there is no possibility that the file has changed, i.e., if downloadData is called from inside another function.
urls	Character vector of urls from which to get the data. This is automatically found from module metadata when this function invoked with SpaDES.core::downloadModule(..., data = TRUE). See also prepInputs().
children	The character vector of child modules (without path) to also run downloadData on
...	Passed to reproducible::preProcess(), e.g., purge

Details

downloadData requires a checksums file to work, as it will only download the files specified therein. Hence, module developers should make sure they have manually downloaded all the necessary data and ran checksums to build a checksums file.

There is an experimental attempt to use the googledrive package to download data from a shared (publicly or with individual users) file. To try this, put the Google Drive URL in sourceURL argument of expectsInputs in the module metadata, and put the filename once downloaded in the objectName argument. If using RStudio Server, you may need to use "out of band" authentication by setting options(httr_oob_default = TRUE). To avoid caching of Oauth credentials, set options(httr_oauth_cache = TRUE).

There is also an experimental option for the user to make a new ‘CHECKSUMS.txt’ file if there is a sourceURL but no entry for that file. This is experimental and should be used with caution.

Value

Invisibly, a list of downloaded files.

Author(s)

Alex Chubaty & Eliot McIntire

See Also

prepInputs(), checksums(), and downloadModule() for downloading modules and building a checksums file.

Examples

# In metadata, each expectsInput has a sourceURL; downloadData will look for
# that and download if it defined; however this sample module has all
# NAs for sourceURL, so nothing to download
modulePath <- getSampleModules(tempdir())
downloadData("caribouMovement", path = modulePath)

---

Download a module from a SpaDES module GitHub repository

Description

Download a .zip file of the module and extract (unzip) it to a user-specified location.

Usage

downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

## S4 method for signature 
## 'character,character,character,character,logical,logical,ANY,logical'
downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

## S4 method for signature 
## 'character,missing,missing,missing,missing,missing,ANY,ANY'
downloadModule(name, quickCheck, overwrite)

## S4 method for signature 'character,ANY,ANY,ANY,ANY,ANY,ANY,ANY'
downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

Arguments

name	Character string giving the module name.
path	Character string giving the location in which to save the downloaded module.
version	The module version to download. (If not specified, or NA, the most recent version will be retrieved.)
repo	GitHub repository name, specified as "username/repo". Default is "PredictiveEcology/SpaDES-modules", which is specified by the global option spades.moduleRepo. Only master/main branches can be used at this point.
data	Logical. If TRUE, then the data that is identified in the module metadata will be downloaded, if possible. Default FALSE.
quiet	Logical. This is passed to download.file (default FALSE).
quickCheck	Logical. If TRUE, then the check with local data will only use file.size instead of digest::digest. This is faster, but potentially much less robust.
overwrite	Logical. Should local module files be overwritten in case they exist? Default FALSE.

Details

Currently only works with GitHub repositories where modules are located in a modules directory in the root tree on the master branch. Module .zip files' names should contain the version number and be inside their respective module folders (see zipModule() for zip compression of modules).

Value

A list of length 2. The first element is a character vector containing a character vector of extracted files for the module. The second element is a tbl with details about the data that is relevant for the function, including whether it was downloaded or not, and whether it was renamed (because there was a local copy that had the wrong file name).

Note

downloadModule uses the GITHUB_PAT environment variable if a value is set. This alleviates 403 errors caused by too-frequent downloads. Generate a GitHub personal access token with no additional permissions at https://github.com/settings/tokens, and add this key to ‘.Renviron’ as ⁠GITHUB_PAT=<your-github-pat-here>⁠.

The default is to overwrite any existing files in the case of a conflict.

Author(s)

Alex Chubaty

See Also

zipModule() for creating module .zip folders.

---

Simulation environment

Description

Accessor functions for the .xData slot, which is the default virtual slot for an S4 class object that inherits from an S3 object (specifically, the simList inherits from environment) in a simList object. These are included for advanced users.

Usage

envir(sim)

## S4 method for signature 'simList'
envir(sim)

envir(sim) <- value

## S4 replacement method for signature 'simList'
envir(sim) <- value

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
value	The object to be stored at the slot.

Details

Currently, only get and set methods are defined. Subset methods are not.

Value

Returns or sets the value of the slot from the simList object.

Author(s)

Alex Chubaty

See Also

SpaDES.core-package, specifically the section 1.2.8 on simList environment.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), events(), globals(), inputs(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

---

Simulation event diagram

Description

Create a Gantt Chart representing the events in a completed simulation. This event diagram is constructed using the completed event list To change the number of events shown, provide an n argument.

Usage

eventDiagram(sim, n, startDate, ...)

## S4 method for signature 'simList,numeric,character'
eventDiagram(sim, n, startDate, ...)

## S4 method for signature 'simList,missing,character'
eventDiagram(sim, n, startDate, ...)

## S4 method for signature 'simList,missing,missing'
eventDiagram(sim, n, startDate, ...)

Arguments

sim	A simList object (typically corresponding to a completed simulation).
n	The number of most recently completed events to plot.
startDate	A character representation of date in YYYY-MM-DD format.
...	Additional arguments passed to mermaid. Useful for specifying height and width.

Details

Simulation time is presented on the x-axis, starting at date startDate. Each module appears in a colour-coded row, within which each event for that module is displayed corresponding to the sequence of events for that module. Note that only the start time of the event is meaningful is these figures: the width of the bar associated with a particular module's event DOES NOT correspond to an event's "duration".

Based on this Stack Overflow answer: https://stackoverflow.com/a/29999300/1380598.

Value

Plots an event diagram as Gantt Chart, invisibly returning a mermaid object.

Note

A red vertical line corresponding to the current date may appear on the figure. This is useful for Gantt Charts generally but can be considered a 'bug' here.

Author(s)

Alex Chubaty

See Also

DiagrammeR::mermaid.

---

Simulation event lists

Description

Accessor functions for the events and completed slots of a simList object. These path functions will extract the values that were provided to the simInit function in the path argument.

Usage

events(sim, unit)

## S4 method for signature 'simList,character'
events(sim, unit)

## S4 method for signature 'simList,missing'
events(sim, unit)

events(sim) <- value

## S4 replacement method for signature 'simList'
events(sim) <- value

conditionalEvents(sim, unit)

## S4 method for signature 'simList,character'
conditionalEvents(sim, unit)

## S4 method for signature 'simList,missing'
conditionalEvents(sim, unit)

current(sim, unit)

## S4 method for signature 'simList,character'
current(sim, unit)

## S4 method for signature 'simList,missing'
current(sim, unit)

current(sim) <- value

## S4 replacement method for signature 'simList'
current(sim) <- value

completed(sim, unit, times = TRUE)

## S4 method for signature 'simList,character'
completed(sim, unit, times = TRUE)

## S4 method for signature 'simList,missing'
completed(sim, unit, times = TRUE)

completed(sim) <- value

## S4 replacement method for signature 'simList'
completed(sim) <- value

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
unit	Character. One of the time units used in SpaDES.
value	The object to be stored at the slot.
times	Logical. Should this function report the clockTime.

Details

By default, the event lists are shown when the simList object is printed, thus most users will not require direct use of these methods.

events	Scheduled simulation events (the event queue).
completed	Completed simulation events.

Currently, only get and set methods are defined. Subset methods are not.

Value

Returns or sets the value of the slot from the simList object.

Note

Each event is represented by a data.table() row consisting of:

• eventTime: The time the event is to occur.

• moduleName: The module from which the event is taken.

• eventType: A character string for the programmer-defined event type.

See Also

SpaDES.core-package, specifically the section 1.2.6 on Simulation event queues.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), globals(), inputs(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

---

Define an input object that the module expects.

Description

Used to specify an input object's name, class, description, source url and other specifications.

Usage

expectsInput(objectName, objectClass, desc, sourceURL, ...)

## S4 method for signature 'ANY,ANY,ANY,ANY'
expectsInput(objectName, objectClass, desc, sourceURL, ...)

## S4 method for signature 'character,character,character,character'
expectsInput(objectName, objectClass, desc, sourceURL, ...)

## S4 method for signature 'character,character,character,missing'
expectsInput(objectName, objectClass, desc, sourceURL, ...)

Arguments

objectName	Character string to define the input object's name.
objectClass	Character string to specify the input object's class.
desc	Text string providing a brief description of the input object. If there are extra spaces or carriage returns, these will be stripped, allowing for multi-line character strings without using paste or multiple quotes.
sourceURL	Character string to specify an URL to reach the input object, default is NA.
...	Other specifications of the input object.

Value

A data.frame suitable to be passed to inputObjects in a module's metadata.

Author(s)

Yong Luo

Examples

inputObjects <- bindrows(
  expectsInput(objectName = "inputObject1", objectClass = "character",
               desc = "this is for example", sourceURL = "not available"),
  expectsInput(objectName = "inputObject2", objectClass = "numeric",
               desc = "this is for example", sourceURL = "not available",
               otherInformation = "I am the second input object")
)

---

Extract a url from module metadata

Description

This will get the sourceURL for the object named.

Usage

extractURL(objectName, sim, module)

## S4 method for signature 'character,missing'
extractURL(objectName, sim, module)

## S4 method for signature 'character,simList'
extractURL(objectName, sim, module)

Arguments

objectName	A character string of the object name in the metadata.
sim	A simList object from which to extract the sourceURL
module	An optional character string of the module name whose metadata is to be used. If omitted, the function will use the currentModule(sim), if defined.

Value

The url.

Author(s)

Eliot McIntire

---

Extract filename (without extension) of a file

Description

Extract filename (without extension) of a file

Usage

fileName(x)

Arguments

x	List or character vector

Value

A character vector.

Author(s)

Eliot McIntire

---

Get copies of sample files for examples and tests

Description

Get copies of sample files for examples and tests

Usage

getMapPath(tmpdir)

getSampleModules(tmpdir)

Arguments

tmpdir

character specifying the path to a temporary directory (e.g., tempdir())

Value

character vector of filepaths to the copied files

---

Find the latest module version from a SpaDES module repository

Description

Modified from https://stackoverflow.com/a/25485782/1380598.

Usage

getModuleVersion(name, repo)

## S4 method for signature 'character,character'
getModuleVersion(name, repo)

## S4 method for signature 'character,missing'
getModuleVersion(name)

Arguments

name	Character string giving the module name.
repo	GitHub repository name, specified as "username/repo". Default is "PredictiveEcology/SpaDES-modules", which is specified by the global option spades.moduleRepo. Only master/main branches can be used at this point.

Details

getModuleVersion extracts a module's most recent version by looking at the module ‘.zip’ files contained in the module directory. It takes the most recent version, based on the name of the zip file.

See the modules vignette for details of module directory structure (https://spades-core.predictiveecology.org/articles/ii-modules.html#module-directory-structure-modulename), and see our SpaDES-modules repo for details of module repository structure (https://github.com/PredictiveEcology/SpaDES-modules).

Value

numeric_version

Author(s)

Alex Chubaty

See Also

zipModule() for creating module ‘.zip’ folders.

---

Get and set global simulation parameters

Description

globals, and the alias G, accesses or sets the "globals" in the simList. This currently is not an explicit slot in the simList, but it is a .globals element in the params slot of the simList.

Usage

globals(sim)

## S4 method for signature 'simList'
globals(sim)

globals(sim) <- value

## S4 replacement method for signature 'simList'
globals(sim) <- value

G(sim)

## S4 method for signature 'simList'
G(sim)

G(sim) <- value

## S4 replacement method for signature 'simList'
G(sim) <- value

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
value	The parameter value to be set (in the corresponding module and param).

See Also

SpaDES.core-package, specifically the section 1.2.1 on Simulation Parameters.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), events(), inputs(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

---

Generate a simList object

Description

Given the name or the definition of a class, plus optionally data to be included in the object, new returns an object from that class.

Given the name or the definition of a class, plus optionally data to be included in the object, new returns an object from that class.

Usage

## S4 method for signature 'simList'
initialize(.Object, ...)

## S4 method for signature 'simList_'
initialize(.Object, ...)

Arguments

.Object	A simList object.
...	Optional Values passed to any or all slot

---

Metadata accessors

Description

These accessors extract the metadata for a module (if specified) or all modules in a simList if not specified.

Usage

inputObjects(sim, module, path)

## S4 method for signature 'simList'
inputObjects(sim, module, path)

## S4 method for signature 'missing'
inputObjects(sim, module, path)

outputObjects(sim, module, path)

## S4 method for signature 'simList'
outputObjects(sim, module, path)

## S4 method for signature 'missing'
outputObjects(sim, module, path)

outputObjectNames(sim, module)

## S4 method for signature 'simList'
outputObjectNames(sim, module)

reqdPkgs(sim, module, modulePath)

## S4 method for signature 'simList'
reqdPkgs(sim, module, modulePath)

## S4 method for signature 'missing'
reqdPkgs(sim, module, modulePath)

documentation(sim, module)

## S4 method for signature 'simList'
documentation(sim, module)

sessInfo(sim)

## S4 method for signature 'simList'
sessInfo(sim)

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
module	Character vector of module name(s)
path	The path to the module., i.e., the modulePath. Only relevant if sim not supplied.
modulePath	That path where module can be found. If set already using setPaths, it will use that. This will be ignored if sim is supplied and is required if sim not supplied

Examples

# set modulePath
setPaths(modulePath = getSampleModules(tempdir()))
# use Require and reqdPkgs
pkgs <- reqdPkgs(module = c("caribouMovement", "randomLandscapes", "fireSpread"))

---

Simulation inputs

Description

Accessor functions for the inputs slots in a simList object.

Usage

inputs(sim)

## S4 method for signature 'simList'
inputs(sim)

inputs(sim) <- value

## S4 replacement method for signature 'simList'
inputs(sim) <- value

inputArgs(sim)

## S4 method for signature 'simList'
inputArgs(sim)

inputArgs(sim) <- value

## S4 replacement method for signature 'simList'
inputArgs(sim) <- value

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
value	The object to be stored at the slot. See Details.

Details

These functions are one of three mechanisms to add the information about which input files to load in a spades call.

1. As arguments to a simInit call. Specifically, inputs or outputs. See ?simInit.

2. With the outputs(simList) function call.

3. By adding a function called .inputObjects inside a module, which will be executed during the simInit call. This last way is the most "modular" way to create default data sets for your model.

See below for more details.

Value

Returns or sets the value(s) of the input or output slots in the simList object.

inputs function or argument in simInit

inputs accepts a data.frame, with up to 7 columns. Columns are:

file	required, a character string indicating the file path. There is no default.
objectName	optional, character string indicating the name of the object that the loaded file will be assigned to in the simList. This object can therefore be accessed with sim$xxx in any module, where objectName = "xxx". Defaults to the filename without file extension or directory information.
fun	optional, a character string indicating the function to use to load that file. Defaults to the known extensions in SpaDES (found by examining .fileExtensions()). The package and fun can be jointly specified here as "packageName::functionName", e.g., "terra::rast".
package	optional character string indicating the package in which to find the fun);
loadTime	optional numeric, indicating when in simulation time the file should be loaded. The default is the highest priority at start(sim), i.e., at the very start.
interval	optional numeric, indicating at what interval should this same exact file be reloaded from disk, e.g,. 10 would mean every 10 time units. The default is NA or no interval, i.e, load the file only once as described in loadTime
arguments	is a list of lists of named arguments, one list for each fun. For example, if fun="raster", arguments = list(native = TRUE) will pass the argument "native = TRUE" to raster. If there is only one list, then it is assumed to apply to all files and will be recycled as per normal R rules of recycling for each fun.

Currently, only file is required. All others will be filled with defaults if not specified.

See the modules vignette for more details (browseVignettes("SpaDES.core")).

.inputObjects function placed inside module

Any code placed inside a function called .inputObjects will be run during simInit() for the purpose of creating any objects required by this module, i.e., objects identified in the inputObjects element of defineModule. This is useful if there is something required before simulation to produce the module object dependencies, including such things as downloading default datasets, e.g., downloadData('LCC2005', modulePath(sim)). Nothing should be created here that does not create an named object in inputObjects. Any other initiation procedures should be put in the "init" eventType of the doEvent function. Note: the module developer can use sim$.userSuppliedObjNames inside the function to selectively skip unnecessary steps because the user has provided those inputObjects in the simInit call. e.g., the following code would look to see if the user had passed defaultColor into during simInit. If the user had done this, then this function would not override that value with 'red'. If the user has not passed in a value for defaultColor, then the module will get it here:

if (!('defaultColor' %in% sim$.userSuppliedObjNames)) { sim$defaultColor <- 'red' }

See Also

SpaDES.core-package, specifically the section 1.2.2 on loading and saving.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), events(), globals(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

Examples

#######################
# inputs
#######################

# Start with a basic empty simList
sim <- simInit()

test <- 1:10
tmpdir <- file.path(tempdir(), "inputs") |> checkPath(create = TRUE)
tmpFile <- file.path(tmpdir, "test.rds")
saveRDS(test, file = tmpFile)
inputs(sim) <- data.frame(file = tmpFile) # using only required column, "file"
inputs(sim) # see that it is not yet loaded, but when it is scheduled to be loaded
simOut <- spades(sim)
inputs(simOut) # confirm it was loaded
simOut$test

# can put data.frame for inputs directly inside simInit call
allTifs <- dir(getMapPath(tempdir()), full.names = TRUE)

# next: .objectNames are taken from the filenames (without the extension)
# This will load all 5 tifs in the SpaDES sample directory, using
#   the rast fuction in the terra package, all at time = 0
sim <- simInit(
  inputs = data.frame(
    files = allTifs,
    functions = "rast",
    package = "terra",
    loadTime = 0,
    stringsAsFactors = FALSE)
)

##############################
# A fully described inputs object, including arguments:
files <- dir(getMapPath(tempdir()), full.names = TRUE)

# arguments must be a list of lists. This may require I() to keep it as a list
#   once it gets coerced into the data.frame.
# arguments = I(rep(list(native = TRUE), length(files)))
filelist <- data.frame(
  objectName = paste0("Maps", 1:5),
  files = files,
  functions = "terra::rast",
  # arguments = arguments,
  loadTime = 0,
  intervals = c(rep(NA, length(files) - 1), 10)
)
inputs(sim) <- filelist
spades(sim)

# Example showing loading multiple objects from global environment onto the
#   same object in the simList, but at different load times
a1 <- 1
a2 <- 2
# Note arguments must be a list of NROW(inputs), with each element itself being a list,
#  which is passed to do.call(fun[x], arguments[[x]]), where x is row number, one at a time
args <- lapply(1:2, function(x) {
               list(x = paste0("a", x),
                    envir = environment()) # may be necessary to specify in which envir a1, a2
                                           # are located, if not in an interactive session
               })
inputs <- data.frame(objectName = "a", loadTime = 1:2, fun = "base::get", arguments = I(args))
a <- simInit(inputs = inputs, times = list(start = 0, end = 1))
a <- spades(a)
identical(a1, a$a)

end(a) <- 3
a <- spades(a) # different object (a2) loaded onto a$a
identical(a2, a$a)

# Clean up after
unlink(tmpdir, recursive = TRUE)

---

Convert time units

Description

Current pre-defined units are found within the spadesTimes() function. The user can define a new unit. The unit name can be anything, but the function definition must be of the form "dunitName", e.g., dyear or dfortnight. The unit name is the part without the d and the function name definition includes the d. This new function, e.g., dfortnight <- function(x) lubridate::duration(dday(14)) can be placed anywhere in the search path or in a module (you will need to declare "lubridate" in your pkgDeps in the metadata).

This function takes a numeric with a "unit" attribute and converts it to another numeric with a different time attribute. If the units passed to argument units are the same as attr(time, "unit"), then it simply returns input time.

Usage

inSeconds(unit, envir, skipChecks = FALSE)

convertTimeunit(time, unit, envir, skipChecks = FALSE)

.spadesTimes

spadesTimes()

checkTimeunit(unit, envir)

## S4 method for signature 'character,missing'
checkTimeunit(unit, envir)

## S4 method for signature 'character,environment'
checkTimeunit(unit, envir)

Arguments

unit	Character. One of the time units used in SpaDES or user defined time unit, given as the unit name only. See details.
envir	An environment. This is where to look up the function definition for the time unit. See details.
skipChecks	For speed, the internal checks for classes and missingness can be skipped. Default FALSE.
time	Numeric. With a unit attribute, indicating the time unit of the input numeric. See Details.

Format

An object of class character of length 12.

Details

Because of R scoping, if envir is a simList environment, then this function will search there first, then up the current search() path. Thus, it will find a user defined or module defined unit before a SpaDES unit. This means that a user can override the dyear given in SpaDES, for example, which is 365.25 days, with dyear <- function(x) lubridate::duration(dday(365)).

If time has no unit attribute, then it is assumed to be seconds.

Value

A numeric vector of length 1, with unit attribute set to "seconds".

Author(s)

Alex Chubaty & Eliot McIntire

Eliot McIntire

---

Load a saved simList and ancillary files

Description

Loading a simList from file can be problematic as there are non-standard objects that must be rebuilt. See description in saveSimList() for details.

unzipSimList is a convenience wrapper around unzip and loadSimList where all the files are correctly identified and passed to loadSimList(..., otherFiles = xxx). See zipSimList for details.

Usage

loadSimList(
  filename,
  projectPath = getwd(),
  tempPath = tempdir(),
  paths = NULL,
  otherFiles = "",
  verbose = getOption("reproducible.verbose")
)

unzipSimList(zipfile, load = TRUE, paths = getPaths(), ...)

Arguments

filename	Character giving the name of a saved simulation file. Currently, only file types .qs or .rds are supported.
projectPath	An optional path for the project within which the simList exists. This is used to identify relative paths for saving and loading the simList.
tempPath	A character string specifying the new base directory for the temporary paths maintained in a simList.
paths	A list of character vectors for all the simList paths. When loading a simList, this will replace the paths of everything to these new paths. Experimental still.
otherFiles	A character vector of (absolute) file names locating each of the existing file-backed ⁠Raster*⁠ files that are the real paths for the possibly incorrect paths in Filenames(sim) if the the file being read in is from a different computer, path, or drive. This could be the output from unzipSimList (which is calls loadSimList internally, passing the unzipped filenames)
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠
zipfile	Filename of a zipped simList
load	Logical. If TRUE, the default, then the simList will also be loaded into R.
...	passed to unzip

Details

If cache is used, it is likely that it should be trimmed before zipping, to include only cache elements that are relevant.

Value

For loadSimList(), a simList object. For unzipSimList(), either a character vector of file names unzipped (if load = FALSE), or a simList object.

See Also

saveSimList(), zipSimList()

---

Make simList correctly work with memoise

Description

Because of the environment slot, simList objects don't correctly memoise a simList. This method for simList converts the object to a simList_ first.

Usage

## S3 method for class 'simList'
makeMemoisable(x)

## S3 method for class 'simList_'
unmakeMemoisable(x)

Arguments

x	An object to make memoisable. See individual methods in other packages.

Value

A simList_ object or a simList, in the case of unmakeMemoisable.

See Also

reproducible::makeMemoisable()

---

Determine the largest timestep unit in a simulation

Description

Determine the largest timestep unit in a simulation

Usage

maxTimeunit(sim)

## S4 method for signature 'simList'
maxTimeunit(sim)

Arguments

sim	A simList simulation object.

Value

The timeunit as a character string. This defaults to NA if none of the modules has explicit units.

Author(s)

Eliot McIntire and Alex Chubaty

---

Estimate memory used with system("ps")

Description

This will give a slightly different estimate than pryr::mem_used, which uses gc() internally. The purpose of this function is to allow continuous monitoring, external to the R session. Normally, this is run in a different session.

This will only work if the user has specified before running the spades call, set the interval, in seconds, that ps is run. E.g., options("spades.memoryUseInterval" = 0.5), will assess memory use every 0.5 seconds. The default is 0, meaning no interval, "off".

Usage

memoryUseThisSession(thisPid)

memoryUse(sim, max = TRUE)

Arguments

thisPid	Numeric or integer, the PID of the process. If omitted, it will be found with Sys.getpid().
sim	A completed simList
max	Logical. If TRUE, then it the return value will be summarized by module/event, showing the maximum memory used. If FALSE, then the raw memory used during each event will be shown.

Value

estimated memory use in MiB

data.table summarizing the estimated memory use (in MiB) for each event type, for each module, during the simulation.

Note

The suggested future and future.callr packages must be available.

See Also

The vignette("iv-modules")

---

Determine the smallest timeunit in a simulation

Description

When modules have different timeunit, SpaDES automatically takes the smallest (e.g., "second") as the unit for a simulation.

Usage

minTimeunit(sim)

## S4 method for signature 'simList'
minTimeunit(sim)

## S4 method for signature 'list'
minTimeunit(sim)

Arguments

sim	A simList simulation object.

Value

The timeunit as a character string. This defaults to "second" if none of the modules has explicit units.

Author(s)

Eliot McIntire

---

Extract the full file paths for R source code

Description

This can be used e.g., for Caching, to identify which files have changed.

Usage

moduleCodeFiles(paths, modules)

Arguments

paths	An optional named list with up to 4 named elements, modulePath, inputPath, outputPath, and cachePath. See details. NOTE: Experimental feature now allows for multiple modulePaths to be specified in a character vector. The modules will be searched for sequentially in the first modulePath, then if it doesn't find it, in the second etc.
modules	A named list of character strings specifying the names of modules to be loaded for the simulation. Note: the module name should correspond to the R source file from which the module is loaded. Example: a module named "caribou" will be sourced form the file ‘caribou.R’, located at the specified modulePath(simList) (see below).

Value

character vector of file paths.

---

Calculate module coverage of unit tests

Description

Calculate the test coverage by unit tests for the module and its functions.

Usage

moduleCoverage(mod, modulePath = "..")

Arguments

mod	Character string. The module's name. Default is basename(getwd())
modulePath	Character string. The path to the module directory (default is "..", i.e., one level up from working directory).

Value

Return a list of two coverage objects and two data.table objects. The two coverage objects are named moduleCoverage and functionCoverage. The moduleCoverage object contains the percent value of unit test coverage for the module. The functionCoverage object contains percentage values for unit test coverage for each function defined in the module. Please use covr::report() to view the coverage information. Two data.tables give the information of all the tested and untested functions in the module.

Note

When running this function, the test files must be strictly placed in the ‘tests/testthat/’ directory under module path. To automatically generate this folder, please set unitTests = TRUE when creating a new module using newModule(). To accurately test your module, the test filename must follow the format test-functionName.R.

Author(s)

Yong Luo

See Also

newModule().

---

Defaults values used in defineModule

Description

Where individual elements are missing in defineModule, these defaults will be used.

Usage

moduleDefaults

Format

An object of class list of length 13.

Value

named list of default module metadata

---

Simulation module dependency diagram

Description

Create a network diagram illustrating the simplified module dependencies of a simulation. Offers a less detailed view of specific objects than does plotting the depsEdgeList directly with objectDiagram().

Usage

moduleDiagram(sim, type, showParents = TRUE, ...)

## S4 method for signature 'simList,character,logical'
moduleDiagram(sim, type = "plot", showParents = TRUE, ...)

## S4 method for signature 'simList,ANY,ANY'
moduleDiagram(sim, type, showParents = TRUE, ...)

Arguments

sim	A simList object (typically corresponding to a completed simulation).
type	Character string, either "rgl" for igraph::rglplot or "tk" for igraph::tkplot, "Plot" to use quickPlot::Plot() or "plot" to use base::plot(), the default.
showParents	Logical. If TRUE, then any children that are grouped into parent modules will be grouped together by coloured blobs. Internally, this is calling moduleGraph(). Default FALSE.
...	Additional arguments passed to plotting function specified by type.

Value

invoked for its side effect of plotting the module dependency diagram.

Author(s)

Alex Chubaty

See Also

igraph(), moduleGraph() for a version that accounts for parent and children module structure.

Examples

if (requireNamespace("SpaDES.tools", quietly = TRUE) &&
    requireNamespace("NLMR", quietly = TRUE)) {
library(igraph)
times <- list(start = 0, end = 6, "month")
parameters <- list(
  .globals = list(stackName = "landscape"),
  caribouMovement = list(
    .saveObjects = "caribou",
    .saveInitialTime = 1, .saveInterval = 1
  ),
  randomLandscapes = list(.plotInitialTime = NA, nx = 20, ny = 20))

modules <- list("randomLandscapes", "caribouMovement")
paths <- list(
  modulePath = getSampleModules(tempdir())
)

# Set some options so example runs faster
opts <- options(spades.moduleCodeChecks = FALSE, spades.loadReqdPkgs = FALSE)
sim <- simInit(times = times, params = parameters, modules = modules,
               paths = paths)
options(opts)
moduleDiagram(sim)
# Can also use default base::plot
modDia <- depsGraph(sim, plot = TRUE)
# See ?plot.igraph
plot(modDia, layout = layout_as_star)

# Or for more control - here, change the label "_INPUT_" to "DATA"
edgeList <- depsEdgeList(sim)
edgeList <- edgeList[, list(from, to)]
edgeList[from == "_INPUT_", from := "Data"]
edgeList[to == "_INPUT_", to := "Data"]
edgeList <- unique(edgeList)
ig <- graph_from_data_frame(edgeList[, list(from, to)])
plot(ig)
}

---

Build a module dependency graph

Description

This is still experimental, but this will show the hierarchical structure of parent and children modules and return a list with an igraph object and an igraph communities object, showing the groups. Currently only tested with relatively simple structures.

Usage

moduleGraph(sim, plot, ...)

## S4 method for signature 'simList,logical'
moduleGraph(sim, plot, ...)

## S4 method for signature 'simList,missing'
moduleGraph(sim, plot, ...)

Arguments

sim	A simList object.
plot	Logical indicating whether the edgelist (and subsequent graph) will be used for plotting. If TRUE, duplicated rows (i.e., multiple object dependencies between modules) are removed so that only a single arrow is drawn connecting the modules. Default is FALSE.
...	Arguments passed to Plot

Value

A list with 2 elements, an igraph() object and an igraph communities object.

Author(s)

Eliot McIntire

See Also

moduleDiagram()

---

Parse and extract module metadata

Description

Parse and extract module metadata

Usage

moduleMetadata(
  sim,
  module,
  path = getOption("spades.modulePath", NULL),
  defineModuleListItems = c("name", "description", "keywords", "childModules", "authors",
    "version", "spatialExtent", "timeframe", "timeunit", "citation", "documentation",
    "reqdPkgs", "parameters", "inputObjects", "outputObjects")
)

## S4 method for signature 'missing,character,character'
moduleMetadata(module, path, defineModuleListItems)

## S4 method for signature 'missing,character,missing'
moduleMetadata(module, defineModuleListItems)

## S4 method for signature 'ANY,ANY,ANY'
moduleMetadata(
  sim,
  module,
  path = getOption("spades.modulePath", NULL),
  defineModuleListItems = c("name", "description", "keywords", "childModules", "authors",
    "version", "spatialExtent", "timeframe", "timeunit", "citation", "documentation",
    "reqdPkgs", "parameters", "inputObjects", "outputObjects")
)

Arguments

sim	A simList simulation object, generally produced by simInit.
module	Character string. Your module's name.
path	Character string specifying the file path to modules directory. Default is to use the spades.modulePath option.
defineModuleListItems	A vector of metadata entries to return values about.

Value

A list of module metadata, matching the structure in defineModule().

Author(s)

Alex Chubaty

See Also

defineModule()

Examples

## turn off code checking -- don't need it here
opts <- options("spades.moduleCodeChecks" = FALSE,
                "spades.useRequire" = FALSE)

path <- getSampleModules(tempdir())
sampleModules <- dir(path)
x <- moduleMetadata(sampleModules[3], path = path)

## using simList
if (require("SpaDES.tools", quietly = TRUE)) {
   mySim <- simInit(
      times = list(start = 2000.0, end = 2001.0, timeunit = "year"),
      params = list(
        .globals = list(stackName = "landscape")
      ),
      modules = list("caribouMovement"),
      paths = list(modulePath = path)
   )
   moduleMetadata(sim = mySim)
}

# turn code checking back on -- don't need it here
options(opts)

---

Extract a module's parameters, inputs, or outputs

Description

These are more or less wrappers around moduleMetadata, with the exception that extraneous spaces and End-Of-Line characters will be removed from the desc arguments in defineParameters, defineInputs, and defineOutputs

Usage

moduleParams(module, path)

## S4 method for signature 'character,character'
moduleParams(module, path)

moduleInputs(module, path)

## S4 method for signature 'character,character'
moduleInputs(module, path)

moduleOutputs(module, path)

## S4 method for signature 'character,character'
moduleOutputs(module, path)

Arguments

module	Character string. Your module's name.
path	Character string specifying the file path to modules directory. Default is to use the spades.modulePath option.

Value

data.frame

Author(s)

Alex Chubaty

See Also

moduleMetadata()

Examples

## easily include these tables in Rmd files using knitr
path <- getSampleModules(tempdir())
sampleModules <- dir(path)

p <- moduleParams(sampleModules[3], path = path)
i <- moduleInputs(sampleModules[3], path = path)
o <- moduleOutputs(sampleModules[3], path = path)

knitr::kable(p)
knitr::kable(i)
knitr::kable(o)

---

Simulation modules and dependencies

Description

Accessor functions for the depends and modules slots in a simList object. These are included for advanced users.

depends()	List of simulation module dependencies. (advanced)
modules()	List of simulation modules to be loaded. (advanced)
inputs()	List of loaded objects used in simulation. (advanced)

Usage

modules(sim, hidden = FALSE)

## S4 method for signature 'simList'
modules(sim, hidden = FALSE)

modules(sim) <- value

## S4 replacement method for signature 'simList'
modules(sim) <- value

depends(sim)

## S4 method for signature 'simList'
depends(sim)

depends(sim) <- value

## S4 replacement method for signature 'simList'
depends(sim) <- value

Arguments

sim	A simList object from which to extract element(s) or in which to replace element(s).
hidden	Logical. If TRUE, show the default core modules.
value	The object to be stored at the slot.

Details

Currently, only get and set methods are defined. Subset methods are not.

Value

Returns or sets the value of the slot from the simList object.

Author(s)

Alex Chubaty

See Also

SpaDES.core-package, specifically the section 1.2.7 on Modules and dependencies.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), events(), globals(), inputs(), objs(), packages(), params(), paths(), progressInterval(), times()

---

Parse and extract a module's version

Description

Parse and extract a module's version

Usage

moduleVersion(module, path, sim, envir = NULL)

## S4 method for signature 'character,character,missing'
moduleVersion(module, path, envir)

## S4 method for signature 'character,missing,missing'
moduleVersion(module, envir)

## S4 method for signature 'character,missing,simList'
moduleVersion(module, sim, envir)

Arguments

module	Character string. Your module's name.
path	Character string specifying the file path to modules directory. Default is to use the spades.modulePath option.
sim	A simList simulation object, generally produced by simInit.
envir	Optional environment in which to store parsed code. This may be useful if the same file is being parsed multiple times. This function will check in that environment for the parsed file before parsing again. If the envir is transient, then this will have no effect.

Value

numeric_version indicating the module's version.

Author(s)

Alex Chubaty

See Also

moduleMetadata()

Examples

# using filepath
path <- getSampleModules(tempdir())
moduleVersion("caribouMovement", path)

# using simList
options("spades.useRequire" = FALSE)
if (require("SpaDES.tools", quietly = TRUE)) {
   mySim <- simInit(
      times = list(start = 2000.0, end = 2002.0, timeunit = "year"),
      params = list(
        .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
      ),
      modules = list("caribouMovement"),
      paths = list(modulePath = path)
   )
   moduleVersion("caribouMovement", sim = mySim)
}

---