Package 'CBMutils'

Calculate stemwood biomass (per ha) of live merchantable trees

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

table3	data.frame corresponding to Table 3 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table3.csv.
vol	gross merchantable volume per hectare ($m^3/ha$)

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

---

barPlot

Description

barPlot

Usage

barPlot(cbmPools)

Arguments

cbmPools

TODO

Value

TODO

---

Proportions of total tree biomass in stemwood, bark, branches, and foliage

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, x, type = "volume")

Arguments

table6	data.frame corresponding to Table 6 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6.csv. The alternative table 6 for equations using total biomass as independent variable is available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6_tb.csv.
table7	data.frame corresponding to Table 7 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7.csv. The alternative table 7 for equations using total biomass as independent variable is available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7_tb.csv.
x	vector gross merchantable volume per hectare ($m^3/ha$) or total biomass ($tonnes/ha$)
type	character specifies if the x represents gross merchantable volume per hectare ("volume") or total biomass ("biomass").

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

---

Sum carbon for totalCarbon or aboveGround or belowGround

Description

Sum carbon for totalCarbon or aboveGround or belowGround

Usage

calcC(cbmPools, poolToSum, masterRaster)

Arguments

cbmPools	DESCRIPTION NEEDED
poolToSum	DESCRIPTION NEEDED
masterRaster	A SpatRaster object to use as the template

Value

DESCRIPTION NEEDED

---

carbonOutPlot

Description

carbonOutPlot

Usage

carbonOutPlot(emissionsProducts)

Arguments

emissionsProducts

TODO

Value

invoked for side effect of creating plot

---

Convert total above ground biomass into 3 pools ($T/ha$)

Description

Implements the flowchart from figure 3 of Boudewyn et al. (2007) using an alternative set of parameter to divide total above ground biomass ($T/ha$) into total merchantable stemwood biomass ($T/ha$), foliage biomass ($T/ha$), and other wood biomass ($T/ha$).

Usage

convertAGB2pools(oneCurve, table6, table7)

Arguments

oneCurve	data.frame with at least four following columns: canfi_species, ecozone, juris_id, and B.
table6	data.frame corresponding to Table 3 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6_tb.csv.
table7	data.frame corresponding to Table 4 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7_tb.csv.

Value

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

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

---

Calculate biomass from gross merchantable volume

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

meta	DESCRIPTION NEEDED
gCvalues	DESCRIPTION NEEDED
spsMatch	DESCRIPTION NEEDED
ecozones	DESCRIPTION NEEDED
params3	data.frame corresponding to Table 3 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table3.csv.
params4	data.frame corresponding to Table 4 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table4.csv.
params5	data.frame corresponding to Table 5 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table5.csv.
params6	data.frame corresponding to Table 6 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6.csv.
params7	data.frame corresponding to Table 7 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7.csv.

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

---

Create cumPools data.table

Description

Create cumPools data.table

Usage

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

Arguments

fullSpecies	DESCRIPTION NEEDED
gcMeta	DESCRIPTION NEEDED
userGcM3	DESCRIPTION NEEDED
stable3	DESCRIPTION NEEDED
stable4	DESCRIPTION NEEDED
stable5	DESCRIPTION NEEDED
stable6	DESCRIPTION NEEDED
stable7	DESCRIPTION NEEDED
thisAdmin	DESCRIPTION NEEDED

Value

cumPools data.table

---

Convert total above ground biomass into 3 pools ($T/ha$)

Description

Implements the flowchart from figure 3 of Boudewyn et al. (2007) using an alternative set of parameter to divide total above ground biomass ($T/ha$) into total merchantable stemwood biomass ($T/ha$), foliage biomass ($T/ha$), and other wood biomass ($T/ha$).

Usage

cumPoolsCreateAGB(allInfoAGBin, table6, table7, pixGroupCol)

Arguments

allInfoAGBin	data.frame with at least four following columns: canfi_species, ecozone, juris_id, age, B and a column for pixel group identifier.
table6	data.frame corresponding to Table 3 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6_tb.csv.
table7	data.frame corresponding to Table 4 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7_tb.csv.
pixGroupCol	the name of the column in allInfoAGBin serving as the pixel group identifier.

Value

biomass ($T/ha$) in each above ground pool for each cohort per pixel group.

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

---

Smooth the 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

cumPoolsRaw	Data.table with a numeric column called ⁠age`` and columns called ⁠colsToUse'.
colsToUse	A character vector of columns to smooth.
colsToUseNew	A character vector of column names for the new smoothed columns

Value

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

Author(s)

Celine Boisvenue and Eliot McIntire

---

CBM data prep: disturbanceRasters

Description

Process disturbanceRasters into a table of disturbanceEvents for the CBM_core module. Optionally resample to align with a template raster.

Usage

dataPrep_disturbanceRasters(
  disturbanceRasters,
  eventID = NULL,
  templateRast = NULL,
  year = NULL
)

Arguments

