spadesOptions: 'SpaDES.core' options

In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

SpaDES.core options

Description

These provide top-level, powerful settings for a comprehensive SpaDES workflow. To see defaults, run spadesOptions(). See Details below.

Usage

spadesOptions()

Details

Below are options that can be set with options("spades.xxx" = newValue), where xxx is one of the values below, and newValue is a new value to give the option. Sometimes these options can be placed in the user's .Rprofile file so they persist between sessions.

The following options are likely of interest to most users

OPTION	DEFAULT VALUE	DESCRIPTION
spades.allowInitDuringSimInit	FALSE	New feature as of ⁠SpaDES.core > 1.1.1.9001⁠; If set to TRUE, simInit will evaluate the dependencies in the metadata objects and determine whether there are modules whose init events can be run safely prior to the .inputObjects of other modules, i.e., if a module's expectsInput is not being supplied by any other module's createsOutput.
spades.browserOnError	FALSE	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 re-parse 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	getOption('reproducible.cachePath')	The default local directory in which to cache simulation outputs. Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/cache⁠).
spades.debug	TRUE	The default debugging value debug argument in spades()
spades.dotInputObjects	TRUE	This is used in simInit; if set to TRUE then the .inputObjects function will be run; if FALSE, then it will be skipped.
spades.DTthreads	1L	The default number of data.table threads to use. See also ?data.table::setDTthreads.
spades.futureEvents	FALSE	If set to TRUE, the event simulator will attempt to spawn events whose outputs are not needed (by other events in the simList) into a future. In some cases, this will speed up simulations, by running some events in parallel. Still VERY experimental. Use cautiously.
spades.logPath	Defaults to a subdirectory (⁠logs/⁠) of the simulation output directory.	The default local directory in which to look for simulation inputs.
spades.inputPath	Default is a temporary directory (typically ⁠/tmp/RtmpXXX/SpaDES/inputs⁠)	The default local directory in which to look for simulation inputs.
spades.loadReqdPkgs	Default is TRUE meaning that any reqdPkgs will be loaded via Require or require. If FALSE, no package loading will occur. This will mean that modules must prefix every function call from a package with that package name with double colon (::).
spades.lowMemory	FALSE	If true, some functions will use more memory efficient (but slower) algorithms.
spades.memoryUseInterval	FALSE	A numeric in seconds indicating how often sample the memory use. This will be run in a separate "future" process so it can monitor the main process. To access the resulting memory use table, use memoryUse(sim) after the simulation has terminated.
spades.messagingNumCharsModule	21	The number of characters to use for the messaging preamble on each line of the messaging during spades calls.
spades.moduleCodeChecks	list(suppressParamUnused = FALSE, suppressUndefined = TRUE, suppressPartialMatchArgs = FALSE, suppressNoLocalFun = TRUE, skipWith = TRUE)	Should the various code checks be run during simInit. These are passed to codetools::checkUsage(). Default is given by the function, plus these:
spades.moduleDocument	TRUE	When a module is an R package e.g., via convertToPackage, it will, by default, rebuild documentation and reparse during simInit. Since rebuilding documentation (from the roxygen2 tags) can be time consuming, a user may wish to prevent this from happening each simInit call. If so, set this option to FALSE
spades.modulePath	file.path(tempdir(), "SpaDES", "modules"))	The default local directory where modules and data will be downloaded and stored. Default is a temporary directory
spades.moduleRepo	"PredictiveEcology/SpaDES-modules"	The default GitHub repository to use when downloading modules via downloadModule
spades.nCompleted	1000L	The maximum number of completed events to retain in the completed event queue.
spades.outputPath	file.path(tempdir(), "SpaDES", "outputs")	The default local directory in which to save simulation outputs.
spades.plots	The value of this will passed to .plots within every module; it will thus override all module parameter values for .plots. This can, e.g., be used to turn off all plotting.	The default is NULL, meaning accept the module-level parameter
spades.recoveryMode	1L	If this is 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.saveFileExtensions	NULL	a data.frame with 3 columns, exts, fun, and package indicating which file extension, and which function from which package will be used when using the outputs mechanism for saving files during a spades call. e.g., ⁠options(spades.saveFileExtensions = data.frame(exts = "shp", fun = "st_write", package = "sf")⁠. Then specify e.g., simInit(outputs = data.frame(objectName = "caribou", fun = "st_write", package = "sf"))
spades.scratchPath	file.path(tempdir(), "SpaDES", "scratch"))	The default local directory where transient files from modules and data will written. This includes temporary raster and terra files, as well as SpaDES recovery mode files. Default is a temporary directory.
spades.sessionInfo	TRUE)	Assigns the utils::sessionInfo() to the simList during simInit with the name sim$._sessionInfo. This takes about 75 milliseconds, which may be undesirable for some situations where speed is critical. If FALSE, then this is not assigned to the simList.
spades.switchPkgNamespaces	FALSE to keep computational overhead down.	Should the search path be modified to ensure a module's required packages are listed first? If TRUE, there should be no name conflicts among package objects, but it is much slower, especially if the events are themselves fast.
spades.testMemoryLeaks	TRUE.	There is a very easy way to create a memory leak with R and SpaDES, by adding formulas or functions to ⁠sim$⁠ when the enclosing environment of the formula or function contained a large object, most relevant here is the sim object. SpaDES.core now tests for likely culprits for this and suggests alternatives with a warning
spades.tolerance	.Machine$double.eps^0.5.	The default tolerance value used for floating point number comparisons.
spades.useragent	"https://github.com/PredictiveEcology/SpaDES".	: The default user agent to use for downloading modules from GitHub.
spades.useRequire	!tolower(Sys.getenv("SPADES_USE_REQUIRE")) %in% "false"	: The default for that environment variable is unset, so this returns TRUE. If this is TRUE, then during the simInit call, when packages are identified as being required, these will be installed if missing, only if spades.useRequire option is TRUE, otherwise, simInit will fail because packages are not available.

Value

named list of the default package options.

SpaDES.core documentation built on June 22, 2024, 10:32 a.m.