title | date | output | editor_options | bibliography | citation-style | link-citations | always_allow_html | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
LandR _Biomass_speciesParameters_ Manual |
Last updated: 2024-04-29 |
|
|
citations/references_Biomass_speciesParameters.bib |
citations/ecology-letters.csl |
true |
true |
(ref:Biomass-speciesParameters) Biomass_speciesParameters
Ian Eddy ian.eddy@nrcan-rncan.gc.ca [aut, cre], Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut], Ceres Barros ceres.barros@ubc.ca [ctb]
This documentation is work in progress. Potential discrepancies and omissions may exist for the time being. If you find any, contact us using the "Get help" link above.
LandR Biomass_speciesParameters (hereafter Biomass_speciesParameters)
calibrates species growth and mortality trait values used in Biomass_core, by
matching theoretical species' growth curves obtained with different trait values
(see Simulated species data) against observed growth
curves derived from Permanent Sample Plots (PSP data) across Canada (see
Permanent sample plot data), to find the combination of
trait values that allows a better match to the observed curves. In particular,
it calibrates the growthcurve
, mortalityshape
, maximum biomass (maxB
) and
maximum aboveground net primary productivity (maxANPP
) traits (see Parameter estimation/calibration).
This module will not obtain other traits or parameters used in Biomass_core and so it is meant to be used in conjunction with another data/calibration module that does so (e.g., Biomass_borealDataPrep). However it can be used stand-alone in an initial developmental phase for easier inspection of the statistical calibration procedure employed.
As of April 29, 2024, the raw PSP data used in this module is not freely available, and data sharing agreements must be obtained from the governments of SK, AB, and BC to obtain it. However, the processed and anonymized PSP data is provided via a Google Drive folder accessed automatically by the module.
Google Account is therefore necessary to access the data used for calibration.*
Biomass_speciesParameters is intended to be used with another data module,
like Biomass_borealDataPrep, that prepares all other traits and parameters
(including maxB
and maxANPP
) for Biomass_core. See
here for all
available modules in the LandR ecosystem and select Biomass_speciesParameters
from the drop-down menu to see potential linkages.
-
Biomass_borealDataPrep: prepares all parameters and inputs (including initial landscape conditions) that Biomass_core needs to run a realistic simulation. Default values/inputs produced are relevant for boreal forests of Western Canada. Used upstream from Biomass_speciesParameters;
-
Biomass_core: core forest dynamics simulation module. Used downstream from Biomass_speciesParameters;
-
Biomass_speciesFactorial: a module that generates theoretical species curves by running thousands of Biomass_core simulations on landscapes populated by one or more species, each simulation using a different set of species trait values.
-
Biomass_borealDataPrep: prepares all parameters and inputs (including initial landscape conditions) that Biomass_core needs to run a realistic simulation. Default values/inputs produced are relevant for boreal forests of Western Canada. Used upstream from Biomass_speciesParameters;
-
Biomass_core: core forest dynamics simulation module. Used downstream from Biomass_speciesParameters;
Tree cohort growth and mortality in Biomass_core are essentially determined by
five parameters: growthcurve
, mortalityshape
, maximum biomass (maxB
), maximum
aboveground net primary productivity (maxANPP
) and longevity
.
The growthcurve
and mortalityshape
parameters (called 'growth curve' and
'mortality shape' in LANDIS-II Biomass Succession Extension v3.2, the base model
for Biomass_core) strongly modulate the shape of species growth curves and so
it is important that they are calibrated to the study area in question.
Also, the growth and mortality equations used in Biomass_core are non-linear and their resulting actual biomass accumulation curve is an emergent phenomenon due to competition effects. This means that the ideal trait/parameter values should not be estimated on pure single species growth conditions, as their resulting dynamics will be different in a multi-species context.
Biomass_speciesParameters attempts to address these issues (at least partially)
using a "curve-matching" approach. It compares the best fit (according to their
AIC) of three non-linear forms (Chapman-Richard's, Gompertz, and a logistic form)
fitted to permanent sample plot (PSP) data to a large collection of theoretical
(i.e. simulated) species curves, each representing a different set of the five
key parameters that govern biomass increment in Biomass_core
: growthcurve
,
mortalityshape
, the ratio of maxANPP
to maxB
, and longevity
. This library
of curves is produced by the Biomass_speciesFactorial module.
Biomass_speciesParameters generally follows other LandR data modules, like
Biomass_boreaDataPrep, which also attempts to calibrate previously estimated
spatially varying species traits such as maxB
and maxANPP
from the input data
layers.
Biomass_speciesParameters can use all the PSP data available (note that it may
span several thousands of kilometres), or select the data based on a shapefile
(studyAreaANPP
; see List of input objects).
By default, the PSP data are obtained from the National Forest Inventory (NFI), the Alberta Ministry of Agriculture, the Saskatchewan Ministry of the Environment, the Ontario Ministry of Forests and Natural Resources, and the British Columbia Ministry of Forests. These data were previously treated for errors and standardized into a single dataset with the exact location and identifying attributes anonymized.
The data include individual species, diameter at breast height (DBH), and
sometimes tree height measurements for each tree in a plot, as well as stand
age. As part of the standardization process, dead trees were removed from the
dataset. Tree biomass was then per species using either a DBH-only model or a
DBH-height model from @LambertEtAl2005, in
Note that the model used to calculate biomass can also be changed to @UngEtAl2008
via the P(sim)$biomassModel
module parameter (see list of parameters).
The Biomass_speciesFactorial module was used to create a library of
theoretical species curves (biomass accumulation curves, to be more precise) to
which the best non-linear model form fit to the PSP-biomass will be matched for
each species and species combinations in the study area landscape. The library of curves was
created by running several Biomass_core simulations with no reproduction, competition,
disturbance, or dispersal effects, on the study area. Each simulation differed in
the combination of species trait values that influence growth and mortality
dynamics, namely: growthcurve
, mortalityshape
, longevity
, maxANPP
and
maximum biomass (maxBiomass
, not to be confused with the data-driven maxB
which is later calibrated).
The values for maxANPP
were explored via the mANPPproportion
, the ratio of
maxANPP
to maxBiomass
(the parameter used for theoretical curves), as it
reflects their relationship.
growthcurve
values varied from 0 to 1, in increments of 0.1; mortalityshape
varied from 5 to 25, in increments of 1; longevity
varied from 150 to 700 in
increments of 25; mANPPproportion
varied from 0.25 to 10 in increments of
0.25. maxBiomass
was held constant at 5000.
This resulted in over 64,000,000 theoretical curves.
Results from these simulations were compiled into a table (cohortDataFactorial
; see List of input objects) that is accessed by
Biomass_speciesParameters, so that the module can be run without needing to
re-simulate the theoretical curves.
Biomass_speciesParameters calibrates growthcurve
, mortalityshape
and
mANPPproportion
by matching the theoretical species curves produced by
Biomass_speciesFactorial (cohortDataFactorial
) against observed
species growth curves from the PSP data.
Before calculating the observed species growth curves (i.e., the best of three
non-linear forms to match PSP data), the module subsets the PSP
data to stand ages below the 95th percent quantile for all species (this can be
changed via the P(sim)$quantileAgeSubset
module parameter), as records for
larger age classes were limited and constituted statistical outliers. In some
species, changing the quantile value may improve results, however. Two examples
are Pinus banksiana and Populus sp (in western Canada), for which using the
99th percent quantile improved the models, because these are short-lived species
for which data at advanced ages is scarce.
In addition, weights are added at the origin (age = 0 and biomass = 0) to force the intercept to be essentially at 0 age and 0 biomass.
The best fit of three non-linear forms, for each focal species, is then
calculated. Focal species are defined as either 50% of dominance in the plot, or
20% if we are looking to capture the multi-species dynamics (currently the
default). Three growth model forms are then fit to the observations for the
focal species: a Chapman-Richard's form [Equation @ref(eq:Chapman); see, e.g.,
@CobleLee2006], a Gompertz form (Equation @ref(eq:Gompertz)) and a Logistic
form [Equation @ref(eq:Logistic); see @FekedulegnEtAl1999 for a complete
overview of these equations]. Multiple tries using the estimation methods from
the robustbase::nlrob
function for each form are used, and the best model fit
is selected via Akaike Information Criterion (AIC).
\begin{equation}
B \sim A \times (1 - e^{-k \times age})^{p}
(\#eq:Chapman)
\end{equation}
\begin{equation}
B \sim A \times e^{-k \times e^{-p \times age}}
(\#eq:Gompertz)
\end{equation}
\begin{equation}
B \sim \frac{A}{1 + k \times e^{-p \times age}}
(\#eq:Logistic)
\end{equation}
Species biomass (
It is possible that some selected species do not have enough data to allow for model convergence. In this case, Biomass_speciesParameters skips trait (re-)calibration, and values remain unchanged.
After each species best fit is selected (using AIC), Biomass_speciesParameters
compares it to the library of theoretical curves, and picks the best one based
on maximum likelihood. This best theoretical curve will be associated with a
given combination of growthcurve
, mortalityshape
and maxANPPproportion
values, which are then used directly as the calibrated values, in case of
growthcurve
and mortalityshape
, or to calibrate maxANPP
in the case of
maxANPPproportion
(see below).
Since simulated growth curves never achieve the maximum biomass parameter (the
maxBiomass
parameter set to 5000 for all simulations of theoretical species
curves, or the maxB
parameter in Biomass_core simulations), it acts as an
asymptotic limit that reflects the potential maximum biomass for a species in an
ecolocation (ecological zone and land cover combination).
Biomass_speciesParameters uses the ratio between the potential maximum biomass
(maxBiomass
, always 5000) to the achieved maximum biomass in the theoretical
curves, to rescale maxB
. This ratio is called the inflationFactor
and it is
multiplied by maxB
values previously estimated from data (e.g. by
Biomass_borealDataPrep). This way, species simulated in Biomass_core are
able to achieve the maximum observed biomasses used to initially estimate
maxB
.
Finally, the module calibrates maxANPP
using the mANPPproportion
value from
the best matching theoretical growth curve as:
\begin{equation}
maxB \times \frac{mANPPproportion}{100}
(\#eq:maxANPPcalib)
\end{equation}
where maxB
is the already (re-)calibrated version.
In cases where there are not sufficient PSP data to fit the growth models and
perform the calibration, mANPPproportion
defaults to 3.33 (the value used in LANDIS-II
applications in Canada's boreal forests) and the inflationFactor
defaults to 1.
The full list of input objects required by the module is presented below (Table
@ref(tab:moduleInputs2-Biomass-speciesParameters)). The only input that
must be provided is studyAreaANPP
(the study area used extract the PSP
data from). All other input objects have internal defaults, but the user may
need to request access to their online files.
Of these inputs, the following are particularly important and deserve special attention:
Spatial layers
studyAreaANPP
-- shapefile. ASpatialPolygonsDataFrame
with a single polygon determining the where the PSP should be subset to simulation will take place. This input object must be supplied by the user or another module.
Tables
speciesTableFactorial
andcohortDataFactorial
-- a tables of species trait combinations and the theoretical species grwoth curve data (respectively)PSPmeasure_sppParams
,PSPplot_sppParams
andPSPgis_sppParams
-- tree measurement, biomass growth and geographical data of the PSP datasets used to buildi observed species growth curves.species
-- a table of invariant species traits that may have been produced by another module. It must contain the columns 'species', 'growthcurve' and 'mortality shape', whose values will be calibrated.speciesEcoregion
-- table of spatially-varying species traits that may have been produced by another module. It must contain the columns 'speciesCode', 'maxB' and 'maxANPP' and 'ecoregionGroup' (the ecolocation ID). 'maxB' and 'maxANPP' values will be calibrated by species.
\newpage \blandscape
(\#tab:moduleInputs2-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) input objects and their description.objectName | objectClass | desc | sourceURL |
---|---|---|---|
speciesTableFactorial | data.table | A large species table (sensu Biomass_core) with all columns used by Biomass_core, e.g., longevity, growthcurve, mortalityshape, etc., when it was used to generate `cohortDataFactorial`. See PredictiveEcology/Biomass_factorial for futher information. It will be written to `disk.frame` following sim completion, to preserve RAM. | https://drive.google.com/file/d/1NH7OpAnWtLyO8JVnhwdMJakOyapBnuBH/ |
cohortDataFactorial | data.table | A large `cohortData` table (sensu Biomass_core) with columns age, B, and speciesCode that joins with `speciesTableFactorial`. See PredictiveEcology/Biomass_factorial for further information. It will be written to `disk.frame` following sim completion, to preserve RAM. | https://drive.google.com/file/d/1NH7OpAnWtLyO8JVnhwdMJakOyapBnuBH/ |
PSPmeasure_sppParams | data.table | Merged PSP and TSP individual tree measurements. Must include the following columns: 'MeasureID', 'OrigPlotID1', 'MeasureYear', 'TreeNumber', 'Species', 'DBH' and 'newSpeciesName' the latter corresponding to species names in `LandR::sppEquivalencies_CA$PSP`. Defaults to randomized PSP data stripped of real plotIDs | https://drive.google.com/file/d/1LmOaEtCZ6EBeIlAm6ttfLqBqQnQu4Ca7/view?usp=sharing |
PSPplot_sppParams | data.table | Merged PSP and TSP plot data. Defaults to randomized PSP data stripped of real plotIDs. Must contain columns 'MeasureID', 'MeasureYear', 'OrigPlotID1', and 'baseSA', the latter being stand age at year of first measurement | https://drive.google.com/file/d/1LmOaEtCZ6EBeIlAm6ttfLqBqQnQu4Ca7/view?usp=sharing |
PSPgis_sppParams | sf | Plot location `sf` object. Defaults to PSP data stripped of real plotIDs/location. Must include field 'OrigPlotID1' for joining to PSPplot object | https://drive.google.com/file/d/1LmOaEtCZ6EBeIlAm6ttfLqBqQnQu4Ca7/view?usp=sharing |
species | data.table | A table of invariant species traits with the following trait colums: 'species', 'Area', 'longevity', 'sexualmature', 'shadetolerance', 'firetolerance', 'seeddistance_eff', 'seeddistance_max', 'resproutprob', 'mortalityshape', 'growthcurve', 'resproutage_min', 'resproutage_max', 'postfireregen', 'wooddecayrate', 'leaflongevity' 'leafLignin', and 'hardsoft'. Only 'growthcurve', 'hardsoft', and 'mortalityshape' are used in this module. Default is from Dominic Cyr and Yan Boulanger's applications of LANDIS-II | https://raw.githubusercontent.com/dcyr/LANDIS-II_IA_generalUseFiles/master/speciesTraits.csv |
speciesEcoregion | data.table | Table of spatially-varying species traits ('maxB', 'maxANPP', 'establishprob'), defined by species and 'ecoregionGroup') Defaults to a dummy table based on dummy data os biomass, age, ecoregion and land cover class | NA |
sppEquiv | data.table | Table of species equivalencies. See `?LandR::sppEquivalencies_CA`. | NA |
studyAreaANPP | sf | Optional study area used to crop PSP data before building growth curves. If supplied, an ecoregion-scale object is recommended, at a minimum. | NA |
\elandscape
The full list of parameters used by the module is presented below (Table @ref(tab:moduleParams2-Biomass-speciesParameters)), all of which have default values specified in the module's metadata.
Of these parameters, the following are particularly important:
Calibration parameters
-
biomassModel
-- the model used to calculate biomass from DBH -
speciesFittingApproach
-- should the calibration take into account species growing in single- or multi-species context?
Data processing
-
PSPperiod
-- PSP data period to use. -
quantileAgeSubset
-- upper quantile age value used to subset PSP data.
\newpage \blandscape
(\#tab:moduleParams2-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) parameters and their description.paramName | paramClass | default | min | max | paramDesc |
---|---|---|---|---|---|
biomassModel | character | Lambert2005 | NA | NA | The model used to calculate biomass from DBH. Can be either 'Lambert2005' or 'Ung2008'. |
maxBInFactorial | integer | 5000 | NA | NA | The arbitrary maximum biomass for the factorial simulations. This is a per-species maximum within a pixel |
minimumPlots | numeric | 50 | 10 | NA | Minimum number of PSP plots per species |
minDBH | integer | 0 | 0 | NA | Minimum diameter at breast height (DBH) in cm used to filter PSP data. Defaults to 0 cm, i.e. all tree measurements are used. |
PSPdataTypes | character | all | NA | NA | Which PSP datasets to source, defaulting to all. Other available options include 'BC', 'AB', 'SK', 'ON', 'NB', 'NFI', and 'dummy'. 'dummy' should be used for unauthorized users. |
PSPperiod | numeric | 1920, 2019 | NA | NA | The years by which to subset sample plot data, if desired. Must be a vector of length 2 |
quantileAgeSubset | numeric | 95 | 1 | 100 | Quantile by which to subset PSP data. As older stands are sparsely represented the oldest measurements become vastly more influential. This parameter accepts both a single value and a list of vectors, named according to sppEquivCol. |
speciesFittingApproach | character | focal | NA | NA | Either 'all', 'pairwise', 'focal' or 'single', indicating whether to pool all species into one fit, do pairwise species (for multiple cohort situations), do pairwise species, but using a focal species approach where all other species are pooled into 'other' or do one species at a time. If 'all', all species will have identical species-level traits |
sppEquivCol | character | Boreal | NA | NA | The column in `sim$sppEquiv` data.table that defines individual species. The names should match those in the species table. |
standAgesForFitting | integer | 21, 91 | NA | NA | The minimum and maximum ages of the biomass-by-age curves used in fitting. It is generally recommended to keep this param under 200, given the low data availability of stands aged 200+, with some exceptions. For a closed interval, end with a 1, e.g. c(31, 101). |
useHeight | logical | TRUE | NA | NA | Should height be used to calculate biomass (in addition to DBH). DBH is used by itself when height is missing. |
.plots | character | screen | NA | NA | Used by Plots function, which can be optionally used here |
.plotInitialTime | numeric | 0 | NA | NA | This describes the simulation time at which the first plot event should occur |
.plotInterval | numeric | NA | NA | NA | This describes the simulation time interval between plot events |
.saveInitialTime | numeric | NA | NA | NA | This describes the simulation time at which the first save event should occur |
.saveInterval | numeric | NA | NA | NA | This describes the simulation time interval between save events |
.studyAreaName | character | NA | NA | NA | Human-readable name for the growth curve filename. If `NA`, a hash of sppEquiv[[sppEquivCol]] will be used. |
.useCache | character | .inputOb.... | NA | NA | Should this entire module be run with caching activated? This is generally intended for data-type modules, where stochasticity and time are not relevant |
\elandscape
The module produces the following outputs (Table
@ref(tab:moduleOutputs-Biomass-speciesParameters)). Note that species
and
speciesEcoregion
are modified versions of the input objects with the same
name.
Tables
-
species
andspeciesEcoregion
-- tables with calibrated trait values. -
speciesGAMMs
-- the fitted GAMM model objects for each species.
objectName | objectClass | desc |
---|---|---|
cohortDataFactorial | disk.frame | This object is converted to a `disk.frame` to save memory. Read using `as.data.table()`. |
species | data.table | The updated invariant species traits table (see description for this object in inputs) |
speciesEcoregion | data.table | The updated spatially-varying species traits table (see description for this object in inputs) |
speciesGrowthCurves | list | list containing each species non-linear model, model data, and the unfiltered PSP data |
speciesTableFactorial | disk.frame | This object is converted to a `disk.frame` to save memory. Read using `as.data.table()`. |
Biomass_speciesParameters initializes itself and prepares all inputs provided there is an active internet connection and the user has access to the data (and a Google Account to do so).
We advise future users to run Biomass_speciesParameters with defaults and inspect what the objects are like before supplying their own data. The user does not need to run Biomass_speciesFactorial to generate their own theoretical curves (unless they wish to), as the module accesses pre-generated theoretical curves.
Note that this module only runs once (in one "time step") and only executes one
event (init
). The general flow of Biomass_speciesParameters processes is:
-
Preparation of all necessary data and input objects that do not require parameter fitting (e.g., the theoretical species growth curve data);
-
Sub-setting PSP data and calculating the observed species growth curves using non-linear growth models;
-
Finding the theoretical species growth curve that best matches the observed curve, for each species. Theoretical curves are subset to those with longevity matching the species' longevity (in
species
table) and withgrowthcurve
andmortalityshape
values; -
Calibrating
maxB
andmaxANPP
.
This module can be run stand-alone, but it won't do much more than calibrate species trait values based on dummy input trait values. We provide an example of this below, since it may be of value to run the module by itself to become acquainted with the calibration process and explore the fitted non-linear models. However, we remind that to run this example you will need a Google Account, and to be granted access to the data.
A realistic usage example of this module and a few others can be found in this repository and in @BarrosEtAlinreview.
options(repos = c(CRAN = "https://cloud.r-project.org"))
tempDir <- tempdir()
pkgPath <- file.path(tempDir, "packages", version$platform,
paste0(version$major, ".", strsplit(version$minor, "[.]")[[1]][1]))
dir.create(pkgPath, recursive = TRUE)
.libPaths(pkgPath, include.site = FALSE)
install.packages("remotes")
if (!require(Require, lib.loc = pkgPath)) {
remotes::install_github(
paste0("PredictiveEcology/",
"Require@5c44205bf407f613f53546be652a438ef1248147"),
upgrade = FALSE, force = TRUE)
library(Require, lib.loc = pkgPath)
}
setLinuxBinaryRepo()
Require(paste0("PredictiveEcology/",
"SpaDES.project@6d7de6ee12fc967c7c60de44f1aa3b04e6eeb5db"),
require = FALSE, upgrade = FALSE, standAlone = TRUE)
paths <- list(inputPath = normPath(file.path(tempDir, "inputs")),
cachePath = normPath(file.path(tempDir, "cache")),
modulePath = normPath(file.path(tempDir, "modules")),
outputPath = normPath(file.path(tempDir, "outputs")))
SpaDES.project::getModule(modulePath = paths$modulePath,
c("PredictiveEcology/Biomass_speciesParameters"),
overwrite = TRUE)
## make sure all necessary packages are installed:
outs <- SpaDES.project::packagesInModules(modulePath = paths$modulePath)
Require(c(unname(unlist(outs)), "SpaDES"),
require = FALSE, standAlone = TRUE)
## load necessary packages
Require(c("SpaDES"), upgrade = FALSE, install = FALSE)
times <- list(start = 0, end = 1)
modules <- list("Biomass_speciesParameters")
#the purpose of this table is experiment with modify longevity - longevity is not estimated by the module
#but it is used in trait estimation.
objects <- list()
inputs <- list()
outputs <- list()
parameters <- list()
mySim <- simInitAndSpades(times = times,
params = parameters,
modules = modules,
paths = paths,
objects = objects)
## to inspect the fitted GAMM models:
mySim$speciesGAMMs$Pice_mar