2 CBM_dataPrep_SK
This documentation is work in progress. Potential discrepancies and omissions may exist for the time being. If you find any, please contact us here.
2.1 Overview
CBM_dataPrep_SK processes spatially explicit inputs for use in CBM_vol2biomass_SK and CBM_core. In SpaDES-speak, it has two events, the init event (scheduled once) and the readDisturbanceEvents which processes disturbances (usually provided as rasters) into a table format used in CBM_core. SpaDES was designed for spatially explicit modelling and provides a wide variety of tools to support it. CBM_dataPrep_SK makes use of these tools. All location specific or spatial information is processed in this module. This module’s inputs are study area and scenario specific making CBM_dataPrep_SK the most idiosyncratic module of the spadesCBM deck, meaning that this is the module that will require users to adapt their available information for their study area. We use an example that simulates a scenario where remotely-sensed disturbances are simulated in the managed forests of Saskatchewan from 1985 to 2011, as described in Boisvenue et al. (2016) (scenario = time horizon + disturbances). We suggest that users wanting to run spadesCBM for their study-area modify this module, adapting their inputs to produce the outputs of CBM_dataPrep_SK. The module would then become CBM_dataPrep_NewStudyArea.
2.2 Background
The default structure of SpaDES modules has the .inputObjects function, and in this function in CBM_dataPrep_SK, we make use of the reproducible::prepInputs function, an important part of the SpaDES toolkit (see the SpaDES training manual for more details), enabling repeatable continuous workflows. CBM_dataPrep_SK falls back to the defaults CBM parameters for running the SK managed forests, unless alternative information is provided by the user.
Our example study area is defined by the object masterRaster. In our example, this raster is provided directly, but note that any R-code can replace current input processing examples in CBM_dataPrep_SK. The characteristics (projection, resolution, etc.) of this masterRaster are transferred to other rasters used in the simulation via the function reproducible::prepInputs. In our example, rasters for age (ageRaster), growth curves location (gcIndexRaster), and ecozone (ecoRaster) and spatial unit (spuRaster), link back to the default parameters for Canada. Yearly (as this is the time step in our example - run times(simMngedSK) to see current, start, and end time) disturbance rasters provide the type and location of disturbances. All rasters are matched to the masterRaster using the reproducible::prepInputs function. Default parameters are expected from CBM_defaults (spinupSQL, species_tr) and one table is provided as cbmAdmin for user convenience. In addition to location (study area or masterRaster) and inventory information (age, here provided as a raster), the user is expected to provide: growth curves (\(m^3/ha\)) that are linked to each pixel or stand (userGcM3), the leading species for each curve (gcMeta), and information about disturbances (userDist).
2.3 Inputs
| Name | Class | Description | Source |
|---|---|---|---|
| dbPath | Character | Path to the CBM defaults SQL database | CBM_defaults |
| disturbanceMatrix | Data table | Default disturbance data | CBM_defaults |
| CBMspecies | Data table | Default species data | CBM_defaults |
| gcMeta | Data table | Growth curve metadata | Google Drive |
| userGcM3 | Data table | User provided growth curve data | Google Drive |
| masterRaster | SpatRaster | Raster of study area | User provided, for SK: Google Drive |
| ageRaster | SpatRaster | Raster ages for each pixel | Google Drive |
| gcIndexRaster | SpatRaster | Raster giving the growth curve value for each pixel | Google Drive |
| spuLocator | SpatRaster | Canada’s spatial units as polygon features with spatial unit IDs | CBM_defaults |
| ecoLocator | SpatRaster | Canada’s ecozone as polygon features with ecozone IDs | CBM_defaults |
| disturbanceRasters | Character | Disturbance rasters for the study area for the duration of simulation | User provided, for SK: Google Drive |
| userDist | Data table | User provided disturbance table defining distubances and values in disturbanceRasters
|
User provided, for SK: Google Drive |
2.4 Module functioning
CBM_dataPrep_SK has 2 events; the init event, which is run only once, and the readDisturbanceEvents event, which is repeated for each simulation year.
2.4.1 init
This first event performs the majority of the data processing steps in this module. The study area’s various spatial data is also processed into a table format for use in the CBM_core and CBM_vol2biomass_SK modules. This event is run only once.
2.4.2 readDisturbanceEvents
This short event serves to process disturbance events for each simulation year. Separating this processing from the init event enables dynamic linkages to disturbance models. However, in our example, disturbances are provided in the form of remotely-sensed disturbance rasters.
2.4.3 Disturbances
The user identifies what disturbances occur on the landscape during the simulations. Our example points to a file that has the disturbance name and description, userDist. The table also provides a raster values that differentiates between disturbance types (in our example, we provide one raster per year, which has all disturbances in that year, each having a unique raster value, as opposed to one individual raster per year per disturbance type), and identifies if the disturbance is a whole stand disturbance or not. These disturbances need to be match to a disturbance matrix, which identifies the proportion of carbon transferred from one pool (source_pool) to another pool (sink_pool) when a disturbance occurs in that pixel. If there is more than one match (e.g., more than one type of fire), the user will be prompted to select from a list of disturbance matrices available for the study area, for each spatial unit and ecozone combinations. The default matrices are provided in the Canada-wide defaults and are region (spatial unit and ecozone) specific. These are read-in by CBM_defaults and available to the CBM_dataPrep_SK module via the simList(). We provide an example of selection in our example. The user-prompts look like this:
There are 468 unique disturbance matrices identified in the defaults. Since root parameters and snag carbon transfer rates have hardwood and softwood specific rates, each disturbance has a hardwood and a softwood instance, which means we have 234 unique disturbances across Canada as defaults in this modelling system, one for hardwood and one for softwood. A user could add or modify the proportions transferred between pools to represent a disturbance (NOTE THAT THIS WOULD HAVE TO HAPPEN IN THE CSVs, and even then would that work? Does libcbm point to those files? what if we change them? QUESTION FOR SCOTT, VINI and SUSAN). Add a section on how one would modify the disturbance matrices
Figure 1: Proportional carbon transfers between pools during a fire in Saskatchewan
There are a series of helper functions in CBMutils to help users explore and navigate disturbance matrices: - spuDist for extracting the disturbances in a specific spatial unit, - simDist() which lists the disturbances used in a simulation, and - seeDist() which pulls out the proportions from source to sink pools.
Because growth curves can be identified by strata, multiple columns can be used to identify growth curves using the curveID object. In our example, only gcids is used.
2.5 Outputs
| Name | Class | Description |
|---|---|---|
| allPixDT | Data table | Summary table of raster input data with 1 row for each masterRaster pixel |
| standDT | Data table | Table of stand attributes. Stands can have 1 or more cohorts |
| cohortDT | Data table | TAble of cohort attributes |
| spatialDT | Data table | Summary table of raster input data with 1 row for each masterRaster pixel that is not NA
|
| curveID | Character | Column names in cohortDT that uniquely define each cohort growth curve ID |
| gcMeta | Data table | Growth curve metadata |
| userGcM3 | Data table | User provided growth curve data |
| disturbanceMeta | Data table | Table defining disturbance event types |
| disturbanceEvents | Data table | Table with disturbance events for each simulation year |
| speciesPixelGroup | Data table | Table connecting pixel groups to species IDs |