Package 'CBMutils'

Description

Utilities for modelling carbon in R/SpaDES based on the Carbon Budget Model of the Canadian Forest Service v3 (CBM-CFS3).

Author(s)

Maintainer: Alex M Chubaty [email protected] (ORCID)

Authors:

• Céline Boisvenue [email protected]

• Eliot McIntire [email protected]

Other contributors:

• Ian Eddy [email protected] [contributor]

See Also

Useful links:

• https://CBMutils.predictiveecology.org/

• https://github.com/PredictiveEcology/CBMutils

Description

TODO: confirm these

Usage

.pooldef

.pooldefids

.poolnames

.poolids

Format

An object of class character of length 26.

An object of class environment of length 26.

An object of class character of length 25.

An object of class environment of length 25.

Details

NOTE: A reminder that indexing in R starts at 1, whereas in C++ it starts at 0. Several C++ data structures do not include the Input category, so the indices there are defined using .poolids - 1.

Description

Implements equation 1 of Boudewyn et al. (2007) to determines the total stemwood biomass of merchantable trees (in metric tonnes per hectare; $T/ha$), using parameters $a$ and $b$ from Table 3 (table3).

Usage

b_m(table3, vol)

Arguments

Value

stemwood biomass of merchantable trees ($b_m$ in units $T/ha$)

References

Boudewyn, P., Song, X., Magnussen, S., & Gillis, M. D. (2007). Model-based, volume-to-biomass conversion for forested and vegetated land in Canada (BC-X-411). Natural Resource Canada, Pacific Forestry Centre. https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/27434.pdf

Description

barPlot

Usage

barPlot(cbmPools, masterRaster)

Arguments

Value

TODO

Description

Biomass turnover matrix

Usage

