The demography module

The demography module contains functions and classes for modelling the demography of tree communities, including the definition of plant functional types, size structured plant cohorts, community canopy models and the allocation of gross primary productivity into respiration, turnover and growth.

The flora module

The flora module implements:

• The Flora class. This is pydantic data model that provides a set of plant functional types (PFT), defined as a set of functional traits for each PFT. The class defines a specific set of traits used for demographic modelling in pyrealm, mostly the parameterisation of the T Model, but also some additional parameters for modelling crown shape.

  Instances are created by providing a dictionary of lists of trait values - the custom model validation checks that the lists are of equal length. Any missing fields are filled in using the default values, unless the model context specifies ‘strict’ validation when the user must provide all fields.

  The class provides from_csv to generate an instance from trait data stored in a CSV file.

• Two functions to calculate computed traits (q_m and z_max_prop).

Classes:

Flora(*[, name, a_hd, ca_ratio, h_max, ...])

The Flora class.

Functions:

calculate_crown_q_m(m, n)	Calculate the crown scaling trait q_m.
calculate_crown_z_max_proportion(m, n)	Calculate the z_m trait.

class Flora(*, name: list[str] = ['default'], a_hd: list[float] = [116.0], ca_ratio: list[float] = [390.43], h_max: list[float] = [25.33], rho_s: list[float] = [200.0], lai: list[float] = [1.8], sla: list[float] = [14.0], tau_f: list[float] = [4.0], tau_r: list[float] = [1.04], tau_b: list[float] = [inf], par_ext: list[float] = [0.5], yld: list[float] = [0.6], zeta: list[float] = [0.17], resp_r: list[float] = [0.913], resp_s: list[float] = [0.044], resp_f: list[float] = [0.1], m: list[float] = [2], n: list[float] = [5], f_g: list[float] = [0.05])

The Flora class.

This dataclass implements the set of traits required to define a plant functional type for use in pyrealm.

• Most traits are taken from the definition of the T Model of plant growth and GPP allocation (Li et al., 2014).

• The foliage maintenance respiration fraction was not explicitly included in Li et al. (2014) - there was assumed to be a 10% penalty on GPP before calculating the other component - but has been explicitly included here.

• This implementation adds two further crown shape parameters (m and n and f_g). The first two are then used to calculate two constant derived attributes (q_m and z_max_ratio) that define the vertical distribution of the crown. The last parameter (f_g) is the crown gap fraction, that defines the vertical distribution of leaves within the crown. This crown model parameterisation follows the implementation developed in the PlantFATE model (Joshi et al., 2022).

• The branch turnover rate (tau_b) has been added to capture branch fall and loss of other woody tissue forming part of normal tree growth. This defaults to infinity to match the expectations of the original T Model in which woody tissue is never lost to turnover. There is no specific branch mass in the T model, so this is the rate at which total stem biomass turns over through branch loss.

Methods:

from_csv(path[, strict])	Create a Flora object from a CSV file.
model_validation(info)	Implements strict validation.
to_dataframe()	Return the Flora data as a pandas DataFrame.

Attributes:

a_hd	Initial slope of height-diameter relationship (\(a\), -)
ca_ratio	Initial ratio of crown area to stem cross-sectional area (\(c\), -)
f_g	Crown gap fraction (\(f_g\), -)
h_max	Maximum tree height (\(H_m\), m)
lai	Leaf area index within the crown (\(L\), -)
m	Crown shape parameter (\(m\), -)
model_config	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
n	Crown shape parameter (\(n\), -)
name	The name of the plant functional type.
par_ext	Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)
q_m	Scaling factor to derive maximum crown radius from crown area.
resp_f	Foliage maintenance respiration fraction (\(r_f\), -)
resp_r	Fine-root specific respiration rate (\(r_r\), year-1)
resp_s	Sapwood-specific respiration rate (\(r_s\), year-1)
rho_s	Sapwood density (\(\rho_s\), kg Cm-3)
sla	Specific leaf area (\(\sigma\), m2 kg-1 C)
tau_b	Branch turnover time (\(\tau_b\), years)
tau_f	Foliage turnover time (\(\tau_f\),years)
tau_r	Fine-root turnover time (\(\tau_r\), years)
yld	Yield factor (\(y\), -)
z_max_prop	Proportion of stem height at which maximum crown radius is found.
zeta	Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

classmethod from_csv(path: Path, strict: bool = False) → Flora

Create a Flora object from a CSV file.

Parameters:

• path – A path to a CSV file of plant functional type definitions.

• strict – Require that all traits are specified in the input file.

model_validation(info: ValidationInfo) → Self

Implements strict validation.

This validator uses the validation context to toggle a strict validation mode where all of the input fields need to be specified and cannot be filled from default.

to_dataframe() → DataFrame

Return the Flora data as a pandas DataFrame.

This is primarily used to store the flora data within the Cohorts class and allow it to be easily merged onto cohort data, which specifies the PFT name.

a_hd: list[float]

Initial slope of height-diameter relationship (\(a\), -)

ca_ratio: list[float]

Initial ratio of crown area to stem cross-sectional area (\(c\), -)

f_g: list[float]

Crown gap fraction (\(f_g\), -)

h_max: list[float]

Maximum tree height (\(H_m\), m)

lai: list[float]

Leaf area index within the crown (\(L\), -)

m: list[float]

Crown shape parameter (\(m\), -)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n: list[float]

Crown shape parameter (\(n\), -)

name: list[str]

The name of the plant functional type.

par_ext: list[float]

Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)

property q_m: list[float]

Scaling factor to derive maximum crown radius from crown area.

resp_f: list[float]

Foliage maintenance respiration fraction (\(r_f\), -)

resp_r: list[float]

Fine-root specific respiration rate (\(r_r\), year-1)

resp_s: list[float]

Sapwood-specific respiration rate (\(r_s\), year-1)

rho_s: list[float]

Sapwood density (\(\rho_s\), kg Cm-3)

sla: list[float]

Specific leaf area (\(\sigma\), m2 kg-1 C)

tau_b: list[float]

Branch turnover time (\(\tau_b\), years)

tau_f: list[float]

Foliage turnover time (\(\tau_f\),years)

tau_r: list[float]

Fine-root turnover time (\(\tau_r\), years)

yld: list[float]

Yield factor (\(y\), -)

property z_max_prop: list[float]

Proportion of stem height at which maximum crown radius is found.

zeta: list[float]

Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

calculate_crown_q_m(m: NDArray[floating], n: NDArray[floating]) → NDArray[floating]

Calculate the crown scaling trait q_m.

The value of q_m is a constant crown scaling parameter derived from the m and n attributes defined for a plant functional type.

Parameters:

• m – Crown shape parameter

• n – Crown shape parameter

calculate_crown_z_max_proportion(m: NDArray[floating], n: NDArray[floating]) → NDArray[floating]

Calculate the z_m trait.

The z_m proportion (\(p_{zm}\)) is the constant proportion of stem height at which the maximum crown radius is found for a given plant functional type.

\[p_{zm} = \left(\dfrac{n-1}{m n -1}\right)^ {\tfrac{1}{n}}\]

Parameters:

• m – Crown shape parameter

• n – Crown shape parameter

The cohorts module

The cohorts module provides functionality to load and maintain a set of size-structured cohorts. Each cohort is defined as a number of individuals from a plant functional type with a given diameter at breast height. Cohorts are maintained as a simple subclass of {class}`pandas.Dataframe` that adds no new functionality, but just gives the structure a distinct type for use in typing and to indicate that it has an expected fixed set of fields.

