v2.1.0

SpaDES.core 2.1.0

• fix issue with event queue colnames in completed<- and all.equal.simList (#272);
• fixed issue saving simList objects when multiple paths were used (e.g., length(modulePath) > 1);
• events can be defined directly in calls to newModule();
• checkpoints are assumed to be used locally, and no longer invoke simulation file archiving and re-extraction of files (i.e., uses saveSimList(..., inputs = FALSE, outputs = FALSE, cache = FALSE, files = FALSE));
• improved recovery of interrupted simulations via savedSimEnv()$.sim -- savedSimEnv() is now exported for easier discovery -- an internal package environment is used, unless the user specifies options(reproducible.memoisePersist = TRUE), which will use the global environment to store the .sim object;
• switch from crayon (superseded) to cli for message colours;

Dependency changes

• require reproducible v2.1.0 or higher;

Breaking changes

• due to upstream changes in reproducible, loadSimList() is incompatible with simList objects saved with earlier versions of SpaDES.core.

v2.0.5

SpaDES.core 2.0.5

• fix a failing test on R-devel and latest R-release (#275)

v2.0.4

SpaDES.core 2.0.4

• drop support for R 4.1 due to changes in dependency packages;
• improve saveSimList documentation (#260);
• newModule now correctly defaults to current working directory (#273);

v2.0.3

SpaDES.core 2.0.3

Enhancements

• new accessor function figurePath() to get the directory of a module's output figures, which is now uses a separate subdirectory per module (i.e., file.path(outputPath(sim), "figures", <moduleName>)); Plots() defaults to using this path, and module developers are encouraged to update their module code to use figurePath(sim) where Plots() is not being used.
• re-Caching of a simList no longer triggers on changes to .useCache parameter, when it doesn't pertain to the event or module in question.
• many historical modules used bind_rows from dplyr within expectsInput or createsOutput. Now, if a module uses bind_rows and doesn't have dplyr installed, SpaDES.core will intercept and use SpaDES.core::bindrows.
• saveSimList() better handles relative paths and symbolic links (#263)
• saveSimList() does an improved job at handling file-backed objects (previously, tests were passing because object was still there; now object is deleted, simList reloaded, and file-backed objects put back into place)
• deal with upstream reproducible changes to .wrap
• deal with upstream reproducible changes to Cache messaging, specifically, remove cases where function was a userTag for an outer function call. Now these will display as otherFunction, so that individual functions can be more easily isolated.
• overhaul of messaging during simInit and spades that allows for nested calls to simInit and/or spades
• elapsed time during simInit is now reported
• elapsedTime now displays the largest time unit, which may not be secs
• some parts of any warning messages are now muffled for clarity: e.g., In modCall... is removed.
• options that are either RequireOptions(), spadesOptions() or reproducibleOptions() can now be set during the simInit by passing them as arguments, e.g., simInit(useMemoise = FALSE). See ?simInit, specifically the ... parameter description. This is not passed as an argument named options: these are just options. For convenience, user can omit the package prefix, e.g., useMemoise for reproducible.useMemoise
• all necessary updates to deal with reproducible updates to exported methods
• new function: dmin to go with the other d* SpaDES times.
• updates to unit tests to accommodate all these changes.

Dependency Changes

• dplyr is removed (again)

Bug fixes

• coltab<- from terra changed how it deals with multi-layer SpatRasters. Two sample modules have been modified to set colours on these multi-layer SpatRasters
• loading of asc raster-type files using inputs did not work; fixed.
• fixed bug in simInit parameter checking
• A number of new edge cases dealt with for reducing false positive and false negative Cacheing of events and modules. Now, for example, a change to the parameter .useCache = c("init") to .useCache = c("init", ".inputObjects") will not trigger a rerun of the init event. Also, .inputObjects is no longer evaluated for Cacheing of doEvent
• Error in if (is.na(sim@params[[m]][[x]])) fixed.
• asc spatial map files were incorrectly loaded by terra package: fixed.

SpaDES.core 2.0.2

Enhancements

• none

Dependency Changes

• none

Bug fixes

• new helpers for getting copies of sample files (getSampleModules() and getMapPath() ) now used throughout examples, vignettes, and tests to avoid writing files in package installation directories.

v2.0.0

SpaDES.core 2.0.0

Enhancements

• options(spades.futureEvents = TRUE) has been reworked and now works under a wider array of conditions.
• Copy, .wrap, wrap and unwrap all have fairly robust methods for simList class. The generics are in reproducible or terra
• updated sampleModules to use Plots and .plot parameter.
• new function: registerOutputs can be used by a developer to add saved files to the outputs(sim) data.frame.
• messaging during nested simInit or spades calls will now not duplicate time prefix
• params and .globals were previously not expected to change during Cached events. Thus returned cached values were always the same as input as params and .globals. They are now assessed and returned as part of the Cache, as expected.
• updates to handle upstream changes in Require and reproducible, including renaming cacheRepo to cachePath in some inherited functions.
• updates to sample modules to use SpaDES.tools::neutralLandscapeMap instead of NLMR package directly
• migration complete to use terra and sf instead of raster, sp, rgeos, and rgdal as defaults. Attempts have been made to maintain backwards compatibility in all cases.
• moduleMetadata now handles multiple module paths
• updates to memoryUse
• new option: setting options("spades.allowInitDuringSimInit" = TRUE), a user will have init events of one ore more modules run during the simInit call, but only if they have no upstream dependencies, i.e., their expectsInputs cannot be supplied by another module's createsOutputs. simInit will determine which modules have no upstream dependencies and only these will be selected for running only their init events. This can be useful e.g., if there is a module that createsOutputs for a studyArea.
• .plots arg in spades can be set to NA to turn of all plotting. This can also be set with option(spades.plots = NA),
• minor bugfixes
• moduleMetadata no longer runs .inputObjects. In addition to being unnecessary and slow, it was also failing with reproducible (==1.2.16) because it was trying to run Cache, which had a bug for this case. Now, moduleMetadata no longer runs the .inputObjects internally, so this bug is no longer relevant.
• two new options -- spades.loadReqdPkgs, so a user can turn off loading of packages, and spades.dotInputObjects, so a user can omit running of the .inputObjects function in modules during simInit. These are updated in spadesOptions.
• some tests and examples have been shortened, to fit within the CRAN guidelines
• improved documentation
• new hidden function runScheduleEventsOnly will extract only the scheduleEvents call; needed for options(spades.futureEvents = TRUE)
• new option: spades.saveFileExtensions which allows users to use the outputs(sim) mechanism for saving, for file extensions that are not already supported by .saveFileExtensions()
• many issues addressed and closed

Dependency Changes

• drop support for R 4.0 as dependency packages no longer support it;
• require reproducible v2.0.5 or higher;
• require quickPlot v1.0.2 or higher;
• removed googledrive from Suggests.

Bug Fixes

• several minor, e.g., Plots when not specifying fn, but usePlot = FALSE
• many examples that were protected behind \dontrun or \donttest were stale; these have been updated
• saveFiles bugfix: multiple objects names can now be passed to .saveOuputs module parameters.

Deprecated, Defunct, and Removed Features

• several previously-deprecated functions have been made defunct: remoteFileSize(), updateList(). These will be removed by mid-2023.

v1.1.0

Known issues: https://github.com/PredictiveEcology/SpaDES.core/issues

version 1.1.0

new features

• messaging in a module can now handle "same line" messages --> simply use the standard "\b" in the message, and it will occur on same line as previous message
• Plots now appends the filename any file saved during Plots to the outputs slot of the sim, i.e., it will show up in outputs(sim)
• logPath is now a function that points to a sub-folder of file.path(outputPath(sim), "log")
• defineEvent is a new function that allows a different way of specifying events than the doEvent function. This is not yet being used in the module templates, so does not appear with newModule.
• spades can now run correctly, with "incomplete" modules that don't have metadata or even a module file. Now, a "module" will work with simInit and spades if a doEvent.XXX exists somewhere e.g., in the .GlobalEnv. spades will find it through inheritance and no longer complain if specific structures are absent. This may make it easier to learn how to use SpaDES as it mimics a more normal user experience where functions are all in the .GlobalEnv.
• new option spades.DTthreads to limit the number of threads used by data.table (default 1).
  Users can override this default if needed; modules can setDTthreads() as needed,
  but should restore the original value on.exit.
• saveSimList() and loadSimList() accept .qs or .rds files
• spades and simInit now force UTF-8 encoding; this is reset on.exit. If a module needs a different character encoding, then it can be set within the module code.
• .studyAreaName parameter added to default module metadata when using newModule.
• changes to template module documentation - removal of "module usage" as it is not relevant within a module, and minor restructuring
• new option spades.scratchPath, to be used for e.g., temporary raster files and temporary SpaDES recovery mode objects.
• The default temporary rasterTmpDir has changed to be a subdirectory of scratchPath.
  rasterPath will be deprecated in a future release.
• New default temporary terraTmpDir set as a subdirectory of scratchPath.
• Old way of naming module functions with full module name plus "Init" ('non namespaced') no longer works. Message now converted to stop.
• use README.md instead of README.txt in new modules.

dependency changes

• removed RandomFields dependency, as that package is no longer maintained;
• added NLMR to Suggests to provide random landscape generation capabilities previously provided by RandomFields.

bug fixes

• memoryUse was not correctly handling timezones; if the system call to get time stamps was in a different timezone compared to the internal SpaDES event queue, then the memory stamps were not correctly associated with the correct events.
• improved handling of data.table objects using loadSimList()
• Fixed caching of .inputObjects to correctly capture objects that were assigned to mod$xxx.
• Fixed caching of simList objects where changes to functions appeared to be undetected, and so a Cache call would return a stale module with function code from the Cached simList, which was incorrect.
• fix recovery mode bug: use scratch directory specified by the user via options(spades.scratchPath) (see above).
• objSize could have infinite recursion problem if there are simLists inside simLists. Fixed with new reproducible::objSize, which uses lobstr::obj_size.
• several minor fixes, including in Plots
• fixes to saveFiles related to data.table assignment and use in outputs(sim)

v1.0.10

Known issues: https://github.com/PredictiveEcology/SpaDES.core/issues

version 1.0.10

new features

• experimental new feature SpaDES modules can now be R packages.
  The simplest way to convert a module to a package is using the new function convertToPackage.
  Benefits of doing this are so that a SpaDES module can benefit from the infrastructure of an R package (e.g., devtools::document, devtools::check, setting up Continuous Integration systems etc.).
  Any documentation written using #' i.e., roxygen2 will be copied immediately above the function where it was sitting.
• newModule now correctly places the SpaDES.core package dependency in the reqdPkgs element of the metadata, instead of version. It will put the full Github reference if SpaDES.core was installed directly from GitHub.
• There is a bug in qs package: either qsave or qread converts data.table objects to list objects. loadSimList has a work around internally to convert these objects back to data.table, if the metadata indicate that the objects should be data.table objects.
• new function: paramCheckOtherMods.
  Can be used within a module to assert that a parameter has the same value as the same parameter in other modules.
  This is therefore a check of a parameter that might be considered a .global and passed within simInit(..., params = list(.globals = list(someParam = "someValue"))), but the user did not do that.
• now spades messaging when e.g., debug = 1 can correctly accommodate nested spades calls, i.e., a SpaDES module calling spades internally.
• newModule now puts SpaDES.core dependency in the correct reqdPkgs instead of version metadata element
• to further the transition to using .plots instead of .plotInitialTime, Plots will check whether .plotInitialTime is actually set in the module metadata first.
  Only if it is there, will it evaluate its value. Currently, modules get default values for .plotInitialTime even if the module developer didn't include it in the module metadata.

dependency changes

• drop support for R 3.6 (#178)

bug fixes

• minor bugfix when debug arg of spades is set to an event type that is also in the core modules (e.g., save, load), such as "init"
• Cache-ing of a simList, when quick is a character vector, errored. Now fixed.
• moduleMetadata incorrectly dropped defineModuleListItems under certain signatures.

v1.0.9

Known issues: https://github.com/PredictiveEcology/SpaDES.core/issues

version 1.0.9

new features

• moduleCoverage has been rewritten to estimate code coverage of a module using covr package.
• P now has a replacement method. So, to update a parameter within a module (where it is namespaced, i.e., don't have to specify the module name): P(sim, "paramName") <- 1. If using this outside a module, then module (3rd argument) will have to be specified.
• P argument order changed to accommodate the fact that namespacing is used to detect module name: the user does not need to supply module, so it should not be second. This is for the normal P method and the new replace method above: it is now P(sim, param, module); there are attempts to capture errors (i.e., parameter supplied that matches a module, but not a parameter; vice versa) and give a warning for user to change code. This may have little downstream effect as all known cases use the P(sim)$paramName, which will still work fine, instead of P(sim, "paramName").
• Plots does a better job with RasterStack objects plotted to screen without ggplot2
• removed .isFALSE: use base::isFALSE now
• Plots can now omit the data argument; just use the named arguments in ...
• defineParameter now allows multi-line desc or multiple strings; paste is no longer needed for long desc
• moduleCodeFiles a new function that identifies all the code files in a collection of modules
• .globals functionality is modified. If a user specifies a .globals in the parameters object (passed into simInit), then all identical parameters in all modules will be overridden with these .global values
• defineParameter, expectsInput and createsOuptut can all now have multi-line desc, without needing to use paste or paste0. Extraneous spaces and carriage returns will all be stripped. This can either be using a single multi-line quote or via multiple lines, each with its own "".
• the module environment in the simList is no longer "locked" with lockBinding. It is already hidden in sim$.mods, and since sim$.mods can be modified, this was a weak caution against user modification. Further, for moduleCoverage, the module environment needed to be unlocked, which is not allowed by CRAN.

dependencies

• no changes

bug fixes

• When .inputObjects was cached (via setting useCache = '.inputObjects' parameter), it was "too sensitive". Changes to any module's parameters, not just the current module, would cause rerun of .inputObjects. Now it correctly identifies parameter changes only in the current module. THIS WILL CAUSE some existing caches to trigger a rerun once; after this, it will be less sensitive
• restartSpades did not correctly deal with objects that did not yet exist prior to the event. Fixed with: 24b9cd1.
• restartSpades was losing the previous completed events list. This has been fixed; it is now kept after restartSpades
• Plots - fixed issues with plot layer names and plot overlaying when passing data only (e.g. quickPlot::Plot-like behaviour)
• simInitAndSpades now has .plots arg to match spades
• fix raster file name query for GDAL 3.3.2 (#174; @rsbivand)

v1.0.8

Known issues: https://github.com/PredictiveEcology/SpaDES.core/issues

version 1.0.8

new features

• Plots function can be used like Plot, but with types specified.
  The devices to save on disk will have some different behaviours to the screen representation, since "wiping" an individual plot on a device doesn't exist for a file device.

version 1.0.7

new features

• Plots function that will produce zero to 4 types of items that are relevant for plotting: 1) Visual on screen, 2) The plot object saved to disk, 3) The raw data that went into the plot and 4) The plot as one or more image files, e.g., .png or .pdf via ggsave
• spades now accepts an events argument, which will limit the events that are run to those specified in the argument. This seems to be most useful for the init case, e.g., spades(sim, events = "init"). See ?spades.
• messaging during simInit now is prefixed with Sys.time() and "simInit"
• messaging during spades is simplified to take up fewer characters: INFO:: has been removed
• simInit now checks for minimum version of SpaDES.core needed in a module and stops if it fails, giving instructions how to upgrade.
• several human-readable only elements of a module metadata are no longer enforced, including spatialExtent, as they are not used by the spades algorithms
• new function: anyPlotting to test whether plotting of one form or another should occur
• line-by-line messaging during spades call is now more informative, including module name (by default shortened -- can be changed with options("spades.messagingNumCharsModule")))
• defineParameter can now accept a vector of "class", so a parameter can be more than one class.
  Presumably this should generally not be used, but a good reason could be, say, c("numeric", "function"), where the use can pass either a numeric or a function that would calculate that numeric.
• new helper function simFile to generate file names for use with e.g., saveSimList
• zipSimList is now exported
• spades will now attempt to load reqdPkgs, which is already done in simInit.
  In cases where simInit was not run, e.g., Cache(simInitAndSpades, ..., events = "init"), then modules will not have access to packages.
  For cases where simInit was called, then this should add very little overhead.
• saveSimList will now convert file-backed Raster* class objects to memory if fileBackend = 0.
  Previously, it left them as is (on disk if on disk, in memory if in memory).
• For code/documentation contributors, markdown syntax is now turned on and can be used when writing function documentation
• The first event will now run if it is scheduled to be prior to time(sim) in the case where it is equal to or after end(sim). Previously, this would not run any events if time(sim) >= end(sim) && events(sim)[[1]] < time(sim).
• minor documentation modifications
• Add optional .seed parameter for modules (#163)

Bugfixes

• defineParameter was throwing is.na(default) warning when a parameter was not an atomic.
• recovery mode did not work correctly if the file-backed rasters were in the temporary directory, as it would collide with the temporary directory of the recovery mode mechanism. Now recovery mode uses a dedicated temporary directory
• other minor bugfixes,