disturbanceRasters	terra SpatRaster or list of SpatRaster. Must be named with 4 digit years such that a single raster layer can be accessed for each disturbance year (e.g. disturbanceRasters[["2025"]]).
eventID	integer. Disturbance event ID. All non-NA cells will be included as events of this type. If NULL, the raster cell values must be the event IDs.
templateRast	terra SpatRaster. Optional template raster to align rasters with.
year	digit or character. One or more years to summarize disturbance events for. If NULL, all available years are summarized.

Value

disturbanceEvents data.table with integer columns 'pixelIndex', 'year', 'eventID'.

---

CBM data prep: disturbanceRastersURL

Description

Process disturbanceRastersURL into disturbanceRasters.

Usage

dataPrep_disturbanceRastersURL(disturbanceRastersURL, bandYears = NULL, ...)

Arguments

disturbanceRastersURL	character. URL of either an archive of raster files or a single raster file.
bandYears	4 digit numeric or character years. If the URL is of a single raster file, provide the disturbance years that each raster band represents.
...	additional arguments to reproducible preProcess

Value

disturbanceRasters. If URL is an archive: a list of terra SpatRaster where each item is named by the disturbance year. If URL is a single raster file: a terra SpatRaster where each raster band layer is named by the disturbance year.

---

Download and unzip URL

Description

Download and unzip URL

Usage

download_unzip_url(url, destdir, overwrite = FALSE)

Arguments

url	character.
destdir	character. Path to destination directory
overwrite	logical. Overwrite existing file

---

Standardized way to create gcids

Description

This uses the underscore delimiter between column names.

Usage

gcidsCreate(...)

Arguments

...	The data.table with ONLY the columns on which to determine unique gcids

---

Extract the parameters to apply to convert total biomass into pool biomass

Description

Extract the species- and location- specific parameters for equation 4-7 of Boudewyn et al. (2007). If there is no match for the given ecozone, the parameters for a different ecozone in the same province/territory is returned. If there is no match for a given province/territory, the parameters for a different province/territory in the same ecozone is returned. If there is no match for the given ecozone and province/territory, the parameters for a different location is returned.

Usage

getParameters(table6, table7, canfi_species, ecozone, juris_id)

Arguments

table6	data.frame corresponding to Table 3 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table6_tb.csv.
table7	data.frame corresponding to Table 4 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table7_tb.csv.
canfi_species	the canfi code of the species
ecozone	the code of the ecozone
juris_id	the 2-letter code for the province/territory

Value

a list with 2 vectors for the parameters in table6 and table7 respectively.

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

---

CBM-CFS3 Historical Disturbances

Description

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

Usage

histDist(spuIDs, localeID = 1, ask = FALSE, ...)

Arguments

spuIDs	Spatial unit ID(s)
localeID	CBM-CFS3 locale_id
ask	logical. If TRUE, prompt the user to choose the correct disturbance matches. If FALSE, the function will look for exact name matches.
...	arguments to spuDistMatch

Details

In all spatial units in Canada, the historical disturbance is set to fire. 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. 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: check this).

---

Plot all columns that are not id_col

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

inc	DESCRIPTION NEEDED
id_col	DESCRIPTION NEEDED
nrow	DESCRIPTION NEEDED
ncol	DESCRIPTION NEEDED
filenameBase	DESCRIPTION NEEDED
path	DESCRIPTION NEEDED
title	DESCRIPTION NEEDED
scales	DESCRIPTION NEEDED

---

Expansion factor for non-merchantable live tree biomass

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

table4	data.frame corresponding to Table 4 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table4.csv.
eq1	stemwood biomass of merchantable trees ($T/ha$) from equation 1 of Boudewyn et al. (2007) (i.e., the result of b_m()).
vol	gross merchantable volume per hectare ($m^3/ha$)

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

---

NPPplot

Description

NPPplot

Usage

NPPplot(spatialDT, NPP, masterRaster)

Arguments

spatialDT	TODO
NPP	TODO
masterRaster	A SpatRaster object to use as the template

Value

TODO

---

Install Python with reticulate::install_python

Description

Download the pyenv-win Python version management tool from Github if necessary. See: https://github.com/pyenv-win/pyenv-win

Usage

reticulate_install_python_windows(
  version = NULL,
  useGit = TRUE,
  prompt = interactive(),
  pyenvRoot = tools::R_user_dir("CBMutils")
)

Arguments

version	character. Python version string.
useGit	logical. Allow reticulate to clone pyenv-win if Git is available
prompt	logical. Prompt user to approve download of pyenv-win tool
pyenvRoot	character. Path to directory of where to download the pyenv-win tool

---

Python interpreter path

Description

Get path to Python interpreter, including installs at a given pyenv-win location

Usage

reticulate_python_path(
  version = NULL,
  pyenvRoot = tools::R_user_dir("CBMutils"),
  pyenvOnly = FALSE
)

Arguments

version	character. Python version or a comma separated list of version constraints. See ?reticulate::virtualenv_starter 'version' argument
pyenvRoot	character. Path to directory containing pyenv-win tool
pyenvOnly	logical. Exclude versions not within a pyenv install directory

Value

character or NULL. IF found, a path to Python interpreter

---

Reticulate find Python

Description

