2 CBM_dataPrep_SK
This documentation is work in progress. Potential discrepancies and omissions may exist for the time being. If you find any regarding this module, contact us here.
2.1 Overview
CBM_dataPrep_SK processes spatially explicit inputs for use in CBM_vol2biomass and CBM_core. In SpaDES-speak, it has one event (init) - we might now change this to two events - stay tuned. 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. This module’s inputs are study area and scenario specific rasters making CBM_dataPrep_SK the most idiosyncratic module of the spadesCBM deck, meaning that this is the module that will require users to adapt to their available information for their study area. The default example simulates a present day (1985-2011) scenario where remotely-sensed disturbances are simulated in the managed forests of Saskatchewan, as described in Boisvenue et al. (2016)’s (scenario = time horizon + disturbances). We suggest 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 become CBM_dataPrep_NewStudyArea.
2.2 Background
The default structure of SpaDES modules has the .inputObjects function, and in the .inputObjects function of CBM_dataPrep_SK, we make use of the reproducible::prepInputs function which is an important part of the SpaDES toolkit (see the SpaDES training. CBM_dataPrep_SK falls back to the defaults CBM parameters for running the SK managed forests, unless alternative information is provided by the user.
The study area is spatially defined by the object masterRaster. This object can be provided directly as a raster, as per our example, or created from shape files or by other means. Reminder: 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, the age raster (ageRaster), the raster specifying where each growth curves are to be used (gcIndexRaster), location rasters that link back to the default parameters for Canada (spuRaster, ecoRaster), and the yearly disturbance rasters (provided as a list in this module disturbanceRaster, but process in the annual event of the CBM_core module using the function reproducible::postProcess, which is part of the reproducible::prepInputs function) are all matched to the masterRaster. Defaults parameters are expected from the CBM_defaults (spinupSQL, species_tr) and one table is provided cbmAdmin for user convenience. In addition to location (study area) 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 |
|---|---|---|---|
| dMatrixAssociation | Data table | Default disturbance IDs | CBM_defaults |
| spinupSQL | Data table | Parameters for CBM_core spinup event | CBM_defaults |
| species_tr | Data table | Default species data | CBM_defaults |
| gcMeta | Data table | Species and growth curve IDs | 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
Two central pieces are processed in CBM_dataPrep_SK: the pixelGroups are created and disturbances are matched with disturbance matrices.
2.4.1 Pixel Groups
pixelGroup are unique combinations of age, growth curve (which means species), spatial unit and ecozone. All pixels having identical age, growth curve, in the same spatial unit and ecozone share one pixelGroup number. The object allPixelDT has all the mixels in the masterRaster. The spatialDT object is the long-form where each simulated pixel has its own line (no N/A pixels), and level3DT lists only the pixel groups. In our example there are 1 347 529 pixels simulated (i.e., 1 347 529 pixels in spatialDT) which are grouped in 739 pixelGroups for actual processing.
2.4.2 Disturbances
The user identifies what disturbances occur on the landscape during the simulations. Our example points to a file (userGcM3) that has the disturbance name and description. The table also provides a number on the raster we provide to identify disturbances (one per year since our simulations are yearly), 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 specific pixel of our study area. 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:
MAYBE TO INSERT SCREEN SHOTS OF THE disturbance SELECTION PROCESS?
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 really 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). Add a section on how one would modify the disturbance matrices
Parameters necessary for the CBM_core spinup event are added to the level3DT object by using the CBM_defaults output object spinupSQL. This includes a match to the historical disturbance matrix (wildfire) specific to this location.
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 distrubances 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 |
| spatialDT | Data table | Summary table of raster input data with 1 row for each masterRaster pixel that is not NA
|
| level3DT | Data table | Table associating pixel groups with key attributes |
| speciesPixelGroup | Data table | Table connecting pixel groups to species IDs |
| ecozones | Numeric | Extracted ecozone IDs for each pixel group |
| spatialUnits | Numeric | Extracted spatial unit IDs for each pixel group |
| realAges | Numeric | Extracted ages for each pixel group |
| mySpuDmids | Data table | Summary table of possible CBM-CFS3 disturbances within study area spatial units |
| historicDMtype | Numeric | Historical disturbance type for each pixel group |
| lastPassDMtype | Numeric | Last pass disturebance type for each pizel group |