Classes:

Cohorts([data, index, columns, dtype, copy])

The Cohorts class.

Functions:

cohort_id_generator([mode, str_fmt])	Generator function for unique cohort IDs.
create_cohorts(flora, cid_generator, ...[, ...])	Create a Cohorts DataFrame.
create_cohorts_from_csv(path, flora, ...)	Generate a Cohort instance from a CSV file.

class Cohorts(data=None, index: Axes | None = None, columns: Axes | None = None, dtype: Dtype | None = None, copy: bool | None = None)

The Cohorts class.

The Cohorts class is simply an alias for a {class}`pandas.DataFrame`.

cohort_id_generator(mode: Literal['uuid', 'int', 'str'] = 'uuid', str_fmt: str = 'C_{id:06}') → Iterator[str | int]

Generator function for unique cohort IDs.

Parameters:

• mode – Use UUID4, sequential integer or formatted sequential integer string cohort IDs.

• str_fmt – A format string for sequential integer string IDs.

create_cohorts(flora: Flora, cid_generator: Iterator, pft_name: NDArray[str_], dbh_value: NDArray[floating], n_individuals: NDArray[integer], community_id: NDArray[integer | str_] | None = None) → Cohorts

Create a Cohorts DataFrame.

This function takes the three variables required for size structured cohort data, along with an optional community ID value, a cohort ID generator instance and a flora.

It validates the inputs and returns a dataframe containing the validated data, using the generator to assign IDs to each cohorts

Parameters:

• flora – A Flora instance.

• cid_generator – A cohort ID generator instance.

• pft_name – An array giving the PFT name for each cohort. The PFT names must all appear in the provided Flora instance.

• dbh_value – An array of diameter at breast height values for cohorts.

• n_individuals – An array giving the number of individuals in each cohort.

• community_id – An optional array providing a community ID, grouping cohorts into communities.

create_cohorts_from_csv(path: Path, flora: Flora, cid_generator: Iterator) → Cohorts

Generate a Cohort instance from a CSV file.

The cohort data provided is validated before being used to generate the Cohorts instance.

Parameters:

• path – Path to a CSV file of cohort data.

• flora – A Flora instance providing the PFT data for the cohorts.

• cid_generator – A generator providing unique cohort ids.

The tmodel module

The t_model module provides the basic scaling relationships of the T Model (Li et al., 2014). This provides scaling relationships using the plant functional type traits defined in the flora module and the diameter at breast height of individual stems to define the stem geometry, masses, respiration and hence calculate stem growth given net primary productivity. Note that stem_height denotes the total tree height, as used interchangeable in (Li et al., 2014), rather than just the height of the trunk below the canopy.

Classes:

GrowthIncrements(cohorts, allometry, ...[, ...])	Calculate growth increments using the T Model.
StemAllocation(cohorts, allometry, ...[, ...])	Calculate GPP allocation for stems.
StemAllometry(cohorts[, at_dbh])	Calculate T Model allometric predictions across a set of stems.

Functions:

calculate_branch_turnover(tau_b, stem_mass)	Calculate stem turnover.
calculate_crown_areas(ca_ratio, a_hd, dbh, ...)	Calculate tree crown area under the T Model.
calculate_crown_fractions(a_hd, stem_height, dbh)	Calculate tree crown fraction under the T Model.
calculate_crown_r0(q_m, crown_area)	Calculate scaling factor for width of maximum crown radius.
calculate_crown_z_max(z_max_prop, stem_height)	Calculate height of maximum crown radius.
calculate_dbh_from_height(h_max, a_hd, ...)	Calculate diameter at breast height from stem height under the T Model.
calculate_fine_root_masses(lai, crown_area, zeta)	Calculate foliage mass under the T Model.
calculate_fine_root_respiration(...)	Calculate fine root respiration.
calculate_fine_root_turnover(tau_r, ...)	Calculate turnover costs.
calculate_foliage_masses(sla, lai, crown_area)	Calculate foliage mass under the T Model.
calculate_foliage_respiration(resp_f, ...)	Calculate foliar respiration.
calculate_foliage_turnover(tau_f, foliage_mass)	Calculate foliage turnover.
calculate_growth_increments(rho_s, a_hd, ...)	Calculate growth increments.
calculate_heights(h_max, a_hd, dbh)	Calculate tree height under the T Model.
calculate_net_primary_productivity(yld, ...)	Calculate net primary productivity.
calculate_sapwood_masses(rho_s, ca_ratio, ...)	Calculate sapwood mass under the T Model.
calculate_sapwood_respiration(resp_s, ...)	Calculate sapwood respiration.
calculate_stem_masses(rho_s, stem_height, dbh)	Calculate stem mass under the T Model.
calculate_whole_crown_gpp(potential_gpp, ...)	Calculate whole crown gross primary productivity.

class GrowthIncrements(cohorts: Cohorts, allometry: StemAllometry, stem_allocation: StemAllocation, biomass_production: NDArray[floating] | None = None)

Calculate growth increments using the T Model.

Experimental

Be aware that GrowthIncrements is an experimental feature and the API and any calculated values may change between major releases.

Stem growth in the T Model is calculated by partitioning biomass production between predicted biomass turnover and carbon available for growth. The T model is then used to estimate an increase in stem diameter that allocates the carbon available for growth across stem, fine roots and foliage according to the allometry of the plant functional types.

This class calculates the stem, fine root and foliage growth increments given:

• a set of cohorts,

• the current stem allometry of those cohorts, and

• calculated allocation of whole crown GPP estimates for the cohorts into respiration, NPP and turnover values.

By default, the calculation will follow the original T Model (Li et al., 2014), in assuming that all of the net primary productivity is available for biomass production. However, the biomass_production argument can be used to use reduce NPP to allocate carbon to other pools such as VOC emissions, soil exudates and non-structural carbohydrates.

Parameters:

• cohorts – A set of cohorts

• allometry – The current stem allometry for those cohorts

• gpp_allocation – An allocation of whole crown GPP for those cohorts.

• biomass_production – An optional array of biomass production values, used to override the NPP estimate in gpp_allocation.

Attributes:

biomass_production	The carbon available for biomass production (g C)
cohort_ids	A numpy array of cohort IDs.
delta_dbh	Predicted increase in stem diameter from growth allocation (m)
delta_fine_root_mass	Predicted increase in fine root mass from growth allocation (g C)
delta_foliage_mass	Predicted increase in foliar mass from growth allocation (g C)
delta_stem_mass	Predicted increase in stem mass from growth allocation (g C)

biomass_production: NDArray[floating]

The carbon available for biomass production (g C)

cohort_ids: NDArray[generic]

A numpy array of cohort IDs.

delta_dbh: NDArray[floating]

Predicted increase in stem diameter from growth allocation (m)

delta_fine_root_mass: NDArray[floating]

Predicted increase in fine root mass from growth allocation (g C)

delta_foliage_mass: NDArray[floating]

Predicted increase in foliar mass from growth allocation (g C)

delta_stem_mass: NDArray[floating]

Predicted increase in stem mass from growth allocation (g C)

class StemAllocation(cohorts: Cohorts, allometry: StemAllometry, whole_crown_gpp: NDArray[floating], profile: bool = False)

Calculate GPP allocation for stems.

Experimental

Be aware that StemAllocation is an experimental feature and the API and any calculated values may change between major releases.