biomassTurnoverMatrix(turnoverParam, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

Implements equations 4-7 of Boudewyn et al. (2007), used to determine the proportions of total tree biomass in stemwood, bark, branches, and foliage ($p_{stemwood}$, $p_{bark}$, $p_{branches}$, $p_{foliage}$, respectively), using parameters $a$, $b$ from Table 6 (table6) and volume-proportion caps from Table 7 (table7).

Usage

biomProp(table6, table7, vol)

Arguments

Details

TODO: will eventually add species, ecozone

Value

four-column matrix will columns corresponding to $p_{stemwood}$, $p_{bark}$, $p_{branches}$, and $p_{foliage}$

References

Boudewyn, P., Song, X., Magnussen, S., & Gillis, M. D. (2007). Model-based, volume-to-biomass conversion for forested and vegetated land in Canada (BC-X-411). Natural Resource Canada, Pacific Forestry Centre. https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/27434.pdf

Description

Sum carbon for totalCarbon or aboveGround or belowGround

Usage

calcC(cbmPools, poolToSum, masterRaster)

Arguments

Value

DESCRIPTION NEEDED

Description

For all spatial units in the simulation, calculate turnover rates.

Usage

calcTurnoverRates(turnoverRates, spatialUnitIds, spatialUnits)

Arguments

Value

extracts the turnover rates for the specific SPU you are in. These are used to in the core module to calculate the specific rates, which are the used to calculate Net Primary Productivity (NPP) both in the core module and in the next function.

Description

carbonOutPlot

Usage

carbonOutPlot(emissionsProducts, masterRaster)

Arguments

Value

invoked for side effect of creating plot

Description

check that the proportions add up to 1

Usage

checkProp(DTofMatrices, tarCols)

Arguments

Value

DESCRIPTION NEEDED

Description

Post-simulations, this function takes the last two years of simulations, and verifies that the C transfers are as expected on n random pixelGroups. It randomly selects three pixelGroups, calculated the expected transactions from time end(sim) and time end(sim) - 1, and compares them to the last year of simulations. Cases of disturbed, non disturbed, sw, hw, young and old stands were tested.

Usage

checkTransactions(
  cbmPools,
  pixelKeep,
  opMatrixCBM,
  allProcesses,
  pixelGroupC,
  pooldef,
  timeSim,
  outputsSim,
  n = 3
)

Arguments

Structure

1. Read-in data

2. randomly select 3 pixelGroups

3. read-in carbon pools at timeSim and timeSim - 1 for the three pixelGroup

4. pull-out matrices applied to these three pixelGroups between t0 and t1

5. matrices into a data.table

6. prep pools at t0

7. merge three pools at t0 with their respective transaction matrices ids

8. apply all matrices (8.1:8.9)

TODO: I am passing a whole simList here for simplification, but only these objects needed:

1. ⁠$cbmPools⁠;

2. ⁠$pixelKeep⁠;

3. ⁠$opMatrixCBM⁠;

4. ⁠$allProcesses⁠;

5. ⁠$pooldef⁠.

TODO: there are still a bunch of checks that need to be changed to assertions (if statements?)

All arguments come from a simList object of the same name, except timeSim (which comes from time(sim)) and outputsSim (which comes from outputs(sim)).

Description

Compute Turnover Matrices

Usage

computeBioTurnoverMatrices(turnoverParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

The first column in the specified decayRates parameter acts as the key to each matrix.

Usage

computeDomDecayMatrices(decayRates, decayParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

Compute DOM turnover matrices

Usage

computeDomTurnoverMatrices(turnoverParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

DESCRIPTION NEEDED

Arguments

Description

DESCRIPTION NEEDED

Usage

ComputeGrowthAndDeclineMatrices2(
  growthIncrements,
  ages,
  gcids,
  pools,
  rootParameters,
  turnoverParams,
  biomassToCarbonRate,
  swMult = 1,
  hwMult = 1
)

Arguments

Description

Transforms growth matrix into coordinate format matrix in terms of CBM pools.

Arguments

Description

Compute the total growth (above ground and belowground) increment matrices for all stands based on age and hashtable of growth increments by growth curve id.

Usage

ComputeGrowthIncrements(
  growthIncrements,
  ages,
  gcids,
  pools,
  rootParameters,
  biomassToCarbonRate,
  swMult = 1,
  hwMult = 1
)

Arguments

Description

Compute flows to dom pools that occur on a growth curve decline.

Usage

ComputeOvermatureDecline(growthIncrements, turnoverParams)

Arguments

Description

Transforms overmature decline matrix into coordinate format matrix in terms of CBM pools.

Arguments

Description

Compute slow decay matrices

Usage

computeSlowDecayMatrices(decayRates, decayParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

Compute slow mixing matrix

Usage

computeSlowMixingMatrix(slowMixingRate, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

Implements the flowchart from figure 3 of Boudewyn et al. (2007) to determined the total above ground biomass ($T/ha$) from gross merchantable volume ($m^3/ha$).

Usage

convertM3biom(
  meta,
  gCvalues,
  spsMatch,
  ecozones,
  params3,
  params4,
  params5,
  params6,
  params7
)

Arguments

Value

three-column matrix with columns corresponding to biomass ($T/ha$) for total merchantable, foliage, and other.

References

Boudewyn, P., Song, X., Magnussen, S., & Gillis, M. D. (2007). Model-based, volume-to-biomass conversion for forested and vegetated land in Canada (BC-X-411). Natural Resource Canada, Pacific Forestry Centre. https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/27434.pdf

Description

Create cumPools data.table

Usage

cumPoolsCreate(
  fullSpecies,
  gcMeta,
  userGcM3,
  stable3,
  stable4,
  stable5,
  stable6,
  stable7,
  thisAdmin
)

Arguments

Value

cumPools data.table

Description

This uses the Chapman Richards equation to smooth the curves that are in colsToUse.

Usage

cumPoolsSmooth(
  cumPoolsRaw,
  colsToUse = c("totMerch", "fol", "other"),
  colsToUseNew = paste0(colsToUse, "_New")
)

Arguments

Value

#' A data.table with original columns plus new columns named 'colsToUseNew“.

Author(s)

Celine Boisvenue and Eliot McIntire

Description

DESCRIPTION NEEDED

Description

This is the ecological theory for decomposing being used in CBM.

Usage

decayRate(meanAnnualTemp, baseDecayRate, q10, tref, max)

Arguments

Value

the scalar rate of decay

Description

Compute a single dom decay matrix based on the specified table of decay rates

Usage

domDecayMatrix(decayRates, decayParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

Calculate a portion of the DOM decay matrix

Usage

domDecayMatrixItem(mat, decayRates, propToAtmosphere, src, dst, emission)

Arguments

Value

A modified copy of the input mat

Description

DOM turnover matrix

Usage

domTurnOverMatrix(turnoverParam, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

This uses the underscore delimiter between column names.

Usage

gcidsCreate(...)

Arguments

Description

Returns a vector of decay rates where the indices of the vector are the DOM pools of CBM.

Usage

getDecayRates(meanAnnualTemp, decayParameters, domPools)

Arguments

Value

the vector of decay rates

Description

DESCRIPTION NEEDED

Usage

getIdentityCoordinateMatrix(size)

Arguments

Description

DESCRIPTION NEEDED

Usage

getTable(filename, dbPath, sqlDir)

Arguments

Description

DESCRIPTION NEEDED

Usage

hash(x)

matrixHash(x)

Arguments

Description

Identifies the stand-replacing wildfire disturbance in each spatial unit.

Usage

histDist(mySpu = c(27, 28))

Arguments

Details

Historical disturbances in CBM-CFS3 are used for "filling-up" the soil-related carbon pools. Boudewyn et al. (2007) translate the m3/ha curves into biomass per ha in each of four pools: total biomass for stem wood, total biomass for bark, total biomass for branches and total biomass for foliage. Biomass in coarse and fine roots, in aboveground- and belowground- very-fast, -fast, -slow, in medium-soil, and in snags still needs to be estimated. In all spatial units in Canada, the historical disturbance is set to fire. A stand-replacing fire disturbance is used in a disturb-grow cycle, where stands are disturbed and regrown with turnover, overmature, decay, functioning until the dead organic matter pools biomass values stabilize (+/- 10%).

TODO: (I think but that is in the Rcpp-RCMBGrowthIncrements.cpp so can't check).

By default the most recent is selected, but the user can change that.

Description

Load disturbance matrix IDs

Usage

loadDisturbanceMatrixIds(disturbanceMatrixValues, dbPools)

Arguments

Value

DESCRIPTION NEEDED

Description

m3ToBiomIncOnlyPlots

Usage

m3ToBiomIncOnlyPlots(inc)

Arguments

Value

TODO

Description

Plot all columns that are not id_col

Usage

m3ToBiomPlots(
  inc = "increments",
  id_col = "gcids",
  nrow = 5,
  ncol = 5,
  filenameBase = "rawCumBiomass_",
  path = NULL,
  title = "Cumulative merch fol other by gc id",
  scales = "free_y"
)

Arguments

Description

Check the growth increments by above ground pool. This is necessary because the Boudewyn et al parameters used to translate the m3/ha into biomass/ha do not always work. Returns a list of plots, each plot show the merch, fol, and other increments for a specific growth curve.

Usage

m3ToVolCheckPlots(sim)

Arguments

Description

Make a data.table out of the carbon transfer matrices

Usage

matrixDT(matricesIn, indicesIn)

Arguments

Value

a data.table object summarizing the carbon transfers

Description

Implements equation 2 of Boudewyn et al. (2007), used to determine the total stem wood biomass (in metric tonnes per hectare; $T/ha$) of non-merchantable trees ($B_n$), together with the stemwood biomass of live merchantable and non-merchantable trees ($B_{nm}$), using parameters $a$, $b$, and $k$ from Table 4 (table4).

Usage

nmfac(table4, eq1, vol)

Arguments

Value

two-column matrix with columns corresponding to $b_n$ and $b_{nm}$

References

Boudewyn, P., Song, X., Magnussen, S., & Gillis, M. D. (2007). Model-based, volume-to-biomass conversion for forested and vegetated land in Canada (BC-X-411). Natural Resource Canada, Pacific Forestry Centre. https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/27434.pdf

Description

Calculate post-simulation net primary productivity

Usage

NPP(pools, pixelGroupSpu, year1, year2, turnoverRates)

Arguments

Examples

## Not run: 
  spadesCBMout <- simInitAndSpades() ## TODO: fill this in
  NPP(pools = spadesCBMout$cbmPools,
      pixelGroupSpu = spadesCBMout$pixelGroupC[, .(pixelGroup, spatial_unit_id)],
      year1 = 1990, year2 = 1991,
      turnoverRates = spadesCBMout$turnoverRates)

## End(Not run)

Description

NPPplot

Usage

NPPplot(spatialDT, NPP, masterRaster)

Arguments

Value

TODO

Description

Plotting pools

Usage

plotCarbonRasters(pixelkeep, cbmPools, poolsToPlot, years, masterRaster)

Arguments

Examples

## Not run: 
# include 'totalCarbon' in poolsToPlot to add plot of total carbon
plotCarbonRasters(
  cbmPools = spadesCBMout$cbmPools,
  poolsToPlot = c("totalCarbon", "BelowGroundSlowSoil"),
  masterRaster = spadesCBMout$masterRaster,
  pixelkeep = spadesCBMout$pixelKeep,
  years = c(1990, 2000, 2005)
)

## End(Not run)

Description

prepInputsEcozones

Usage

prepInputsEcozones(url = NULL, dPath, rasterToMatch)

Arguments

Description

Read in the BC VRI, with growth curve information (from ws3), and creates a raster stack of the age and gcID.

Usage

prepInputsVRI(url, dPath, rasterToMatch)

Arguments

Description

Read in the BC VRI, with growth curve information (from ws3), and creates a raster stack of the age

Usage

prepInputsVRIage(
  VRIurl,
  dPath,
  rasterToMatch,
  targetFile,
  field = "PROJ_AGE_1"
)

Arguments

Description

DESCRIPTION NEEDED

Usage

query(dbPath, sql)

Arguments

Description

DESCRIPTION NEEDED

Usage

readSqlFile(filePath)

Arguments

Description

Produce a raster with spUnits

Usage

retrieveSpuRaster(
  spatialUnitsFile = shapefile("data/spUnit_Locator.shp"),
  UserArea,
  rasterRes = c(250, 250)
)

Arguments

Examples

## Not run: 
  test1 <- raster::shapefile("data/forIan/SK_data/CBM_GIS/SpadesCBM_TestArea.shp")
  out1 <- retrieveSpuRaster(UserArea = test1, rasterRes = c(250, 250))
  if (interactive()) Plot(out1)


## End(Not run)

Description

Implements equation 3 of Boudewyn et al. (2007), used to determine the total stem wood biomass (in metric tonnes per hectare; $T/ha$) of sapling-sized trees ($B_s$), using parameters $a$, $b$, and $k$ from Table 5 (table5).

Usage

sapfac(table5, eq2, vol)

Arguments

Value

stemwood biomass of sapling-sized trees ($b_s$ in units $T/ha$)

References

Boudewyn, P., Song, X., Magnussen, S., & Gillis, M. D. (2007). Model-based, volume-to-biomass conversion for forested and vegetated land in Canada (BC-X-411). Natural Resource Canada, Pacific Forestry Centre. https://cfs.nrcan.gc.ca/pubwarehouse/pdfs/27434.pdf

Description

Get the descriptive name of the disturbance, the source pools, the sink pools, and the proportions transferred.

Usage

seeDist(
  distId = c(161, 230, 313, 361),
  dbPath = file.path("data", "cbm_defaults", "cbm_defaults.db")
)

Arguments

Value

A list of data.frames, one per disturbance matrix id.

Description

get the descriptive name and proportions transferred for disturbances in a simulation requires a simulation list post simulations (from spades()) and returns a list of data.frames. Each data had the descriptive name of a disturbance used in the simulations, the disturbance matrix identification number from cbm_defaults, the pool from which carbon is taken (source pools) in this specific disturbance, the pools into which carbon goes, and the proportion in which the carbon-transfers are completed.

Usage

simDist(sim)

Arguments

Description

Slow decay matrix

Usage

slowDecayMatrix(decayRates, decayParameters, PoolCount)

Arguments

Value

DESCRIPTION NEEDED

Description

spatialPlot

Usage

spatialPlot(pixelkeep, cbmPools, poolsToPlot, years, masterRaster)

Arguments

Value

TODO

Description

the spatialPlot function plots rasters directly, but does not return rasters, whereas it does so here.

Usage

spatialRaster(pixelkeep, cbmPools, poolsToPlot, years, masterRaster)

Arguments

Value

RasterLayer but invoked for its side-effect of plotting the rasters.

See Also

spatialPlot

Description

Spatial unit decay rates

Usage

spatialUnitDecayRates(climate, decayparameters, domPools)

Arguments

Value

DESCRIPTION NEEDED

Description

Spinup a landscape by running rotations of stand replacing disturbances repeatedly until the pre-disturbance slow pools and the last rotation pre-disturbance slow pools are within a tolerance. Stand then grows to inventory age, and is ready for CBM simulation.

Usage

Spinup(
  pools,
  opMatrix,
  constantProcesses,
  growthIncrements,
  ages,
  gcids,
  historicdmids,
  lastPassdmids,
  delays,
  minRotations,
  maxRotations,
  returnIntervals,
  rootParameters,
  turnoverParams,
  biomassToCarbonRate,
  debug = FALSE
)

Arguments

Description

You give is spatial units you are targeting mySpu and it gives you the disturbance matrix id that are possible/default in that specific spu and a descriptive name of that disturbance matrix it creates a data.frame of length number of disturbances, with three columns: spatial_unit_is, disturbance_matrix_id, and a desciption of the disturbance.

Usage

spuDist(mySpu, dbPath)

Arguments

Details

TODO: can we have a Canada-wide SPU map and they locate themselves on the map? this needs to be done before simulations are run so the user can provide this info (location info) for the simulations - Ian is working on this.

the function has the defaults from the SK managed forest example. These can be changed by feeding in other SPU.

Examples

## Not run: 
  ## using raster
  library(terra)
  spuRaster <- rast(file.path("data/forIan/SK_data/CBM_GIS/spUnits_TestArea.tif"))
  spatial_unit_id <- values(spuRaster) # 28 27
  mySpu <- unique(spatial_unit_id)

  ## using growth curves
  f <- file.path("spadesCBMinputs/data/SK_ReclineRuns30m/LookupTables/yieldRCBM.csv")
  gcIn <- as.matrix(read.csv(f))
  mySpu <- unique(gcIn[, 1])

## End(Not run)

Description

Computes by row (stand/pixelGroup) across all columns (pools).

Usage

StepPools(pools, opMatrix, flowMatrices)

Arguments

Examples

nPixGrp <- 3

pools <- matrix(c(1.0, 10.0, 0.0, 1.0, 20.0, 0.0, 1.0, 5.0, 0.0),
                ncol = 3, nrow = nPixGrp, byrow = TRUE)
colnames(pools) <- c("input", "pool1", "pool2")
pools

##      input pool1 pool2
## [1,]     1    10     0
## [2,]     1    20     0
## [3,]     1     5     0

op <- matrix(rep(c(1, 1), nPixGrp), ncol = 2, nrow = nPixGrp, byrow = TRUE)
colnames(op) <- c("disturbance", "growth")

cnames <- c("row", "col", "value")
dist <- matrix(c(2, 3, 1, 1, 1, 1), ncol = 3, nrow = 2, byrow = TRUE)
colnames(dist) <- cnames
grow <- matrix(c(1, 2, 0.1, 1, 3, 0.2, 2, 3, 0.3, 3, 3, 1.0), ncol = 3, nrow = 4, byrow = TRUE)
colnames(grow) <- cnames
flow <- list(Disturbance = list(dist), Growth = list(grow))

new_pools <- StepPools(pools, op, flow)
new_pools

##      input pool1 pool2
## [1,]     1   0.1  10.2
## [2,]     1   0.1  20.2
## [3,]     1   0.1   5.2

Description

Computes by row (stand/pixelGroup) across all columns (pools) in place.

Usage

StepPoolsRef(pools, opMatrix, flowMatrices)

Arguments

Description

ws3, the harvest optimizer created by Greg Paradis provided the BC disturbance rasters (harvest or harvest and fires) per TSA and not for the whole study area. This function reads-in the file structure, pulls in all the TSA-level rasters, knits them together and post-processes them to match the rasterToMatch.

Usage

ws3Build(masterRaster, tsaDirs, years, pathsTifs)

Arguments