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.
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.
spadesCBM and carbon terms
0.0.2 CBM-CFS3 vs spadesCBM
The Carbon Budget Model of the Canadian Forest Sector CBM-CFS3 is the windows-based framework currently used for the international reporting of Canada’s managed forests. It is aspatial and windows-based. spadesCBM is a SpaDES implementation of the logic, structure, and defaults assumptions of the Carbon Budget Model CBM. It is spatially explicit and built in R with calls to Python functions.
0.0.3 Spinup
A more in-depth explanation of the spinup function can be found here and here (incomplete).
0.0.4 Ecozone vs spatial unit
In Canada, there are 15 distinct terrestrial ecozones. spadesCBM uses this classification. These represent large ecosystems with specific climate and vegetation, regardless of jurisdiction.
Spatial units are more specific than ecozones, and correspond to the unique combination of jurisdiction (i.e. province or territory) and ecozone.
0.0.5 Cohort groups
To simplify and optimize our simulations, we group individual pixels into cohortGroupID in which each group corresponds to a unique set of age, growth curve, spatial unit, and ecozone.
A more in-depth description of cohort groups in spadesCBM can be found here.
0.0.6 source_pool and sink_pool
Every carbon transfer in spadesCBM occurs between two pools. One pool is the source and transfers its carbon to the sink. A specific pool is generally not tied to one or the other and can be a source in one carbon transfer and a sink in another. in spadesCBM, this is calculated by proportions, with a proportion of one pool moving to another pool, with proportions adding to 1 so that no carbon is lost.
0.0.7 masterRaster
In spadesCBM, our 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. In our example, it is provided as a raster file in our global script. Refer to our Example chapter to view how it the masterRaster is provided in our example.
0.0.8 cbmAdmin
This data table provides ecozone and spatial unit information for provincial boundaries. It is provided to help users with the equivalence between provincial and territorial boundaries, ecozones, and spatial unit IDs.
0.0.9 Net Primary Productivity (NPP)
NPP is defined as the amount of CO2 removed from the atmosphere and absorbed by the forest to maintain itself.