title: "LandR _BiomassspeciesParameters Manual" subtitle: "v.1.0.0" date: "Last updated: 2022-05-04" output: bookdown::html_document2: toc: true toc_float: true theme: sandstone number_sections: false df_print: paged keep_md: yes editor_options: chunk_output_type: console markdown: wrap: 80 bibliography: citations/references_Biomass_speciesParameters.bib citation-style: citations/ecology-letters.csl link-citations: true always_allow_html: true

LandR Biomass_speciesParameters Module

(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\^\^

Authors:

Ian Eddy ian.eddy@nrcan-rncan.gc.ca [aut, cre], Eliot McIntire eliot.mcintire@nrcan-rncan.gc.ca [aut]

Module Overview

Module summary

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.

Module inputs and parameters at a glance

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)).

(\#tab:moduleInputs-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) input objects and their description.
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

(\#tab:moduleParams-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) parameters and their description.
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

Events

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 (init event): after downloading all the necessary data (during the .inputObjects event), the module prepares the necessary objects and parameters for the simulation and performs the calibration (see [Detailed description]).

See [Simulation flow] for further detail.

Module outputs

The module produces the following outputs (Table \@ref(tab:moduleOutputs-Biomass-speciesParameters)):

(\#tab:moduleOutputs-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) output objects and their description.
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

Links to other modules

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.

Getting help

https://github.com/PredictiveEcology/Biomass_speciesParameters/issues

Module manual

Detailed description

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.

Permanent sample plot data

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.

Simulated species data

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.

Parameter estimation/calibration

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 ($B$) is estimated as a function of stand age ($age$), with the best values of the $A$, $k$ and $p$ parameters to fit the PSP data.

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.

Initialization, inputs and parameters

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)

Input objects

Table \@ref(tab:moduleInputs2-Biomass-speciesParameters) shows the full list of input objects used by the module.

(\#tab:moduleInputs2-Biomass-speciesParameters)List of (ref:Biomass-speciesParameters) input objects and their description.
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://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	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. A SpatialPolygonsDataFrame 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.
Tables
- speciesTableFactorial and cohortDataFactorial -- a tables of species trait combinations and the theoretical species grwoth curve data (respectively)
- PSPmeasure_sppParams, PSPplot_sppParams and PSPgis_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.

Parameters

Table \@ref(tab:moduleParams2-Biomass-speciesParameters) lists all parameters used in Biomass_speciesParameters and their detailed information.

(\#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'
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
- GAMMiterations and GAMMknots -- 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, constrainMortalityShape and constrainMaxANPP -- determine the upper and lower boundaries of the calibrated values of growthcurve, mortalityshape and maxANPP, 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.

Outputs

Tables
- species and speciesEcoregion -- 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])

Simulation flow

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 with growthcurve and mortalityshape values within the chosen boundaries (P(sim)$constrainGrowthCurve, P(sim)$constrainMortalityShape);
Calibrating maxB and maxANPP
Adjusting maxANPP to match the chosen boundaries (P(sim)$constrainMaxANPP)

Usage example

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.

Load `SpaDES` and other packages.

if (!require(Require)) {
  install.packages("Require")
  library(Require)
}

Require(c("PredictiveEcology/SpaDES.install",
          "SpaDES", "PredictiveEcology/SpaDES.core@development"), 
        install_githubArgs = list(dependencies = TRUE))

Get module, necessary packages and set up folder directories

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)

Setup simulation

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

PredictiveEcology / Biomass_speciesParameters

readme

LandR Biomass_speciesParameters Module

Authors:

Module Overview

Module summary

Module inputs and parameters at a glance

Events

Module outputs

Links to other modules

Getting help

Module manual

Detailed description

Permanent sample plot data

Simulated species data

Parameter estimation/calibration

Initialization, inputs and parameters

Input objects

Parameters

Outputs

Simulation flow

Usage example

Load `SpaDES` and other packages.

Get module, necessary packages and set up folder directories

Setup simulation

References

PredictiveEcology / Biomass_speciesParameters

readme

LandR Biomass_speciesParameters Module

Authors:

Module Overview

Module summary

Module inputs and parameters at a glance

Events

Module outputs

Links to other modules

Getting help

Module manual

Detailed description

Permanent sample plot data

Simulated species data

Parameter estimation/calibration

Initialization, inputs and parameters

Input objects

Parameters

Outputs

Simulation flow

Usage example

Load SpaDES and other packages.

Get module, necessary packages and set up folder directories

Setup simulation

References

Load `SpaDES` and other packages.