Skip to main content

CBM Spades Manual: v. 0.1

3 CBM_dataPrep_SK

3.1 Overview

This module is to read-in user-provided information or provide defaults. It reads-in rasters (ageRaster, ecoRaster, gcIndexRaster, spuRaster, and masterRaster) from either defaults of provided by the user. From the rasters, pixelGroup are created which are unique combinations of the rasters values. pixelGroup is a main processing unit in SpaDES CBM simulations. In a first step, a spatialDT which is a data.table listing all pixels with their respective values of raster, pixelIndex and pixelGroup is created (sim$spatialDT). From the spatialDT, a reduced data.table is create (sim$level3DT) which is the data.table from which processing will start in CBM_core. The number of records in this data.table (sim$level3DT) should equal the number of pixel groups that will be processed in the spinup event of the CBM_core module. This present module also creates variables of the same length as the rows in level3DT for use in other events of the CBM_core module. These are: returnIntervals, maxRotations, minRotations, lastPassDMIDs, historicDMIDs, and delays all stored in the simList.

Another important object created in this module is mySpuDmids. This data.table links the user-defined disturbances ($userDist) with a spatial unit and a disturbance matrix. This will be used to apply disturbances to pixel groups in the annual event of the CBM_core module. The mySpuDmids object is created starting from a user provided list of disturbances (userDist) that matches the rasterId of the disturbance raster to the disturbance name, and speficies if the disturbance is stand-replacing (userDist$wholeStand == 1) or not (userDist$wholeStand == 1). The disturbance names (userDist$distName) and their location of the disturbance (linked via the rasterID to the sim$mySpuDmids$spatial_unit id) are used to associate a disturbance matrix identification number to the disturbed pixelGroup. Disturbance Matrices (DM) determine what proportion of a carbon pool gets transferred to another carbon pool via disturbance. There are 426 matrix IDs in the present default data (sim$processes$disturbanceMatrices). DMIDs (Disturbance Matrix IDs) are part of the default data of CBM-CFS3. DMs are specific to spatial units which are a numbering (48 of them sim$cbmData@spatialUnitIds) of the overlay of the administrative boundaries and ecozones in Canada. Spatial units are central units in CBM-CFS3, as are ecozones because both determining various ecological and other parameters that will be used in simulations via the CBM_core module. The proportion of carbon transferred by a specific DMID can be found here sim$cbmData@disturbanceMatrixValues. A series of R-functions were built to help users associate the correct disturbance matrices (spuDist(), mySpu(), seeDist(), simDist()) and are searchable in this package.

Note: * CBM_defaults objects are recreated in the .inputObject of this module * nothing is in carbon or carbon increments at this point. This module feeds into the CBM_core module as does the CBM_vol2biomass.R module.

3.2 Usage 

library(igraph)
library(SpaDES.core)

moduleDir <- getwd()
inputDir <- file.path(moduleDir, "inputs") %>% reproducible::checkPath(create = TRUE)
outputDir <- file.path(moduleDir, "outputs")
cacheDir <- file.path(outputDir, "cache")
times <- list(start = 0, end = 10)
parameters <- list(
  #CBM_dataPrep = list(.useCache = ".inputObjects")
 #.progress = list(type = "text", interval = 1), # for a progress bar
 ## If there are further modules, each can have its own set of parameters:
 #module1 = list(param1 = value1, param2 = value2),
 #module2 = list(param1 = value1, param2 = value2)
 )
modules <- list("CBM_dataPrep_SK")
objects <- list(
  userDistFile = file.path(moduleDir, "CBM_dataPrep_SK", "data", "userDist.csv")
)
paths <- list(
  cachePath = cacheDir,
  modulePath = moduleDir,
  inputPath = inputDir,
  outputPath = outputDir
)

myInputs <- simInit(times = times, params = parameters, modules = modules,
                    objects = objects, paths = paths)

outInputs <- spades(myInputs)

3.3 Events

There is only when event (init) is this module.

3.4 Data dependencies

3.4.1 Module parameters

3.4.2 Input data

An example with all the user-provided rasters and .csv files is provided by default. The example simulates a region of the managed forests of SK. All rasters and data frames for this example are on a cloud-drive (userDefaultData_CBM_SK). Unless using this example, the user most provide:

  • a raster of the study area at the desired resolution for simulation (sim$masterRaster)
  • an age raster (sim$ageRaster)
  • a raster indicating which growth curve should be applied to which pixels (sim$gcIndexRaster) or a URL for this raster (sim$gcIndexRasterURL).
  • raster of disturbances for each year the user wants disturbances to be simulated. This information could come from other SpaDES modules (fireSence, other fire modules, insects modules, etc.). For retrospective simulation (past to present), rasters found here can be used anywhere in Canada https://opendata.nfis.org/downloads/forest_change/CA_forest_harvest_mask_year_1985_2015.zip.
  • a .csv file of the growth curve for the study area (with links to the sim$gcIndexRaster), sim$userGcM3.csv or the location of this file (sim$userGcM3File). The sim$userGcM3.csv file is required to have three columns:
    • “GrowthCurveComponentID”, which will be the link to the raster sim$gcIndexRaster,
    • “Age” ranging from 0 to the maximum age of the growth curve, and
    • “MerchVolume” which is the cumulative value of m3/ha at each age along each growth curve.
  • a file with the disturbances to be applied as well as their raster values (sim$userDist) or its location (sim$userDistFile). The userDist.csv file must have three columns:
    • “distName” representing a simple description of the disturbance type (e.g., fire, clearcut, deforestation, etc.).
    • “rasterId” which indications the value that this specific disturbance will have on the disturbance raster.
    • “wholeStand” indicating if the disturbance is stand-replacing disturbance (1) or a partial disturbance (0).

The user could provide: * a raster of the ecozones in their study area (sim$ecoRaster), but the script will calculate this raster based on the sim$masterRaster if it is not provided. * a raster of the spatial units (sim$spuRaster) but the script will calculate this raster based on the sim$masterRaster if it is not provided.

3.4.3 Output data