Use reticulate to find or install Python that meets version requirements. Download the pyenv-win Python version management tool from Github if necessary.

Usage

ReticulateFindPython(
  version,
  versionInstall = version,
  useGit = TRUE,
  prompt = FALSE,
  pyenvRoot = tools::R_user_dir("CBMutils"),
  pyenvOnly = FALSE
)

Arguments

version	character. Python version or a comma separated list of version constraints. See ?reticulate::virtualenv_starter 'version' argument
versionInstall	character. Version to install if suitable version not found. Defaults to 'version'. Required if 'version' is a string of versions constraints instead of a specific version.
useGit	logical. Allow reticulate to clone pyenv-win if Git is available
prompt	logical. Prompt user to approve download of pyenv-win tool
pyenvRoot	character. Path to directory of where to download the pyenv-win tool
pyenvOnly	logical. Exclude versions not within a pyenv install directory

Details

This function was created to bypass the requirement for Git to be installed when install_python is called on a Windows computer without pyenv-win already installed. pyenv-win is installed by reticulate by cloning the Github repository. This will instead download the pyenv-win repository as a ZIP file.

Note: If pyenv-win is installed by ZIP download instead of via Git clone, it will not be updated after the first time it is downloaded.

Value

character. Path to Python interpreter

---

Expansion factor for sapling-sized trees

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

table5	data.frame corresponding to Table 5 from Boudewyn et al. (2007), available from https://nfi.nfis.org/resources/biomass_models/appendix2_table5.csv.
eq2	two-column matrix giving stemwood biomass of non-merchantable trees (i.e., $b_n$ given in units $T/ha$), and merchantable + non-merchantable trees (i.e., $b_{nm}$ given in units $T/ha$), from equation 2 of Boudewyn et al. (2007) (i.e., the result of nmfac()).
vol	gross merchantable volume per hectare ($m^3/ha$)

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

---

See disturbances

Description

Retrieve disturbance source pools, sink pools, and the proportions transferred.

Usage

seeDist(
  EXN = TRUE,
  matrixIDs = NULL,
  dbPath = NULL,
  disturbance_matrix_value = NULL
)

Arguments

EXN	logical. Use CBM-EXN CBM-CFS3 equivalent model data.
matrixIDs	character. Optional. Subset disturbances by disturbance_matrix_id
dbPath	Path to CBM-CFS3 SQLite database file. Required if EXN = FALSE
disturbance_matrix_value	disturbance_matrix_value table from CBM-EXN Required if EXN = TRUE

Value

List of data.frame named by disturbance_matrix_id

---

See disturbances in simList

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

sim	A SpaDES CBM simulation (simList) object.

Value

List of data.frame for each disturbance matrix id in the study area, named by disturbance name

---

spatialPlot

Description

spatialPlot

Usage

spatialPlot(cbmPools, years, masterRaster, spatialDT)

Arguments

cbmPools	TODO
years	TODO
masterRaster	A SpatRaster object to use as the template
spatialDT	TODO

Value

TODO

---

CBM-CFS3 Spatial Unit Disturbances

Description

Identify the disturbances possible in spatial units.

Usage

spuDist(
  EXN = TRUE,
  spuIDs = NULL,
  dbPath = NULL,
  disturbance_matrix_association = NULL,
  localeID = 1
)

Arguments

EXN	logical. Use CBM-EXN CBM-CFS3 equivalent model data.
spuIDs	Optional. Subset by spatial unit ID(s)
dbPath	Path to CBM-CFS3 SQLite database file. Required if EXN = TRUE or EXN = FALSE.
disturbance_matrix_association	data.frame. Optional. Alternative disturbance_matrix_association table with columns "spatial_unit_id", "disturbance_type_id", and "disturbance_matrix_id". Required if EXN = TRUE.
localeID	CBM-CFS3 locale_id

Value

data.table with 'disturbance_type_tr' columns "spatial_unit_id", "disturbance_type_id", "name", "description" and 'disturbance_matrix_association' columns "spatial_unit_id" and "disturbance_matrix_id"

---

CBM-CFS3 Disturbances Match

Description

Match disturbance names with CBM-CFS3 spatial unit disturbances.

Usage

spuDistMatch(
  distTable,
  ask = interactive(),
  nearMatches = TRUE,
  listDist = NULL,
  ...
)

Arguments

distTable	data.table with columns 'spatial_unit_id' and 'name' (or 'distName'). The name column will be matched with disturbance names and descriptions in the CBM-CFS3 database.
ask	logical. If TRUE, prompt the user to choose the correct disturbance matches. If FALSE, the function will look for exact name matches.
nearMatches	logical. Allow for near matches; e.g. "clearcut" can match "clear-cut".
listDist	data.table. Optional. Result of a call to spuDist. A list of possible disturbances in the spatial unit(s) with columns 'spatial_unit_id', 'disturbance_type_id', 'disturbance_matrix_id', 'name', 'description'.
...	arguments to spuDist for listing the possible disturbances in the spatial units.

Value

data.table with columns 'spatial_unit_id' 'disturbance_type_id', 'disturbance_matrix_id', 'name', 'description'

---