Lexicon

If this is your first time encountering a model built within the SpaDES framework, you may be unfamiliar with several terms used in this manual. Here we offer a lexicon to help familiarize users with terms and concepts relevant to spadesCBM. A more comprehensive guide and introduction to robust and nimble scientific workflows using SpaDES can be found here.

Basic structure of a SpaDES project

SpaDES projects aim to follow the principles of the PERFICT approach of McIntire et al. (2022). The PERFICT approach aims to Predict regularly frm models that are Evaluated, Reusable, Freely accessible, and Interoperable, and that are part of Continuous workflows that are Tested regularly. More information on how this approach fits within the SpaDES framework can be found here.
Using modules allows us to break up a model’s code into meaningful themes and/or uses that can easily be moved, swapped or replaced. SpaDES projects use modules in its standardized structure to allow for this nimbleness. Each module defines its own metadata, identifying the inputs and outputs of the code, allowing R to connect the module with others.

Modules

In its simplest form, a SpaDES module is comprised of R code that has metadata that gets put into functions.

Metadata

inputs and outputs are described in the metadata of the module.

Parameters

Each module has its own set of parameters that a user can choose to set or leave as default. Parameters are usually module-specific, but some global parameters exist. To view an example of how parameters can be set in a global script, see the params section of the global found in our example chapter.

Events

The functions of the module can be further subdivided into events. These events are scheduled in the module to be run one or many times.

.inputObjects()

This function is found at the end of a module’s script. This is where default inputs are supplied. For most default inputs in spadesCBM, the module will check if a user has supplied their own input, and if not, will use the default described in the module’s .inputObjects() call.

Simlist

Objects cannot be shared across modules unless they are added to the simlist. It is a rich data object that acts like a list or an environment. All outputs of a module or model are added to this simlist.

0.0.1 prepInputs()

This function is used to prepare R objects from remote (usually URLs) or local data sources. This enables easily repeatable continuous workflows and facilitates commonly used steps for getting, loading, and processing data. More information on the function and how it can be used with SpaDES-related projects can be found here.

Running a global script

The setupProject() function

setupProject() is a function in the SpaDES.project package. It allows the user to set a variety of options before running. When run, setupProject does a series of very specific things in a particular order to reduce the chances of package conflicts and user errors. In spadesCBM, we use our setupProject() call to select the modules to run and their respective GitHub branches, project paths, caching and saving options,our python options and download, and certain project specific input objects. to learn more about the SpaDES.project package and setupProject() you can view the training chapter here.

The simInitAndSpades2() function

Once we have run our setupProject() call, we can run our model using simInitAndSpades2(). One of the outputs of this function is the simlist, allowing the user to view all outputs from their simulation.

Folder structure of a SpaDES module

Our spadesCBM modules use the basic folder structure for all SpaDES modules. Each have their respective .R scripts, an .Rmd file with their documentation used in this manual, and a tests folder containing the module’s tests. Some will also have an R folder containing other scripts that get sourced when running the module. These can include basic functions used in the module or the creation of default objects only used when the user doesn’t provide a specific input.

0.1 LandRCBM terms

0.1.1 Cohorts

Cohorts represent trees on a pixel that share the same species and age. These are the smallest unit of forest representation in LandRCBM.

0.1.2 Pixel groups and cohort groups

Pixel groups are used in LandR and cohort groups are used in spadesCBM. A pixel group in LandR represents a collection of pixels that share the same cohort species and age composition within the same ecoregion. A cohort group is defined as cohorts share the same set of age, growth curve (or species), spatial unit, and ecozone across pixels (or stands). A single pixel can have many cohort groups. More information on the spadesCBM terminology can be found here. An in-depth description of LandR pixel groups can be found in the highlited text here here.

0.1.3 masterRaster

In LandRCBM (as in LandR and spadesCBM), study area is defined by the masterRaster object. This object can be directly provided as a raster, created from a shapefile, or by any other means. For LandR, the studyArea object is also required. In our example, masterRaster is provided in our global script, refer to our example chapter to view how it the masterRaster is provided in our example.

0.1.4 spinup

There are two different processes refered to as a spinup in LandR CBM. Biomass_core performs a spinup to initialize starting landscape conditions for Biomass_yieldTables whereas CBM_core performs a spinup to initialize and balance above and below-ground carbon pools. See figure 1 in the Overview chapter to see a basic visual of flow the modules involved in the LandR spinup. In-depth descriptions of the spadesCBM spinup can be found here and here.

0.1.5 Ecozone, ecoregion/ecolocation, and spatial unit

In Canada, there are 15 distinct terrestrial ecozones. These represent large ecosystems with specific climate and vegetation, regardless of jurisdiction. Spatial units (spadesCBM) are more specific than ecozones, and correspond to the unique combination of jurisdiction (i.e. province or territory) and ecozone. Ecoregions/ecolocations (LandR) are grouped by National Ecological Classification of Canada (NECC) ecodistricts and land-cover classification.