This method calculates the predicted GPP allocations of potential gross primary productivity (GPP) for stems under the T Model (Li et al., 2014), given a set of cohorts and stem allometry predictions for those cohorts.

Allocation from GPP estimates are handled in two ways:

1. In the standard mode, provided GPP estimates are mapped onto the provided allometry following standard array broadcasting. For example, if the allometry provides data for three cohorts, then GPP values could be a scalar array (shape (1,)) or provide and estimate for each cohort (shape (3,). If the allometry estimates used at_dbh to estimate allometry for four DBH sizes, then GPP could again be scalar or per cohort, but could also provide a GPP estimate for each combination of DBH and cohort (shape (4,3)).

2. When profile=True, then StemAllocation will only accept a 1D array of GPP values but will calculate allocation values for all combinations of DBH, cohort and GPP.

Parameters:

• cohorts – An instance of Cohorts.

• allometry – An instance of StemAllometry.

• whole_crown_gpp – An array of GPP values available to a stem at which to model allocation (kg C).

• profile – A boolean switch used to calculate profiles of allocation values for cohorts at different GPP values.

TODO:

Add args to allow inputs from PModel in µgC m2 s-1? Would need to scale to
growth period though.

Attributes:

cohort_ids	A numpy array of cohort IDs.
fine_root_respiration	Allocation to fine root respiration (g C)
fine_root_turnover	Allocation to fine root turnover
foliage_respiration	Allocation to foliar respiration (g C)
foliage_turnover	Allocation to leaf turnover (g C)
npp	Net primary productivity (g C)
sapwood_respiration	Allocation to sapwood respiration (g C)
whole_crown_gpp	An array of gross primary productivity values (kg C) across the whole of the crown of each stem to be allocated to respiration, turnover and growth.

cohort_ids: NDArray[generic]

A numpy array of cohort IDs.

fine_root_respiration: NDArray[floating]

Allocation to fine root respiration (g C)

fine_root_turnover: NDArray[floating]

Allocation to fine root turnover

foliage_respiration: NDArray[floating]

Allocation to foliar respiration (g C)

foliage_turnover: NDArray[floating]

Allocation to leaf turnover (g C)

npp: NDArray[floating]

Net primary productivity (g C)

sapwood_respiration: NDArray[floating]

Allocation to sapwood respiration (g C)

whole_crown_gpp: NDArray[floating]

An array of gross primary productivity values (kg C) across the whole of the crown of each stem to be allocated to respiration, turnover and growth.

class StemAllometry(cohorts: Cohorts, at_dbh: NDArray[floating] | None = None)

Calculate T Model allometric predictions across a set of stems.

Experimental

Be aware that StemAllometry is an experimental feature and the API and any calculated values may change between major releases.

This method calculates predictions of stem allometries for stem height, crown area, crown fraction, stem mass, foliage mass and sapwood mass under the T Model (Li et al., 2014), given diameters at breast height (DBH) for a set of plant cohorts.

The default is to calculate the expected allometry for the DBH values specified in the cohort data and the predictions will be 1D arrays providing the prediction for each cohort.

Alternatively, the class can be used to generate a stem allometry profile for the cohort PFTs at a range of DBH values. The at_dbh argument is used to provide 1D array of DBH values and the class will then generate a prediction for each cohort PFT at each stem diameter. The class prediction attributes are then 2D arrays with shape (n_at_dbh, n_cohorts).

The to_dataframe method can be used to export the predictions as a data frame, flattening 2D predictions if at_dbh is used.

Parameters:

• cohorts – An instance of Cohorts.

• at_dbh – An optional array of DBH values used to provide a profile of allometry predictions.

Attributes:

cohort_ids	An array of the cohort ID for each prediction.
crown_area	Crown area (m2)
crown_fraction	Vertical fraction of the stem covered by the crown (-)
crown_r0	Crown radius scaling factor (-)
crown_z_max	Height of maximum crown radius (m)
dbh	The diameter at breast height (m)
fine_root_mass	Fine root mass (kg)
foliage_mass	Foliage mass (kg)
sapwood_mass	Sapwood mass (kg)
stem_height	Stem height (m)
stem_mass	Stem mass (kg)

cohort_ids: NDArray[generic]

An array of the cohort ID for each prediction.

crown_area: NDArray[floating]

Crown area (m2)

crown_fraction: NDArray[floating]

Vertical fraction of the stem covered by the crown (-)

crown_r0: NDArray[floating]

Crown radius scaling factor (-)

crown_z_max: NDArray[floating]

Height of maximum crown radius (m)

dbh: NDArray[floating]

The diameter at breast height (m)

fine_root_mass: NDArray[floating]

Fine root mass (kg)

foliage_mass: NDArray[floating]

Foliage mass (kg)

sapwood_mass: NDArray[floating]

Sapwood mass (kg)

stem_height: NDArray[floating]

Stem height (m)

stem_mass: NDArray[floating]

Stem mass (kg)

calculate_branch_turnover(tau_b: NDArray[floating], stem_mass: NDArray[floating]) → NDArray[floating]

Calculate stem turnover.

This function calculates the carbon mass of branch turnover, representing branch fall and other woody tissue losses. This is calculated from the total stem mass of individuals (\(W_s\)), and the stem turnover rate (\(\tau_b\)) for the plant functional type.

\[T = W_s * \tau_b\]

NOTE:

Th :math:`\tau_b` term is not present in :cite:t:`{see Equation 15, }Li:2014bc`
and is added in pyrealm. It defaults to infinity to duplicate the calculations
of the original model, which do not include branch turnover.

Parameters:

• tau_b – The branch turnover rate

• stem_mass – The stem mass

calculate_crown_areas(ca_ratio: NDArray[floating], a_hd: NDArray[floating], dbh: NDArray[floating], stem_height: NDArray[floating]) → NDArray[floating]

Calculate tree crown area under the T Model.

The tree crown area (\(A_{c}\)) is calculated from individual diameters at breast height (\(D\)) and stem height (\(H\)), along with the crown area ratio (\(c\)) and the initial slope of the height/diameter relationship (\(a\)) of the plant functional type (Equation 8, Li et al., 2014):

\[A_{c} =\frac{\pi c}{4 a} D H\]

Parameters:

• ca_ratio – Crown area ratio of the PFT

• a_hd – Initial slope of the height/diameter relationship of the PFT

• dbh – Diameter at breast height of individuals

• stem_height – Stem height of individuals

calculate_crown_fractions(a_hd: NDArray[floating], stem_height: NDArray[floating], dbh: NDArray[floating]) → NDArray[floating]

Calculate tree crown fraction under the T Model.

The crown fraction (\(f_{c}\)) is calculated from individual diameters at breast height (\(D\) for \(D > 0\)) and stem height (\(H\)), along with the initial slope of the height / diameter relationship (\(a\)) of the plant functional type (Equation 11, Li et al., 2014):

\[f_{c} =\frac{H}{a D}\]

Parameters:

• a_hd – Initial slope of the height/diameter relationship of the PFT

• stem_height – Stem height of individuals

• dbh – Diameter at breast height of individuals

calculate_crown_r0(q_m: NDArray[floating], crown_area: NDArray[floating]) → NDArray[floating]

Calculate scaling factor for width of maximum crown radius.

This scaling factor (\(r_0\)) is derived from the crown shape parameters (\(m,n,q_m\)) for plant functional types and the estimated crown area (\(A_c\)) of individuals. The shape parameters are defined as part of the extension of the T Model presented by Joshi et al. (2022) and \(r_0\) is used to scale the crown area such that the crown area at the maximum crown radius fits the expectations of the T Model.

\[r_0 = 1/q_m \sqrt{A_c / \pi}\]

Parameters:

• q_m – Crown shape parameter of the PFT

• crown_area – Crown area of individuals

calculate_crown_z_max(z_max_prop: NDArray[floating], stem_height: NDArray[floating]) → NDArray[floating]

Calculate height of maximum crown radius.

The height of the maximum crown radius (\(z_m\)) is derived from the crown shape parameters (\(m,n\)) and the resulting fixed proportion (\(p_{zm}\)) for plant functional types. These shape parameters are defined as part of the extension of the T Model presented by Joshi et al. (2022).

The value \(z_m\) is the height above ground where the largest crown radius is found, given the proportion and the estimated stem height (\(H\)) of individuals.

\[z_m = p_{zm} H\]

Parameters:

• z_max_prop – Crown shape parameter of the PFT

• stem_height – Stem height of individuals

calculate_dbh_from_height(h_max: NDArray[floating], a_hd: NDArray[floating], stem_height: NDArray[floating]) → NDArray[floating]

Calculate diameter at breast height from stem height under the T Model.

This function inverts the normal calculation of stem height (\(H\)) from diameter at breast height (DBH, \(D\)) in the T Model (see calculate_heights()). This is a helper function to allow users to convert known stem heights for a plant functional type, with maximum height (\(H_{m}\)) and initial slope of the height/diameter relationship (\(a\)) into the expected DBH values.

\[D = \frac{H \left( \log \left(\frac{H}{H_{m}-H}\right)\right)}{a}\]

Warning

Where the stem height is greater than the maximum height for a PFT, then DBH is undefined and the return array will contain np.nan. Where the stem height equals the maximum height, the model predicts an infinite stem diameter: the h_max parameter is the asymptotic maximum stem height of an exponential function. Similarly, heights very close to the maximum height may lead to unrealistically large predictions of DBH.

Parameters:

• h_max – Maximum height of the PFT

• a_hd – Initial slope of the height/diameter relationship of the PFT

• stem_height – Stem height of individuals

• validate – Boolean flag to suppress argument validation

calculate_fine_root_masses(lai: NDArray[floating], crown_area: NDArray[floating], zeta: NDArray[floating]) → NDArray[floating]

Calculate foliage mass under the T Model.

The fine root mass (\(W_{r}\)) is calculated from the total area of foliage - the product of the crown area (\(A_{c}\)) and leaf area index (\(L\)) - and the ratio of fine root mass to leaf area (\(zeta\)).

\[W_r = A_c L \zeta\]

Parameters:

• lai – Leaf area index of the PFT

• crown_area – Crown area of individuals

• zeta – The ratio of fine root mass to foliage area of the PFT.

calculate_fine_root_respiration(fine_root_mass: NDArray[floating], resp_r: NDArray[floating]) → NDArray[floating]

Calculate fine root respiration.

Calculates the total fine root respiration (\(R_{r}\)) given fine root mass (\(W_r\)) the fine root respiration rate (\(r_r\)):

\[R_{r} = W_r r_r\]

Equation 13 of (Li et al., 2014) gives this calculation as:

\[R_{r} = \zeta \sigma W_f r_r,\]

given the individual foliage mass (\(W_f\)), the ratio of fine root mass to foliage area (\(\zeta\)) and the specific leaf area (\(\sigma\)), which can be simplified to the equation here given :math: W_f = (A_c L) / sigma: and \(W_r = \zeta A_c L\) (see calculate_fine_root_masses()).

Parameters:

• fine_root_mass – The individual fine root mass.

• resp_r – The respiration rate of fine roots of the PFT.

calculate_fine_root_turnover(tau_r: NDArray[floating], fine_root_mass: NDArray[floating]) → NDArray[floating]

Calculate turnover costs.

This function calculates the costs associated with the turnover of fine roots. This is calculated from the total fine root mass of individuals (\(W_r\)) and the turnover time of fine roots (\(\tau_r\)) of the plant functional type.

\[T = \frac{W_r}{\tau_r}\]

Equation 15 of (Li et al., 2014) gives this as:

T = W_f left(frac{ sigma zeta}{tau_r} right),

given the foliage mass of individuals (\(W_f\)), the specific leaf area (\(\sigma\)) and fine root mass to foliage area ratio (\(\zeta\)), which can be simplified to the equation here given :math: W_f = (A_c L) / sigma: and \(W_r = \zeta A_c L\) (see calculate_fine_root_masses()).

Parameters:

• tau_r – The turnover time of fine roots

• fine_root_mass – The fine root mass

calculate_foliage_masses(sla: NDArray[floating], lai: NDArray[floating], crown_area: NDArray[floating]) → NDArray[floating]

Calculate foliage mass under the T Model.

The foliage mass (\(W_{f}\)) is calculated from the crown area (\(A_{c}\)), along with the specific leaf area (\(\sigma\)) and leaf area index (\(L\)) of the plant functional type (Li et al., 2014).

\[W_f = (1 / \sigma) A_c L\]

Parameters:

• sla – Specific leaf area of the PFT

• lai – Leaf area index of the PFT

• crown_area – Crown area of individuals

calculate_foliage_respiration(resp_f: NDArray[floating], whole_crown_gpp: NDArray[floating]) → NDArray[floating]

Calculate foliar respiration.

Calculates the total foliar respiration (\(R_{f}\)) given the individual crown GPP (\(P\)) and the foliar respiration rate of the plant functional type (\(r_{f}\)). Li et al. (2014) remove foliar respiration as a constant proportion of potential GPP before calculating GPP for the crown, but pyrealm treats this proportion as part of the definition of plant functional types.

\[R_{f} = P \, r_f\]

Parameters:

• resp_f – The foliar respiration rate

• whole_crown_gpp – The individual whole crown GPP.

calculate_foliage_turnover(tau_f: NDArray[floating], foliage_mass: NDArray[floating]) → NDArray[floating]

Calculate foliage turnover.

This function calculates the carbon mass of foliage turnover. This is calculated from the total foliage mass of individuals (\(W_f\)), and the turnover times of foliage (\(\tau_f\)) of the plant functional type (see Equation 15, Li et al., 2014).

\[T = W_f \left( \frac{1}{\tau_f} \right)\]

Parameters:

• tau_f – The turnover time of foliage

• foliage_mass – The foliage mass

calculate_growth_increments(rho_s: NDArray[floating], a_hd: NDArray[floating], h_max: NDArray[floating], lai: NDArray[floating], ca_ratio: NDArray[floating], sla: NDArray[floating], zeta: NDArray[floating], biomass_production: NDArray[floating], turnover: NDArray[floating], dbh: NDArray[floating], stem_height: NDArray[floating]) → tuple[NDArray[floating], NDArray[floating], NDArray[floating], NDArray[floating]]

Calculate growth increments.

This function calculates growth increments for stems. Under the T Model (Li et al., 2014), estimated biomass production (\(B\)) can be partitioned into turnover costs (\(T\)) and carbon available for allocation to biomass increments in:

• the stem diameter (\(\Delta D\)),

• the stem mass (\(\Delta W_s\)),

• the foliar mass (\(\Delta W_f\)), and

• the fine root mass (\(\Delta W_r\)).

The T Model does not include the allocation of NPP to carbon costs outside of growth and turnover, and so uses NPP directly as biomass production. Predicted NPP could be decreased to capture allocation to other processes, such as VOC emissions, non-structural carbohydrates or soil exudates, that are not currently modelled within pyrealm.

The stem diameter increment can be calculated using the available productivity for growth and the rates of change in stem mass (\(\textrm{d}W_s / \textrm{d}t\)) and in the combined foliage and fine root masses (\(\textrm{d}W_fr / \textrm{d}t\)):

\[\Delta D = \frac{B - T}{ \textrm{d}W_s / \textrm{d}t + \textrm{d}W_fr / \textrm{d}t}\]

The rates of change in stem and foliar mass can be calculated as:

\[ \begin{align*} \textrm{d}W_s / \textrm{d}t &= \frac{\pi}{8} \rho_s D \left(a D \left(1 - \frac{H}{H_{m}} + 2 H \right) \right) \\ \textrm{d}W_fr / \textrm{d}t &= L \frac{\pi c}{4 a} \left(a D \left( 1 - \frac{H}{H_{m}} + H \right) \right) \frac{1}{\sigma + \zeta} \end{align*} \]

given the current stem diameter (\(D\)) and height (\(H\)) and the following plant functional type traits:

• the specific leaf area (\(\sigma\)),

• the leaf area index (\(L\)),

• the wood density of the PFT (\(\rho_s\)),

• the maximum height (\(H_{m}\)),

• the initial slope of the height/diameter relationship (\(a\)),

• the crown area ratio (\(c\)), and

• the ratio of fine root mass to leaf area (\(\zeta\)).

The value of \(\Delta D\) is unstable when \(D = 0\) and hence \(H = 0\) and the rates of change in stem and foliar mass are also zero. If \(P_{net} - T = 0\) then \(\Delta D\) is undefined, otherwise \(\Delta D = \pm \inf\) depending on whether then turnover costs exceed the available NPP. Under these conditions, this function explicitly sets \(\Delta D = 0\): stems with zero height cannot grow.

The resulting incremental changes in stem mass and foliage plus fine root masses can then be calculated as:

\[ \begin{align*} \Delta W_s &= \textrm{d}W_s / \textrm{d}t \, \Delta D\\ \Delta W_fr &= \textrm{d}W_fr / \textrm{d}t \, \Delta D \end{align*} \]

Note that (Li et al., 2014) use ‘\(W_f\)’ to denote the increment in both foliage and fine root mass, as fine root mass is estimated as a function of foliage area through the specific leaf area (\(\sigma\)) and ratio of fine root mass to leaf area (\(\zeta\)). Here we use \(W_fr\) to indicate the combined increments and partition the final increments into foliage and fine root components as:

\[ \begin{align*} \Delta W_f &= \Delta W_fr /( 1 + \sigma \zeta) \Delta W_r &= \Delta W_fr - \Delta W_f \end{align*} \]

Parameters:

• rho_s – Wood density of the PFT

• a_hd – Initial slope of the height/diameter relationship of the PFT

• h_max – Maximum height of the PFT

• lai – Leaf area index of the PFT

• ca_ratio – Crown area ratio of the PFT

• sla – Specific leaf area of the PFT

• zeta – The ratio of fine root mass to foliage area of the PFT

• biomass_production – The biomass production of individuals

• turnover – Fine root and foliage turnover cost of individuals

• dbh – Diameter at breast height of individuals

• stem_height – Stem height of individuals

calculate_heights(h_max: NDArray[floating], a_hd: NDArray[floating], dbh: NDArray[floating]) → NDArray[floating]

Calculate tree height under the T Model.

The height of trees (\(H\)) are calculated from individual diameters at breast height (\(D\)), along with the maximum height (\(H_{m}\)) and initial slope of the height/diameter relationship (\(a\)) of the plant functional types (Equation 4, Li et al., 2014):

\[H = H_{m} \left(1 - \exp(-a \cdot D / H_{m})\right)\]

Parameters:

• h_max – Maximum height of the PFT

• a_hd – Initial slope of the height/diameter relationship of the PFT

• dbh – Diameter at breast height of individuals

calculate_net_primary_productivity(yld: NDArray[floating], whole_crown_gpp: NDArray[floating], foliage_respiration: NDArray[floating], fine_root_respiration: NDArray[floating], sapwood_respiration: NDArray[floating]) → NDArray[floating]

Calculate net primary productivity.

The net primary productivity (NPP, \(P_{net}\)) is calculated as a plant functional type specific yield proportion (\(y\)) of the total GPP (\(P\)) for the individual minus respiration (\(R_m\)), as the sum of the respiration costs for foliage (\(R_f\)), fine roots (\(R_r\)) and sapwood (\(R_s\)).

\[P_{net} = y (P - R_m) = y (P - W_{\cdot s} r_s - \zeta \sigma W_f r_r - W_f r_f)\]

Note that this differs from Equation 13 of Li et al. (2014), which does not include a term for foliar respiration. Li et al. (2014) remove foliar respiration as a fixed proportion of potential GPP as the first step in their calculations. The approach here is equivalent but allows the foliar respiration to vary between plant functional types.

Parameters:

• yld – The yield proportion.

• whole_crown_gpp – The total GPP for the crown.

• foliage_respiration – The total foliar respiration.

• fine_root_respiration – The total fine root respiration

• sapwood_respiration – The total sapwood respiration.

calculate_sapwood_masses(rho_s: NDArray[floating], ca_ratio: NDArray[floating], stem_height: NDArray[floating], crown_area: NDArray[floating], crown_fraction: NDArray[floating]) → NDArray[floating]

Calculate sapwood mass under the T Model.

The sapwood mass (\(W_{\cdot s}\)) is calculated from the individual crown area (\(A_{c}\)), stem height (\(H\)) and canopy fraction (\(f_{c}\)) along with the wood density (\(\rho_s\)) and crown area ratio (\(c\)) of the plant functional type, following Equation 14 of (Li et al., 2014). The function is undefined for negative or zero heights.

\[W_{\cdot s} = \frac{A_c \rho_s H (1 - f_c / 2)}{c}\]

Parameters:

• rho_s – Wood density of the PFT

• ca_ratio – Crown area ratio of the PFT

• stem_height – Stem height of individuals

• crown_area – Crown area of individuals

• crown_fraction – Crown fraction of individuals

calculate_sapwood_respiration(resp_s: NDArray[floating], sapwood_mass: NDArray[floating]) → NDArray[floating]

Calculate sapwood respiration.

Calculates the total sapwood respiration (\(R_{\cdot s}\)) given the individual sapwood mass (\(W_{\cdot s}\)) and the sapwood respiration rate of the plant functional type (\(r_{s}\)) (see Equation 13, Li et al., 2014).

\[R_{\cdot s} = W_{\cdot s} \, r_s\]

Parameters:

• resp_s – The sapwood respiration rate

• sapwood_mass – The individual sapwood mass

calculate_stem_masses(rho_s: NDArray[floating], stem_height: NDArray[floating], dbh: NDArray[floating]) → NDArray[floating]

Calculate stem mass under the T Model.

The stem mass (\(W_{s}\)) is calculated from individual diameters at breast height (\(D\)) and stem height (\(H\)), along with the wood density (\(\rho_s\)) of the plant functional type (Equation 6, Li et al., 2014):

\[W_s = (\pi / 8) \rho_s D^2 H\]

Parameters:

• rho_s – Wood density of the PFT

• stem_height – Stem height of individuals

• dbh – Diameter at breast height of individuals

calculate_whole_crown_gpp(potential_gpp: NDArray[floating], crown_area: NDArray[floating], par_ext: NDArray[floating], lai: NDArray[floating]) → NDArray[floating]

Calculate whole crown gross primary productivity.

This function calculates individual gross primary productivity (GPP) across the whole crown, given the individual potential GPP per metre squared (\(P_0\), kg C m-2) and crown area (\(A_c\), m2), along with the leaf area index (\(L\)) and the extinction coefficient (\(k\)) of the plant functional type (Equation 12, Li et al., 2014).

\[P = P_0 A_c (1 - e^{-kL})\]

Parameters:

• lai – The leaf area index

• par_ext – The extinction coefficient

• potential_gpp – Potential GPP per metre squared

• crown_area – The crown area in metres squared

The crown module

A set of functions implementing the crown shape and vertical leaf distribution model used in PlantFATE Joshi et al. (2022).

Classes:

CrownProfile(cohorts, z[, allometry])

Calculate vertical crown profiles for stems.

Functions:

calculate_crown_radius(q_z, r0)	Calculate crown radius from relative crown radius and crown r0.
calculate_relative_crown_radius_at_z(z, ...)	Calculate relative crown radius at a given height.
calculate_stem_projected_crown_area_at_z(z, ...)	Calculate stem projected crown area above a given height.
calculate_stem_projected_leaf_area_at_z(z, ...)	Calculate projected leaf area above a given height.

class CrownProfile(cohorts: Cohorts, z: NDArray[floating], allometry: StemAllometry | None = None)

Calculate vertical crown profiles for stems.

Experimental

Be aware that CrownProfile is an experimental feature and the API and any calculated values may change between major releases.

This method calculates crown profile predictions, given an array of vertical heights (z) for:

• relative crown radius,

• actual crown radius,

• projected crown area, and

• projected leaf area.

The predictions require a set of plant functional types (PFTs) but also the expected allometric predictions of stem height, crown area and z_max for an actual stem of a given size for each PFT.

In addition to the variables above, the class can also has properties the calculate the projected crown radius and projected leaf radius. These are simply the radii that would result in the two projected areas: the values are not directly meaningful for calculating canopy models, but can be useful for exploring the behaviour of projected area on the same linear scale as the crown radius.

Parameters:

• cohorts – A cohorts instance.

• z – An array of vertical height values at which to calculate crown profiles.

• allometry – A StemAllometry instance for the provided cohorts. If this is missing, then it is calculated automatically from the cohorts.

Methods:

to_xy(attr[, stem_offsets, two_sided, as_xy])

Extract plotting data from crown profiles.

Attributes:

crown_radius	A 2D array of the actual crown radius of each stem at given heights
height_is_valid	A 2D logical array showing which heights are below the stem height for each stem.
projected_crown_area	A 2D array of the projected crown area of each stem at given heights
projected_crown_radius	An array of the projected crown radius of stems at z heights.
projected_leaf_area	A 2D array of the projected leaf area of each stem at given heights
projected_leaf_radius	An array of the projected leaf radius of stems at z heights.
relative_crown_radius	A 2D array of the relative crown radius of each stem at given heights
stem_height	A 1D array of the stem heights for each cohort.

to_xy(attr: str, stem_offsets: NDArray[floating] | None = None, two_sided: bool = True, as_xy: bool = False) → list[tuple[NDArray[floating], NDArray[floating]]] | list[NDArray[floating]]

Extract plotting data from crown profiles.

A CrownProfile instance contains crown radius and projected area data for a set of stems at given heights, but can contain predictions of these attributes above the actual heights of some or all of the stems.

This function extracts plotting data for a given attribute for each crown that includes only the predictions within the height range of the actual stem. It can also mirror the values around the vertical midline to provide a two sided canopy shape.

The data are returned as a list with one entry per stem. The default value for each entry a tuple of two arrays (height, attribute values) but the as_xy=True option will return an (N, 2) dimensioned XY array suitable for use with matplotlib.patches.Polygon.

Parameters:

• attr – The crown profile attribute to plot (see CrownProfile)

• stem_offsets – An optional array of offsets to add to the midline of stems.

• two_sided – Should the plotting data show a two sided canopy.

• as_xy – Should the plotting data be returned as a single XY array rather than tuples of X and Y coordinates.

crown_radius: NDArray[floating]

A 2D array of the actual crown radius of each stem at given heights

height_is_valid: NDArray[bool]

A 2D logical array showing which heights are below the stem height for each stem.

projected_crown_area: NDArray[floating]

A 2D array of the projected crown area of each stem at given heights

property projected_crown_radius: NDArray[floating]

An array of the projected crown radius of stems at z heights.

projected_leaf_area: NDArray[floating]

A 2D array of the projected leaf area of each stem at given heights

property projected_leaf_radius: NDArray[floating]

An array of the projected leaf radius of stems at z heights.

relative_crown_radius: NDArray[floating]

A 2D array of the relative crown radius of each stem at given heights

stem_height: NDArray[floating]

A 1D array of the stem heights for each cohort.

calculate_crown_radius(q_z: NDArray[floating], r0: NDArray[floating]) → NDArray[floating]

Calculate crown radius from relative crown radius and crown r0.

The relative crown radius (\(q(z)\)) at a given height \(z\) describes the vertical profile of the crown shape, but only varies with the m and n shape parameters and the stem height. The actual crown radius at a given height (\(r(z)\)) needs to be scaled using \(r_0\) such that the maximum crown area equals the expected crown area given the crown area ratio traiit for the plant functional type:

\[r(z) = r_0 q(z)\]

This function calculates \(r(z)\) given estimated r0 and an array of relative radius values.

Parameters:

• q_z – An array of relative crown radius values

• r0 – An array of crown radius scaling factor values

calculate_relative_crown_radius_at_z(z: NDArray[floating], stem_height: NDArray[floating], m: NDArray[floating], n: NDArray[floating], clip: bool = True) → NDArray[floating]

Calculate relative crown radius at a given height.

The crown shape parameters m and n define the vertical distribution of crown along the stem. For a stem of a given total height, this function calculates the relative crown radius at a given height \(z\):

\[q(z) = m n \left(\dfrac{z}{H}\right) ^ {n -1} \left( 1 - \left(\dfrac{z}{H}\right) ^ n \right)^{m-1}\]

This function calculates \(q(z)\) across a set of stems: the stem_height, m and n arguments should be one-dimensional arrays (‘row vectors’) of equal length \(I\). The value for z is then an array of heights, with one of the following shapes:

1. A scalar array: \(q(z)\) is found for all stems at the same height and the return value is a 1D array of length \(I\).

2. A row vector of length \(I\): \(q(z)\) is found for all stems at stem-specific heights and the return value is again a 1D array of length \(I\).

3. A column vector of length \(J\), that is a 2 dimensional array of shape (\(J\), 1). This allows \(q(z)\) to be calculated efficiently for a set of heights for all stems and return a 2D array of shape (\(J\), \(I\)).

By default, this function clips \(q(z)\): the value is set to zero for values of \(z < 0\) or \(z > H\).

Parameters:

• z – Height at which to calculate relative radius

• stem_height – Total height of individual stems

• m – Canopy shape parameter of PFT for stems

• n – Canopy shape parameter of PFT for stems

• clip – Boolean flag to set \(q(z) = 0\) where the \(z\) is below zero or above the stem height.

calculate_stem_projected_crown_area_at_z(z: NDArray[floating], q_z: NDArray[floating], stem_height: NDArray[floating], crown_area: NDArray[floating], q_m: NDArray[floating], z_max: NDArray[floating]) → NDArray[floating]

Calculate stem projected crown area above a given height.

This function calculates the projected crown area of a set of stems with given properties at a set of vertical heights. The stem properties are given in the arguments stem_height,``crown_area``,``q_m`` and z_max, which must be one-dimensional arrays (‘row vectors’) of equal length. The array of vertical heights z accepts a range of input shapes (see calculate_relative_crown_radius_at_z() ) and this function then also requires the expected relative stem radius (q_z) calculated from those heights.

Parameters:

• z – Vertical height at which to estimate crown area

• q_z – Relative crown radius at those heights

• crown_area – Crown area of each stem

• stem_height – Stem height of each stem

• q_m – Canopy shape parameter q_m` for each stem

• z_max – Height of maximum crown radius for each stem

calculate_stem_projected_leaf_area_at_z(z: NDArray[floating], q_z: NDArray[floating], stem_height: NDArray[floating], crown_area: NDArray[floating], f_g: NDArray[floating], q_m: NDArray[floating], z_max: NDArray[floating]) → NDArray[floating]

Calculate projected leaf area above a given height.

This function calculates the projected leaf area of a set of stems with given properties at a set of vertical heights. This differs from crown area in allowing for crown openness within the crown of an individual stem that results in the displacement of leaf area further down into the crown. The degree of openness is controlled by the crown gap fraction property of each stem.

The stem properties are given in the arguments stem_height,``crown_area``,``f_g``,``q_m`` and z_max, which must be one-dimensional arrays (‘row vectors’) of equal length. The array of vertical heights z accepts a range of input shapes (see calculate_relative_crown_radius_at_z() ) and this function then also requires the expected relative stem radius (q_z) calculated from those heights.

Parameters:

• z – Vertical heights on the z axis.

• q_z – Relative crown radius at heights in z.

• crown_area – Crown area for a stem

• stem_height – Total height of a stem

• f_g – Within crown gap fraction for each stem.

• q_m – Canopy shape parameter q_m` for each stem

• z_max – Height of maximum crown radius for each stem

The canopy module

Functionality for canopy modelling.

Classes:

Canopy(cohorts, allometry, canopy_area[, ...])	Calculate canopy characteristics for a plant community.
CohortCanopyData(projected_leaf_area, ...)	Dataclass holding canopy data across cohorts.
CommunityCanopyData(absorption, ...)	Dataclass holding community-wide canopy data.

Functions:

fit_perfect_plasticity_approximation(...)	Find canopy layer heights under the PPA model.
solve_canopy_area_filling_height(z, ...[, ...])	Solver function for finding the height where a canopy occupies a given area.

class Canopy(cohorts: Cohorts, allometry: StemAllometry, canopy_area: float, layer_heights: NDArray[floating] | None = None, fit_ppa: bool = False, canopy_gap_fraction: float = 0, solver_tolerance: float = 0.001)

Calculate canopy characteristics for a plant community.

Experimental

Be aware that Canopy is an experimental feature and the API and any calculated values may change between major releases.

This class generates a canopy structure for a community of trees using the perfect-plasticity approximation (PPA) model (Purves et al., 2008). In this approach, each individual is assumed to arrange its canopy crown area plastically to take up space in canopy layers and that new layers form below the canopy top as the available space is occupied.

Real canopies contain canopy gaps, through process such as crown shyness. This is included in the model through the canopy gap fraction, which sets the proportion of the available space that will remain unfilled by any canopy.

Parameters:

• community – A Community object that will be used to generate the canopy model.

• layer_heights – A column array of vertical heights at which to calculate canopy variables.

• fit_ppa – Calculate layer heights as the canopy layer closure heights under the PPA model.

• canopy_gap_fraction – The proportion of the available space unfilled by canopy (default: 0.05).

• layer_tolerance – The minimum precision used by the solver to find canopy layer closure heights (default: 0.001 metres)

Attributes:

canopy_gap_fraction	Canopy gap fraction.
cohort_data	The per-cohort canopy data.
community_data	The community-wide canopy data.
crown_profile	The crown profiles of the community stems at the provided layer heights.
filled_community_area	The area filled by crown after accounting for the crown gap fraction.
heights	The vertical heights at which the canopy structure is calculated.
max_stem_height	Maximum height of any individual in the community (m).
n_cohorts	Total number of cohorts in the canopy.
n_layers	Total number of canopy layers.
solver_tolerance	Numerical tolerance for fitting the PPA model of canopy layer closure.

canopy_gap_fraction: float

Canopy gap fraction.

cohort_data: CohortCanopyData

The per-cohort canopy data.

community_data: CommunityCanopyData

The community-wide canopy data.

crown_profile: CrownProfile

The crown profiles of the community stems at the provided layer heights.

filled_community_area: float

The area filled by crown after accounting for the crown gap fraction.

heights: NDArray[floating]

The vertical heights at which the canopy structure is calculated.

max_stem_height: float

Maximum height of any individual in the community (m).

n_cohorts: int

Total number of cohorts in the canopy.

n_layers: int

Total number of canopy layers.

solver_tolerance: float

Numerical tolerance for fitting the PPA model of canopy layer closure.

class CohortCanopyData(projected_leaf_area: dataclasses.InitVar[NDArray[numpy.floating]], n_individuals: dataclasses.InitVar[NDArray[numpy.int64]], lai: dataclasses.InitVar[NDArray[numpy.floating]], par_ext: dataclasses.InitVar[NDArray[numpy.floating]], cell_area: dataclasses.InitVar[float])

Dataclass holding canopy data across cohorts.

Experimental

Be aware that CohortCanopyData is an experimental feature and the API and any calculated values may change between major releases.

The cohort canopy data consists of a set of attributes represented as two dimensional arrays. Each row is different height at which canopy properties are required and the columns represent the different cohorts or the identical stem properties of individuals within cohorts.

The data class:

1. Takes the projected leaf area at the required heights and then partitions this into the actual leaf area within each layer, the leaf area index across the whole cohort and then then light absorption and transmission fractions of each cohort at each level.

2. Calculates the community-wide transmission and absorption profiles. These are generated as an instance of the class CommunityCanopyData and stored in the community_data attribute.

3. Allocates the community-wide absorption across cohorts. The total fraction of light absorbed across layers is a community-wide property - each cohort contributes to the cumulative light absorption. Once the light absorbed within a layer of the community is known, this can then be partitioned back to cohorts and individual stems to give the fraction of canopy top radiation intercepted by each stem within each layer.

Parameters:

• projected_leaf_area – A two dimensional array providing projected leaf area for a set of cohorts (columns) at a set of required heights (rows), as for example calculated using the CrownProfile class.

• n_individuals – A one-dimensional array of the number of individuals in each cohort.

• lai – A one-dimensional array giving the leaf area index trait for the plant functional type of each cohort.

• par_ext – A one-dimensional array giving the light extinction coefficient for the plant functional type of each cohort.

• cell_area – A float setting the total canopy area available to the cohorts.

Attributes:

cell_area	The area available to the community.
cohort_absorption	The Beer-Lambert absorption fraction for each cohort.
community_data	The community wide canopy properties.
fapar	The across layer fractions of absorbed radiation for each cohort by layer.
lai	The leaf area index of the plant functional type for each cohort.
n_individuals	The number of individuals for each cohort.
par_ext	The extinction coefficient of the plant functional type for each cohort.
projected_leaf_area	An array of the stem projected leaf area for each cohort at each of the required heights.
stem_leaf_area	The leaf area of the crown model for each cohort by layer.

cell_area: dataclasses.InitVar[float]

The area available to the community.

cohort_absorption: NDArray[floating]

The Beer-Lambert absorption fraction for each cohort.

community_data: CommunityCanopyData

The community wide canopy properties.

fapar: NDArray[floating]

The across layer fractions of absorbed radiation for each cohort by layer.

lai: dataclasses.InitVar[NDArray[numpy.floating]]

The leaf area index of the plant functional type for each cohort.

n_individuals: dataclasses.InitVar[NDArray[numpy.int64]]

The number of individuals for each cohort.

par_ext: dataclasses.InitVar[NDArray[numpy.floating]]

The extinction coefficient of the plant functional type for each cohort.

projected_leaf_area: dataclasses.InitVar[NDArray[numpy.floating]]

An array of the stem projected leaf area for each cohort at each of the required heights.

stem_leaf_area: NDArray[floating]

The leaf area of the crown model for each cohort by layer.

class CommunityCanopyData(absorption: dataclasses.InitVar[NDArray[numpy.floating]], leaf_area_index: dataclasses.InitVar[NDArray[numpy.floating]], cohort_leaf_area: dataclasses.InitVar[NDArray[numpy.floating]], cell_area: dataclasses.InitVar[float])

Dataclass holding community-wide canopy data.

Experimental

Be aware that CommunityCanopyData is an experimental feature and the API and any calculated values may change between major releases.

The community canopy data consists of a set of attributes represented as one dimensional arrays, with each entry representing a different vertical height at which canopy properties are required.

The data class takes the expected light transmission for each cohort within each layer (as the prediction from the Beer-Lambert law for the cohort), along with the total leaf area in each layer within each cohort, and uses this to calculate the average light transmission profile down through the canopy layers. It also calculates the average leaf area index within each layer.

The cumulative transmission profile shows the fraction of light reaching each of the canopy layers given the average absorption of the layer above, starting with 1 to represent the light reaching the canopy top. The fraction of light reaching the ground below the canopy is stored as the transmission_to_ground attribute.

Parameters:

• absorption – The expected light absorption for cohorts within each layer.

• leaf_area_index – The leaf area index of cohorts within layers.

• cohort_leaf_area – The total leaf area of each cohort in each layer.

• cell_area – The area of the cell containing the community.

Attributes:

absorption	The Beer Lambert light absorption fraction for each cohort.
average_layer_absorption	The average absorption within layers across the community.
average_layer_fapar	The average fAPAR of the community for each layer.
average_layer_lai	The average leaf area index of the community within layers.
cell_area	The total area within the community.
cohort_leaf_area	The total leaf area per cohort for each layer.
leaf_area_index	The leaf area index for each cohort.
transmission_profile	The light transmission profile through the canopy by layer.
transmission_to_ground	The fraction of light reaching the ground below the canopy.

absorption: dataclasses.InitVar[NDArray[numpy.floating]]

The Beer Lambert light absorption fraction for each cohort.

average_layer_absorption: NDArray[floating]

The average absorption within layers across the community.

average_layer_fapar: NDArray[floating]

The average fAPAR of the community for each layer.

average_layer_lai: NDArray[floating]

The average leaf area index of the community within layers.

cell_area: dataclasses.InitVar[float]

The total area within the community.

cohort_leaf_area: dataclasses.InitVar[NDArray[numpy.floating]]

The total leaf area per cohort for each layer.

leaf_area_index: dataclasses.InitVar[NDArray[numpy.floating]]

The leaf area index for each cohort.

transmission_profile: NDArray[floating]

The light transmission profile through the canopy by layer.

transmission_to_ground: NDArray[floating]

The fraction of light reaching the ground below the canopy.

fit_perfect_plasticity_approximation(cohorts: Cohorts, allometry: StemAllometry, area: float, canopy_gap_fraction: float, max_stem_height: float, solver_tolerance: float) → NDArray[floating]

Find canopy layer heights under the PPA model.

Finds the closure heights of the canopy layers under the perfect plasticity approximation by fidnding the set of heights that lead to complete closure of canopy layers through the canopy. The function solves the following equation for integers \(l \in (1,2,..., m)\):

\[\sum_{s=1}^{N_s}{ A_p(z^*_l)} = l A(1 - f_G)\]

The right hand side sets out the total area needed to close a given layer \(l\) and all layers above it: \(l\) times the total community area \(A\) less any canopy gap fraction (\(f_G\)). The left hand side then calculates the projected crown area for each stem \(s\) \(A_p(z^*_l)_{[s]}\) and sums those areas across all stems in the community \(N_s\). The specific height \(z^*_l\) is then the height at which the two terms are equal and hence solves the equation for layer \(l\).

Parameters:

• cohorts – A set of cohorts.

• allometry – The stem allometry for those cohorts.

• area – The area available for canopy to fill.

• canopy_gap_fraction – The canopy gap fraction

• max_stem_height – The maximum stem height in the canopy, used as an upper bound on finding the closure height of the topmost layer.

• solver_tolerance – The absolute tolerance used with the root solver to find the layer heights.

solve_canopy_area_filling_height(z: float, stem_height: NDArray[floating], crown_area: NDArray[floating], m: NDArray[floating], n: NDArray[floating], q_m: NDArray[floating], z_max: NDArray[floating], n_individuals: NDArray[floating], target_area: float = 0) → NDArray[floating]

Solver function for finding the height where a canopy occupies a given area.

This function takes the number of individuals in each cohort along with the stem height and crown area and a given vertical height (\(z\)). It then uses the crown shape parameters associated with each cohort to calculate the community wide projected crown area above that height (\(A_p(z)\)). This is simply the sum of the products of the individual stem crown projected area at \(z\) and the number of individuals in each cohort.

The return value is the difference between the calculated \(A_p(z)\) and a user-specified target area, This allows the function to be used with a root solver to find \(z\) values that result in a given \(A_p(z)\). The default target area is zero, so the default return value will be the actual total \(A_p(z)\) for the community.

A typical use case for the target area would be to specify the area at which a given canopy layer closes under the perfect plasticity approximation in order to find the closure height.

Parameters:

• z – Vertical height on the z axis.

• n_individuals – Number of individuals in each cohort

• crown_area – Crown area of each cohort

• stem_height – Stem height of each cohort

• m – Crown shape parameter m` for each cohort

• n – Crown shape parameter n` for each cohort

• q_m – Crown shape parameter q_m` for each cohort

• z_max – Crown shape parameter z_m` for each cohort

• target_area – A target projected crown area.

The core module

This module provides shared functionality for the demography module.

• ToDataFrameMixin is a class mixin that provides the provides the utility to_dataframe() method for generating a dataframe of attributes from demography classes for plotting and exploring data.

Classes:

ToDataFrameMixin()

Mixin providing a to_dataframe method.

class ToDataFrameMixin

Mixin providing a to_dataframe method.

Classes using this mixin must:

1. Define a class attribute _array_attrs that identifies a set of class attributes that are all numpy arrays of equal shape.

2. Have an _ndims attribute giving the dimensionality of the array attributes.

The mixin provides the to_dataframe method that exports the array attributes as a dataframe.

TODO:

Vague plan here that this could also support polars or simply swap to polars for
increased performance without an API change.

Methods:

to_dataframe()

Convert the instance array attributes into a data frame.

to_dataframe() → DataFrame

Convert the instance array attributes into a data frame.