3 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.
3.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).SpaDES was designed for spatially explicit modelling and provides a wide variety of tools to support it. CBM_dataPrep_SK processes spatially explicit inputs for spadesCBM, making use of these tools. This information is study area and scenario specific making CBM_dataPrep_SK the most idiosyncratic module of the spadesCBM deck. Users have the capacity to define their simulation through the inputs they provide to CBM_dataPrep_SK. 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).
3.2 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 | https://drive.google.com/file/d/189SFlySTt0Zs6k57-PzQMuQ29LmycDmJ/view?usp=sharing |
| userGcM3 | Data table | User provided growth curve data | https://drive.google.com/file/d/1u7o2BzPZ2Bo7hNcC8nEctNpDmp7ce84m |
| masterRaster | SpatRaster | Raster of study area | User provided, for SK: https://drive.google.com/file/d/1zUyFH8k6Ef4c_GiWMInKbwAl6m6gvLJW |
| ageRaster | SpatRaster | Raster ages for each pixel | https://drive.google.com/file/d/1hylk0D1vO19Dpg4zFtnSNhnyYP4j-bEA |
| gcIndexRaster | SpatRaster | Raster giving the growth curve value for each pixel | https://drive.google.com/file/d/1yunkaYCV2LIdqej45C4F9ir5j1An0KKr |
| 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: https://drive.google.com/file/d/12YnuQYytjcBej0_kdodLchPg7z9LygCt |
| userDist | Data table | User provided disturbance table defining distubances and values in disturbanceRasters
|
User provided, for SK: https://drive.google.com/file/d/1n4fXwUkX5GPyWJgr0QQx65roAIaxmcWJ |
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, tools that enable repeadability and reproducibility ((McIntire2022?)). CBM_dataPrep_SK falls back to the defaults for running the SK managed forests, unless alternative information is provided by the user. These defaults give an example users can developed their own scenarios on.
The study area is 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 by the user. Any R-code can replace current input processing examples in CBM_dataPrep_SK. The characteristics (projection, resolution, etc.) of this masterRaster are transferred to all 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 is 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 cbmAdminfor 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).
3.3 Module functioning
Two central pieces are processed in CBM_dataPrep_SK: the pixelGroups are created and the named disturbances are matched with disturbance matrices.
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 spatialDT is the long-form where each simulated pixel has its own line, and level3DT lists only the pixel groups. In our example there are 1,347,529 pixels simulated which are grouped in 739 pixelGroups for actual processing. Parameters necessary for the CBM_core spinup are added to the level3DT object by using the output object spinupSQL from CBM_defaults.
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, matches that to 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 something else then the defaults are used, 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. These 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 differ between hardwood and softwood in this model, 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
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 one column is used, “gcids”.
3.4 List of output objects
| 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 |