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 `core` module

This module provides shared functionality for the demography module, implementing two abstract base classes that are used to share core methods across demography classes:

PandasExporter provides the utility to_pandas() method for extracting data from demography classes for plotting and exploring data.
CohortMethods provides the utility add_cohort_data() and drop_cohort_data() methods that are used to append new cohort data across some demography dataclasses.

Classes:

`CohortMethods`()	Abstract base class implementing cohort manipulation functionality.
`PandasExporter`()	Abstract base class implementing pandas export.

class CohortMethods

Abstract base class implementing cohort manipulation functionality.

Classes inheriting from this ABC must define a class attribute array_attrs that names a set of instance attributes that are all numpy arrays of equal length. They must also define the class attribute count_attr that identifies an instance attribute used to records the number of cohorts or stems in the class.

The class then inherit:

The add_cohorts method, which allows a second instance of the same class to be joined to the calling instance, concatenting each of the array attributes from the second instance onto the calling instance and updating n_cohorts.
The drop_cohorts method, which takes a set of indices onto the array attributes and drops the values from those indices for each array attribute and updating n_cohorts.

Methods:

`add_cohort_data`(new_data)	Add array attributes from a second instance implementing the base class.
`drop_cohort_data`(drop_indices)	Drop array attribute values from an instance.

add_cohort_data(new_data: CohortMethods) → None

Add array attributes from a second instance implementing the base class.

Parameters:: new_data – A second instance from which to add cohort data to array attribute values.

drop_cohort_data(drop_indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Drop array attribute values from an instance.

Parameters:: drop_indices – An array of integer indices to drop from each array attribute.

class PandasExporter

Abstract base class implementing pandas export.

Classes inheriting from this ABC must define a class attribute array_attrs that names a set of class attributes that are all numpy arrays of equal length. The classes then inherit the to_pandas method that exports those attributes to a {class}`pandas.DataFrame`.

Methods:

to_pandas()

Convert the instance array attributes into a {class}`pandas.DataFrame.

to_pandas() → DataFrame

Convert the instance array attributes into a {class}`pandas.DataFrame.

If the array values are two-dimensional (i.e. stem or cohort data by vertical heights), the data are stacked and an index is added.

The `flora` module

The flora module implements definitions of:

The PlantFunctionalType and PlantFunctionalTypeStrict dataclasses, which are used to parameterise the traits of different plant functional types. The PlantFunctionalType dataclass is a subclass of PlantFunctionalTypeStrict that simply adds default values to the attributes.
The PlantFunctionalTypeStrict dataclass is used as the basis of a marshmallow schema for validating the creation of plant functional types from data files. This intentionally enforces a complete description of the traits in the input data. The PlantFunctionalType is provided as a more convenient API for programmatic use.
The Flora dataclass, which represents a collection of plant functional types for use in describing a plant community in a simulation. It provides the same trait attributes as the plant functional type classes, but the values are arrays of trait values across the provided PFTS. The Flora class also defines factory methods to create instances from plant functional type data stored in JSON, TOML or CSV formats.
The StemTraits dataclass, which represents a collection of stems used in a simulation. It again provides the same trait attributes as the plant functional type classes, but as arrays. This differs from the Flora class in allowing multiple stems of the same plant functional type and is primarily used to broadcast PFT traits into arrays for use in calculating demography across the stems in plant cohorts.

Classes:

`Flora`(pfts)	A dataclass providing trait data on collection of plant functional types.
`PlantFunctionalType`(name[, a_hd, ca_ratio, ...])	The PlantFunctionalType dataclass.
`PlantFunctionalTypeStrict`(name, a_hd, ...)	The PlantFunctionalTypeStrict dataclass.
`StemTraits`(name, a_hd, ca_ratio, h_max, ...)	A dataclass for stem traits.

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(pfts: dataclasses.InitVar[collections.abc.Sequence[pyrealm.demography.flora.PlantFunctionalTypeStrict]])

A dataclass providing trait data on collection of plant functional types.

A flora provides trait data on the complete collection of plant functional types that will be used within a particular simulation. The dataclass provides access to trait attributes as row arrays across those plant functional types.

The class is created using a list of PlantFunctionalType or PlantFunctionalTypeStrict instances, which must have unique names.

Parameters:: pfts – A sequence of PlantFunctionalType or PlantFunctionalTypeStrict instances, which must not have duplicated name attributes.

Methods:

`from_csv`(path)	Create a Flora object from a CSV file.
`from_json`(path)	Create a Flora object from a JSON file.
`from_toml`(path)	Create a Flora object from a TOML file.
`get_stem_traits`(pft_names)	Generates a stem traits object for a set of names.

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\), -)
`gpp_topslice`	Proportion of GPP to topslice before allocation.
`h_max`	Maximum tree height (\(H_m\), m)
`lai`	Leaf area index within the crown (\(L\), -)
`m`	Crown shape parameter (\(m\), -)
`n`	Crown shape parameter (\(n\), -)
`n_pfts`	The number of plant functional types in the Flora instance.
`name`	The name of the plant functional type.
`p_foliage_for_reproductive_tissue`	Proportion of foliage used to calculate reproductive tissue.
`par_ext`	Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)
`pft_dict`	A dictionary of the original plant functional type instances, keyed by name.
`pft_indices`	An dictionary giving the index of each PFT name in the trait array attributes.
`pfts`	A sequence of plant functional type instances to include in the Flora.
`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_rt`	Reproductive tissue respiration rate (\(r_{rt}\), -)
`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_f`	Foliage turnover time (\(\tau_f\),years)
`tau_r`	Fine-root turnover time (\(\tau_r\), years)
`tau_rt`	Reproductive tissue turnover time (\(\tau_rt\),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) → Flora

Create a Flora object from a CSV file.

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

classmethod from_json(path: Path) → Flora

Create a Flora object from a JSON file.

Parameters:: path – A path to a JSON file of plant functional type definitions.

classmethod from_toml(path: Path) → Flora

Create a Flora object from a TOML file.

Parameters:: path – A path to a TOML file of plant functional type definitions.

get_stem_traits(pft_names: ndarray[tuple[Any, ...], dtype[str_]]) → StemTraits

Generates a stem traits object for a set of names.

Parameters:: pft_names – An array of PFT names for each stem.

a_hd: ndarray[tuple[Any, ...], dtype[floating]]: Initial slope of height-diameter relationship (\(a\), -)

ca_ratio: ndarray[tuple[Any, ...], dtype[floating]]: Initial ratio of crown area to stem cross-sectional area (\(c\), -)

f_g: ndarray[tuple[Any, ...], dtype[floating]]: Crown gap fraction (\(f_g\), -)

gpp_topslice: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of GPP to topslice before allocation.

h_max: ndarray[tuple[Any, ...], dtype[floating]]: Maximum tree height (\(H_m\), m)

lai: ndarray[tuple[Any, ...], dtype[floating]]: Leaf area index within the crown (\(L\), -)

m: ndarray[tuple[Any, ...], dtype[floating]]: Crown shape parameter (\(m\), -)

n: ndarray[tuple[Any, ...], dtype[floating]]: Crown shape parameter (\(n\), -)

n_pfts: int: The number of plant functional types in the Flora instance.

name: ndarray[tuple[Any, ...], dtype[str_]]: The name of the plant functional type.

p_foliage_for_reproductive_tissue: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of foliage used to calculate reproductive tissue.

par_ext: ndarray[tuple[Any, ...], dtype[floating]]: Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)

pft_dict: dict[str, PlantFunctionalTypeStrict]: A dictionary of the original plant functional type instances, keyed by name.

pft_indices: dict[str, int]: An dictionary giving the index of each PFT name in the trait array attributes.

pfts: dataclasses.InitVar[collections.abc.Sequence[pyrealm.demography.flora.PlantFunctionalTypeStrict]]: A sequence of plant functional type instances to include in the Flora.

q_m: ndarray[tuple[Any, ...], dtype[floating]]: Scaling factor to derive maximum crown radius from crown area.

resp_f: ndarray[tuple[Any, ...], dtype[floating]]: Foliage maintenance respiration fraction (\(r_f\), -)

resp_r: ndarray[tuple[Any, ...], dtype[floating]]: Fine-root specific respiration rate (\(r_r\), year-1)

resp_rt: ndarray[tuple[Any, ...], dtype[floating]]: Reproductive tissue respiration rate (\(r_{rt}\), -)

resp_s: ndarray[tuple[Any, ...], dtype[floating]]: Sapwood-specific respiration rate (\(r_s\), year-1)

rho_s: ndarray[tuple[Any, ...], dtype[floating]]: Sapwood density (\(\rho_s\), kg Cm-3)

sla: ndarray[tuple[Any, ...], dtype[floating]]: Specific leaf area (\(\sigma\), m2 kg-1 C)

tau_f: ndarray[tuple[Any, ...], dtype[floating]]: Foliage turnover time (\(\tau_f\),years)

tau_r: ndarray[tuple[Any, ...], dtype[floating]]: Fine-root turnover time (\(\tau_r\), years)

tau_rt: ndarray[tuple[Any, ...], dtype[floating]]: Reproductive tissue turnover time (\(\tau_rt\),years)

yld: ndarray[tuple[Any, ...], dtype[floating]]: Yield factor (\(y\), -)

z_max_prop: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of stem height at which maximum crown radius is found.

zeta: ndarray[tuple[Any, ...], dtype[floating]]: Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

class PlantFunctionalType(name: str, a_hd: float = 116.0, ca_ratio: float = 390.43, h_max: float = 25.33, rho_s: float = 200.0, lai: float = 1.8, sla: float = 14.0, tau_f: float = 4.0, tau_rt: float = 1.0, tau_r: float = 1.04, par_ext: float = 0.5, yld: float = 0.6, zeta: float = 0.17, resp_r: float = 0.913, resp_rt: float = 0.0, resp_s: float = 0.044, resp_f: float = 0.1, m: float = 2, n: float = 5, f_g: float = 0.05, p_foliage_for_reproductive_tissue: float = 0.0, gpp_topslice: float = 0.0)

The PlantFunctionalType dataclass.

This dataclass is a subclass of PlantFunctionalTypeStrict that implements exactly the same set of traits but provides default values. This class is intended as a convenience API for programmatic use, where the parent provides a strict schema for generating plant functional type instances from data.

The table below lists the attributes and default values taken from Table 1 of Li et al. (2014), except for m, n and f_g which take representative values from Joshi et al. (2022).

Attribute	Default	Unit
a_hd	116.0
ca_ratio	390.43
h_max	25.33	m
rho_s	200.0	kg Cm-3
lai	1.8
sla	14.0	m2 kg-1 C
tau_f	4.0	years
tau_r	1.04	years
par_ext	0.5
yld	0.6
zeta	0.17	kg C m-2
resp_r	0.913	year-1
resp_s	0.044	year-1
resp_f	0.1
m	2
n	5
f_g	0.05

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\), -)
`gpp_topslice`	Proportion of GPP to topslice before allocation.
`h_max`	Maximum tree height (\(H_m\), m)
`lai`	Leaf area index within the crown (\(L\), -)
`m`	Crown shape parameter (\(m\), -)
`n`	Crown shape parameter (\(n\), -)
`name`	The name of the plant functional type.
`p_foliage_for_reproductive_tissue`	Mass of reproductive tissue as a proportion of foliage mass (\(p_{rt}\), -).
`par_ext`	Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)
`resp_f`	Foliage maintenance respiration fraction (\(r_f\), -)
`resp_r`	Fine-root specific respiration rate (\(r_r\), year-1)
`resp_rt`	Reproductive tissue respiration rate (\(r_{rt}\), 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_f`	Foliage turnover time (\(\tau_f\),years)
`tau_r`	Fine-root turnover time (\(\tau_r\), years)
`tau_rt`	Reproductive tissue turnover time (\(\tau_rt\),years)
`yld`	Yield factor (\(y\), -)
`zeta`	Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

a_hd: float = 116.0: Initial slope of height-diameter relationship (\(a\), -)

ca_ratio: float = 390.43: Initial ratio of crown area to stem cross-sectional area (\(c\), -)

f_g: float = 0.05: Crown gap fraction (\(f_g\), -)

gpp_topslice: float = 0.0: Proportion of GPP to topslice before allocation.

h_max: float = 25.33: Maximum tree height (\(H_m\), m)

lai: float = 1.8: Leaf area index within the crown (\(L\), -)

m: float = 2: Crown shape parameter (\(m\), -)

n: float = 5: Crown shape parameter (\(n\), -)

name: str: The name of the plant functional type.

p_foliage_for_reproductive_tissue: float = 0.0: Mass of reproductive tissue as a proportion of foliage mass (\(p_{rt}\), -).

par_ext: float = 0.5: Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)

q_m: float: Scaling factor to derive maximum crown radius from crown area.

resp_f: float = 0.1: Foliage maintenance respiration fraction (\(r_f\), -)

resp_r: float = 0.913: Fine-root specific respiration rate (\(r_r\), year-1)

resp_rt: float = 0.0: Reproductive tissue respiration rate (\(r_{rt}\), year-1)

resp_s: float = 0.044: Sapwood-specific respiration rate (\(r_s\), year-1)

rho_s: float = 200.0: Sapwood density (\(\rho_s\), kg Cm-3)

sla: float = 14.0: Specific leaf area (\(\sigma\), m2 kg-1 C)

tau_f: float = 4.0: Foliage turnover time (\(\tau_f\),years)

tau_r: float = 1.04: Fine-root turnover time (\(\tau_r\), years)

tau_rt: float = 1.0: Reproductive tissue turnover time (\(\tau_rt\),years)

yld: float = 0.6: Yield factor (\(y\), -)

z_max_prop: float: Proportion of stem height at which maximum crown radius is found.

zeta: float = 0.17: Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

PlantFunctionalTypeSchema

Marshmallow validation schema class for validating PlantFunctionalType data.

This schema explicitly uses the strict version of the dataclass, which enforces complete descriptions of plant functional type data rather than allowing partial data and filling in gaps from the default values.

class PlantFunctionalTypeStrict(name: str, a_hd: float, ca_ratio: float, h_max: float, rho_s: float, lai: float, sla: float, tau_f: float, tau_rt: float, tau_r: float, par_ext: float, yld: float, zeta: float, resp_r: float, resp_rt: float, resp_s: float, resp_f: float, m: float, n: float, f_g: float, p_foliage_for_reproductive_tissue: float, gpp_topslice: float)

The PlantFunctionalTypeStrict dataclass.

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

See also PlantFunctionalType for the default values implemented in that subclass.

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\), -)
`gpp_topslice`	Proportion of GPP to topslice before allocation.
`h_max`	Maximum tree height (\(H_m\), m)
`lai`	Leaf area index within the crown (\(L\), -)
`m`	Crown shape parameter (\(m\), -)
`n`	Crown shape parameter (\(n\), -)
`name`	The name of the plant functional type.
`p_foliage_for_reproductive_tissue`	Mass of reproductive tissue as a proportion of foliage mass (\(p_{rt}\), -).
`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_rt`	Reproductive tissue respiration rate (\(r_{rt}\), 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_f`	Foliage turnover time (\(\tau_f\),years)
`tau_r`	Fine-root turnover time (\(\tau_r\), years)
`tau_rt`	Reproductive tissue turnover time (\(\tau_rt\),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)

a_hd: float: Initial slope of height-diameter relationship (\(a\), -)

ca_ratio: float: Initial ratio of crown area to stem cross-sectional area (\(c\), -)

f_g: float: Crown gap fraction (\(f_g\), -)

gpp_topslice: float: Proportion of GPP to topslice before allocation.

h_max: float: Maximum tree height (\(H_m\), m)

lai: float: Leaf area index within the crown (\(L\), -)

m: float: Crown shape parameter (\(m\), -)

n: float: Crown shape parameter (\(n\), -)

name: str: The name of the plant functional type.

p_foliage_for_reproductive_tissue: float: Mass of reproductive tissue as a proportion of foliage mass (\(p_{rt}\), -).

par_ext: float: Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)

q_m: float: Scaling factor to derive maximum crown radius from crown area.

resp_f: float: Foliage maintenance respiration fraction (\(r_f\), -)

resp_r: float: Fine-root specific respiration rate (\(r_r\), year-1)

resp_rt: float: Reproductive tissue respiration rate (\(r_{rt}\), year-1)

resp_s: float: Sapwood-specific respiration rate (\(r_s\), year-1)

rho_s: float: Sapwood density (\(\rho_s\), kg Cm-3)

sla: float: Specific leaf area (\(\sigma\), m2 kg-1 C)

tau_f: float: Foliage turnover time (\(\tau_f\),years)

tau_r: float: Fine-root turnover time (\(\tau_r\), years)

tau_rt: float: Reproductive tissue turnover time (\(\tau_rt\),years)

yld: float: Yield factor (\(y\), -)

z_max_prop: float: Proportion of stem height at which maximum crown radius is found.

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

A dataclass for stem traits.

This dataclass is used to provide arrays of plant functional type (PFT) traits across a set of stems. The main use case is to provide stem trait data as arrays across the cohorts within a community object.

It provides the same attribute interface as the Flora class, but unlike that class:

is purely a data container, and
plant functional types can be represented multiple times to represent multiple stems or cohorts of the same PFT.

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\), -)
`gpp_topslice`	Proportion of GPP to topslice before allocation.
`h_max`	Maximum tree height (\(H_m\), m)
`lai`	Leaf area index within the crown (\(L\), -)
`m`	Crown shape parameter (\(m\), -)
`n`	Crown shape parameter (\(n\), -)
`name`	The name of the plant functional type.
`p_foliage_for_reproductive_tissue`	Proportion of foliage used to calculate reproductive tissue.
`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_rt`	Reproductive tissue respiration rate (\(r_{rt}\), -)
`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_f`	Foliage turnover time (\(\tau_f\),years)
`tau_r`	Fine-root turnover time (\(\tau_r\), years)
`tau_rt`	Reproductive tissue turnover time (\(\tau_rt\),years)
`validate`	Boolean flag to control validation of the input array sizes.
`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)

a_hd: ndarray[tuple[Any, ...], dtype[floating]]: Initial slope of height-diameter relationship (\(a\), -)

ca_ratio: ndarray[tuple[Any, ...], dtype[floating]]: Initial ratio of crown area to stem cross-sectional area (\(c\), -)

f_g: ndarray[tuple[Any, ...], dtype[floating]]: Crown gap fraction (\(f_g\), -)

gpp_topslice: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of GPP to topslice before allocation.

h_max: ndarray[tuple[Any, ...], dtype[floating]]: Maximum tree height (\(H_m\), m)

lai: ndarray[tuple[Any, ...], dtype[floating]]: Leaf area index within the crown (\(L\), -)

m: ndarray[tuple[Any, ...], dtype[floating]]: Crown shape parameter (\(m\), -)

n: ndarray[tuple[Any, ...], dtype[floating]]: Crown shape parameter (\(n\), -)

name: ndarray[tuple[Any, ...], dtype[str_]]: The name of the plant functional type.

p_foliage_for_reproductive_tissue: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of foliage used to calculate reproductive tissue.

par_ext: ndarray[tuple[Any, ...], dtype[floating]]: Extinction coefficient of photosynthetically active radiation (PAR) (\(k\), -)

q_m: ndarray[tuple[Any, ...], dtype[floating]]: Scaling factor to derive maximum crown radius from crown area.

resp_f: ndarray[tuple[Any, ...], dtype[floating]]: Foliage maintenance respiration fraction (\(r_f\), -)

resp_r: ndarray[tuple[Any, ...], dtype[floating]]: Fine-root specific respiration rate (\(r_r\), year-1)

resp_rt: ndarray[tuple[Any, ...], dtype[floating]]: Reproductive tissue respiration rate (\(r_{rt}\), -)

resp_s: ndarray[tuple[Any, ...], dtype[floating]]: Sapwood-specific respiration rate (\(r_s\), year-1)

rho_s: ndarray[tuple[Any, ...], dtype[floating]]: Sapwood density (\(\rho_s\), kg Cm-3)

sla: ndarray[tuple[Any, ...], dtype[floating]]: Specific leaf area (\(\sigma\), m2 kg-1 C)

tau_f: ndarray[tuple[Any, ...], dtype[floating]]: Foliage turnover time (\(\tau_f\),years)

tau_r: ndarray[tuple[Any, ...], dtype[floating]]: Fine-root turnover time (\(\tau_r\), years)

tau_rt: ndarray[tuple[Any, ...], dtype[floating]]: Reproductive tissue turnover time (\(\tau_rt\),years)

validate: bool = True: Boolean flag to control validation of the input array sizes.

yld: ndarray[tuple[Any, ...], dtype[floating]]: Yield factor (\(y\), -)

z_max_prop: ndarray[tuple[Any, ...], dtype[floating]]: Proportion of stem height at which maximum crown radius is found.

zeta: ndarray[tuple[Any, ...], dtype[floating]]: Ratio of fine-root mass to foliage area (\(\zeta\), kg C m-2)

calculate_crown_q_m(m: float | ndarray[tuple[Any, ...], dtype[floating]], n: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[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: float | ndarray[tuple[Any, ...], dtype[floating]], n: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[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 `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:

`StemAllocation`(stem_traits, stem_allometry, ...)	Calculate T Model GPP allocation across a set of stems.
`StemAllometry`(stem_traits, at_dbh[, validate])	Calculate T Model allometric predictions across a set of stems.

Functions:

`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[, validate])	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`(...[, validate])	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_turnover`(tau_f, foliage_mass)	Calculate turnover costs for foliage.
`calculate_foliar_respiration`(resp_f, ...[, ...])	Calculate foliar respiration.
`calculate_gpp_topslice`(gpp_topslice, ...[, ...])	Calculate gpp topslice.
`calculate_growth_increments`(rho_s, a_hd, ...)	Calculate growth increments.
`calculate_heights`(h_max, a_hd, dbh[, validate])	Calculate tree height under the T Model.
`calculate_net_primary_productivity`(yld, ...)	Calculate net primary productivity.
`calculate_reproductive_tissue_mass`(...)	Calculate reproductive tissue mass.
`calculate_reproductive_tissue_respiration`(...)	Calculate reproductive tissue respiration.
`calculate_reproductive_tissue_turnover`(...)	Calculate reproductive tissue turnover costs.
`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 StemAllocation(stem_traits: dataclasses.InitVar[pyrealm.demography.flora.Flora | pyrealm.demography.flora.StemTraits], stem_allometry: dataclasses.InitVar[StemAllometry], whole_crown_gpp: ndarray[tuple[Any, ...], dtype[floating]], validate: dataclasses.InitVar[bool] = True)

Calculate T Model GPP allocation across a set of 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 allocation of potential gross primary productivity (GPP) for stems under the T Model (Li et al., 2014), given a set of traits for those stems and the stem allometries given the stem size.

Parameters:

stem_traits – An instance of Flora or StemTraits, providing plant functional trait data for a set of stems.
stem_allometry – An instance of StemAllometry providing the stem size data for which to calculate allocation.
whole_crown_gpp – An array of GPP values available to a stem at which to model allocation (kg C).
validate – Boolean flag to suppress argument validation

Attributes:

`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)
`fine_root_respiration`	Allocation to fine root respiration (g C)
`fine_root_turnover`	Allocation to fine root turnover
`foliar_respiration`	Allocation to foliar respiration (g C)
`gpp_topslice`	GPP removed before allocation for various biological functions (g C)
`leaf_turnover`	Allocation to leaf turnover (g C)
`npp`	Net primary productivity (g C)
`reproductive_tissue_respiration`	Allocation to reproductive tissue respiration (g C)
`reproductive_tissue_turnover`	Allocation to reproductive tissue turnover (g C)
`sapwood_respiration`	Allocation to sapwood respiration (g C)
`stem_allometry`	An instance of `StemAllometry` providing the stem size data for which to calculate allocation.
`stem_traits`	An instance of `Flora` or `StemTraits`, providing plant functional trait data for a set of stems.
`topslice_whole_crown_gpp`	The available stem GPP after any topslicing (g C)
`validate`	Boolean flag to suppress argument validation.
`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.

delta_dbh: ndarray[tuple[Any, ...], dtype[floating]]: Predicted increase in stem diameter from growth allocation (m)

delta_fine_root_mass: ndarray[tuple[Any, ...], dtype[floating]]: Predicted increase in fine root mass from growth allocation (g C)

delta_foliage_mass: ndarray[tuple[Any, ...], dtype[floating]]: Predicted increase in foliar mass from growth allocation (g C)

delta_stem_mass: ndarray[tuple[Any, ...], dtype[floating]]: Predicted increase in stem mass from growth allocation (g C)

fine_root_respiration: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to fine root respiration (g C)

fine_root_turnover: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to fine root turnover

foliar_respiration: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to foliar respiration (g C)

gpp_topslice: ndarray[tuple[Any, ...], dtype[floating]]: GPP removed before allocation for various biological functions (g C)

leaf_turnover: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to leaf turnover (g C)

npp: ndarray[tuple[Any, ...], dtype[floating]]: Net primary productivity (g C)

reproductive_tissue_respiration: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to reproductive tissue respiration (g C)

reproductive_tissue_turnover: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to reproductive tissue turnover (g C)

sapwood_respiration: ndarray[tuple[Any, ...], dtype[floating]]: Allocation to sapwood respiration (g C)

stem_allometry: dataclasses.InitVar[StemAllometry]: An instance of StemAllometry providing the stem size data for which to calculate allocation.

stem_traits: dataclasses.InitVar[pyrealm.demography.flora.Flora | pyrealm.demography.flora.StemTraits]: An instance of Flora or StemTraits, providing plant functional trait data for a set of stems.

topslice_whole_crown_gpp: ndarray[tuple[Any, ...], dtype[floating]]: The available stem GPP after any topslicing (g C)

validate: dataclasses.InitVar[bool] = True: Boolean flag to suppress argument validation.

whole_crown_gpp: ndarray[tuple[Any, ...], dtype[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(stem_traits: dataclasses.InitVar[pyrealm.demography.flora.Flora | pyrealm.demography.flora.StemTraits], at_dbh: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]], validate: dataclasses.InitVar[bool] = True)

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 for a set of plant functional traits.

Parameters:

stem_traits – An instance of Flora or StemTraits, providing plant functional trait data for a set of stems.
at_dbh – An array of diameter at breast height values at which to predict stem allometry values.
validate – Boolean flag to suppress argument validation

Attributes:

`at_dbh`	An array of diameter at breast height values at which to predict stem allometry values.
`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`	Diameter at breast height (m)
`fine_root_mass`	Fine root mass (kg)
`foliage_mass`	Foliage mass (kg)
`reproductive_tissue_mass`	Reproductive tissue mass (kg)
`sapwood_mass`	Sapwood mass (kg)
`stem_height`	Stem height (m)
`stem_mass`	Stem mass (kg)
`stem_traits`	An instance of `Flora` or `StemTraits`, providing plant functional trait data for a set of stems.
`validate`	Boolean flag to suppress argument validation.

at_dbh: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: An array of diameter at breast height values at which to predict stem allometry values.

crown_area: ndarray[tuple[Any, ...], dtype[floating]]: Crown area (m2)

crown_fraction: ndarray[tuple[Any, ...], dtype[floating]]: Vertical fraction of the stem covered by the crown (-)

crown_r0: ndarray[tuple[Any, ...], dtype[floating]]: Crown radius scaling factor (-)

crown_z_max: ndarray[tuple[Any, ...], dtype[floating]]: Height of maximum crown radius (m)

dbh: ndarray[tuple[Any, ...], dtype[floating]]: Diameter at breast height (m)

fine_root_mass: ndarray[tuple[Any, ...], dtype[floating]]: Fine root mass (kg)

foliage_mass: ndarray[tuple[Any, ...], dtype[floating]]: Foliage mass (kg)

reproductive_tissue_mass: ndarray[tuple[Any, ...], dtype[floating]]: Reproductive tissue mass (kg)

sapwood_mass: ndarray[tuple[Any, ...], dtype[floating]]: Sapwood mass (kg)

stem_height: ndarray[tuple[Any, ...], dtype[floating]]: Stem height (m)

stem_mass: ndarray[tuple[Any, ...], dtype[floating]]: Stem mass (kg)

stem_traits: dataclasses.InitVar[pyrealm.demography.flora.Flora | pyrealm.demography.flora.StemTraits]: An instance of Flora or StemTraits, providing plant functional trait data for a set of stems.

validate: dataclasses.InitVar[bool] = True: Boolean flag to suppress argument validation.

calculate_crown_areas(ca_ratio: ndarray[tuple[Any, ...], dtype[floating]], a_hd: ndarray[tuple[Any, ...], dtype[floating]], dbh: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_crown_fractions(a_hd: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], dbh: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_crown_r0(q_m: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_crown_z_max(z_max_prop: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_dbh_from_height(h_max: ndarray[tuple[Any, ...], dtype[floating]], a_hd: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], zeta: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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.
validate – Boolean flag to suppress argument validation

calculate_fine_root_respiration(fine_root_mass: ndarray[tuple[Any, ...], dtype[floating]], resp_r: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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.
validate – Boolean flag to suppress argument validation

calculate_fine_root_turnover(tau_r: ndarray[tuple[Any, ...], dtype[floating]], fine_root_mass: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_foliage_masses(sla: ndarray[tuple[Any, ...], dtype[floating]], lai: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_foliage_turnover(tau_f: ndarray[tuple[Any, ...], dtype[floating]], foliage_mass: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate turnover costs for foliage.

This function calculates the costs associated with the turnover of foliage. 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
validate – Boolean flag to suppress argument validation

calculate_foliar_respiration(resp_f: ndarray[tuple[Any, ...], dtype[floating]], whole_crown_gpp: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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.
validate – Boolean flag to suppress argument validation

calculate_gpp_topslice(gpp_topslice: ndarray[tuple[Any, ...], dtype[floating]], whole_crown_gpp: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate gpp topslice.

Calculates a fixed proportion of the total GPP for the crown that is removed before further GPP allocation. This is intended as a helper variable for T Model users to simulate processes not included in the T Model such as root exudation or active nutrient servicing for mycorriza fungi.

Note

This is a naive calculation method that is not part of the T model. If values for GPP topslice are zero it will have no impact on the T Model calculations.

Parameters:

gpp_topslice – The portion of GPP to remove before allocation.
whole_crown_gpp – The individual whole crown GPP.
validate – Boolean flag to suppress argument validation

Calculate growth increments.

Given an estimate of net primary productivity (NPP, \(P_{net}\)), less associated turnover costs (\(T\)), the remaining productivity can be allocated to growth and hence estimate resulting increments (Li et al., 2014) 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 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{P_{net} - 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*} \]

Note

The original equations have been extended to include a term to model the costs of maintaining reproductive tissue mass as a fraction of foliage mass. These values can be set to zero to reproduce the predictions of the original T Model calculations.

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
npp – Net primary productivity of individuals
turnover – Fine root and foliage turnover cost of individuals
p_foliage_for_reproductive_tissue – Proportion of foliage mass that is reproductive tissue.
reproductive_tissue_turnover – Reproductive tissue turnover cost of individuals
dbh – Diameter at breast height of individuals
stem_height – Stem height of individuals
validate – Boolean flag to suppress argument validation

calculate_heights(h_max: ndarray[tuple[Any, ...], dtype[floating]], a_hd: ndarray[tuple[Any, ...], dtype[floating]], dbh: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_net_primary_productivity(yld: ndarray[tuple[Any, ...], dtype[floating]], whole_crown_gpp: ndarray[tuple[Any, ...], dtype[floating]], foliar_respiration: ndarray[tuple[Any, ...], dtype[floating]], fine_root_respiration: ndarray[tuple[Any, ...], dtype[floating]], sapwood_respiration: ndarray[tuple[Any, ...], dtype[floating]], reproductive_tissue_respiration: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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\)), sapwood (\(R_s\)), and reproductive tissue (\(R_{rt}\)).

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

Note that this differs from Equation 13 of Li et al. (2014), which does not include a term for foliar respiration or reproductive tissue 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. Li et al. (2014) do not include reproductive tissue respiration in their calculations.

Parameters:

yld – The yield proportion.
whole_crown_gpp – The total GPP for the crown.
foliar_respiration – The total foliar respiration.
fine_root_respiration – The total fine root respiration
sapwood_respiration – The total sapwood respiration.
reproductive_tissue_respiration – The total reproductive tissue respiration.
validate – Boolean flag to suppress argument validation

calculate_reproductive_tissue_mass(foliage_mass: ndarray[tuple[Any, ...], dtype[floating]], p_foliage_for_reproductive_tissue: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate reproductive tissue mass.

This function calculates the mass of reproductive tissue (\(m_{rt}\)) as a fixed proportion of the total foliage mass (\(W_f\)) of individuals.

\[m_{rt} = p_{f_{rt}} W_f\]

Parameters:

foliage_mass – The foliage mass
p_foliage_for_reproductive_tissue – The proportion of foliage mass that is reproductive tissue
validate – Boolean flag to suppress argument validation

calculate_reproductive_tissue_respiration(resp_rt: ndarray[tuple[Any, ...], dtype[floating]], reproductive_tissue_mass: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate reproductive tissue respiration.

Calculates the total reproductive tissue respiration (\(R_{rt}\)) given the reproductive tissue mass (\(M_rt\)) and the reproductive tissue respiration rate of the plant functional type (\(r_{rt}\)).

NOTE: This function is not part of the original T Model, but is included here to allow for the calculation of reproductive tissue respiration in the same way as sapwood respiration.

\[R_{rt} = M_rt \, r_rt\]

Parameters:

resp_rt – The reproductive tissue respiration rate
reproductive_tissue_mass – The stem reproductive tissue mass.
validate – Boolean flag to suppress argument validation

calculate_reproductive_tissue_turnover(reproductive_tissue_mass: ndarray[tuple[Any, ...], dtype[floating]], tau_rt: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate reproductive tissue turnover costs.

This function calculates the costs associated with the turnover of reproductive tissue. This is calculated from the total reproductive tissue mass (\(m_{rt}\)), along with the turnover time of reproductive tissue (\(\tau_{rt}\)).

\[T_{rt} = m_{rt} \left( \frac{1}{\tau_{rt}}\right)\]

Parameters:

reproductive_tissue_mass – The mass of reproductive tissue
tau_rt – The turnover time of reproductive tissue
validate – Boolean flag to suppress argument validation

calculate_sapwood_masses(rho_s: ndarray[tuple[Any, ...], dtype[floating]], ca_ratio: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], crown_fraction: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_sapwood_respiration(resp_s: ndarray[tuple[Any, ...], dtype[floating]], sapwood_mass: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_stem_masses(rho_s: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], dbh: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

calculate_whole_crown_gpp(potential_gpp: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], par_ext: ndarray[tuple[Any, ...], dtype[floating]], lai: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation

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(stem_traits, stem_allometry, z)

Calculate vertical crown profiles for stems.

Functions:

`calculate_crown_radius`(q_z, r0[, validate])	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.
`get_crown_xy`(crown_profile, stem_allometry, attr)	Extract plotting data from crown profiles.

class CrownProfile(stem_traits: dataclasses.InitVar[pyrealm.demography.flora.StemTraits | pyrealm.demography.flora.Flora], stem_allometry: dataclasses.InitVar[StemAllometry], z: ndarray[tuple[Any, ...], dtype[floating]], validate: dataclasses.InitVar[bool] = True)

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:

stem_traits – A Flora or StemTraits instance providing plant functional trait data.
stem_allometry – A StemAllometry instance setting the stem allometries for the crown profile.
z – An array of vertical height values at which to calculate crown profiles.
validate – Boolean flag to suppress argument validation.

Attributes:

`crown_radius`	An array of the actual crown radius of stems at z heights
`projected_crown_area`	An array of the projected crown area of stems at z heights
`projected_crown_radius`	An array of the projected crown radius of stems at z heights.
`projected_leaf_area`	An array of the projected leaf area of stems at z heights
`projected_leaf_radius`	An array of the projected leaf radius of stems at z heights.
`relative_crown_radius`	An array of the relative crown radius of stems at z heights
`stem_allometry`	A StemAllometry instance setting the stem allometries for the crown profile.
`stem_traits`	A Flora or StemTraits instance providing plant functional trait data.
`validate`	Boolean flag to suppress argument validation.
`z`	An array of vertical height values at which to calculate crown profiles.

crown_radius: ndarray[tuple[Any, ...], dtype[floating]]: An array of the actual crown radius of stems at z heights

projected_crown_area: ndarray[tuple[Any, ...], dtype[floating]]: An array of the projected crown area of stems at z heights

property projected_crown_radius: ndarray[tuple[Any, ...], dtype[floating]]: An array of the projected crown radius of stems at z heights.

projected_leaf_area: ndarray[tuple[Any, ...], dtype[floating]]: An array of the projected leaf area of stems at z heights

property projected_leaf_radius: ndarray[tuple[Any, ...], dtype[floating]]: An array of the projected leaf radius of stems at z heights.

relative_crown_radius: ndarray[tuple[Any, ...], dtype[floating]]: An array of the relative crown radius of stems at z heights

stem_allometry: dataclasses.InitVar[StemAllometry]: A StemAllometry instance setting the stem allometries for the crown profile.

stem_traits: dataclasses.InitVar[pyrealm.demography.flora.StemTraits | pyrealm.demography.flora.Flora]: A Flora or StemTraits instance providing plant functional trait data.

validate: dataclasses.InitVar[bool] = True: Boolean flag to suppress argument validation.

z: ndarray[tuple[Any, ...], dtype[floating]]: An array of vertical height values at which to calculate crown profiles.

calculate_crown_radius(q_z: ndarray[tuple[Any, ...], dtype[floating]], r0: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation.

calculate_relative_crown_radius_at_z(z: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], m: ndarray[tuple[Any, ...], dtype[floating]], n: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True, clip: bool = True) → ndarray[tuple[Any, ...], dtype[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:

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\).
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\).
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 stem
m – Canopy shape parameter of PFT
n – Canopy shape parameter of PFT
validate – Boolean flag to suppress argument validation.
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[tuple[Any, ...], dtype[floating]], q_z: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], q_m: ndarray[tuple[Any, ...], dtype[floating]], z_max: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation.

calculate_stem_projected_leaf_area_at_z(z: ndarray[tuple[Any, ...], dtype[floating]], q_z: ndarray[tuple[Any, ...], dtype[floating]], stem_height: ndarray[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], f_g: ndarray[tuple[Any, ...], dtype[floating]], q_m: ndarray[tuple[Any, ...], dtype[floating]], z_max: ndarray[tuple[Any, ...], dtype[floating]], validate: bool = True) → ndarray[tuple[Any, ...], dtype[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
validate – Boolean flag to suppress argument validation.

get_crown_xy(crown_profile: CrownProfile, stem_allometry: StemAllometry, attr: str, stem_offsets: ndarray[tuple[Any, ...], dtype[floating]] | None = None, two_sided: bool = True, as_xy: bool = False) → list[tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]] | list[ndarray[tuple[Any, ...], dtype[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 or indeed below ground.

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:

crown_profile – A crown profile instance
stem_allometry – The stem allometry instance used to create the crown profile
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.

The `community` module

This modules provides the Community class, which contains the set of size-structured cohorts of plants across a range of plant functional types that occur a given location (or ‘cell’) with a given cell id number and area.

The class provides factory methods to create Community instances from CSV, JSON and TOML files, using marshmallow schemas to both validate the input data and to perform post processing to align the input formats to the initialisation arguments to the Community class.

Internally, the cohort data in the Community class is represented as a dictionary of numpy arrays.

Worked example

The example code below demonstrates defining PFTs, creating a Flora collection, initializing a Community, and computing ecological metrics using the T Model for a set of plant cohorts.

>>> import pandas as pd
>>>
>>> from pyrealm.demography.flora import PlantFunctionalType, Flora
>>> from pyrealm.demography.tmodel import (
...     calculate_heights, calculate_crown_areas, calculate_stem_masses,
...     calculate_foliage_masses
... )

>>> pft1 = PlantFunctionalType(
...     name="Evergreen Tree",
...     a_hd=120.0,
...     ca_ratio=380.0,
...     h_max=30.0,
...     rho_s=210.0,
...     lai=3.0,
...     sla=12.0,
...     tau_f=5.0,
...     tau_r=1.2,
...     par_ext=0.6,
...     yld=0.65,
...     zeta=0.18,
...     resp_r=0.95,
...     resp_s=0.045,
...     resp_f=0.12,
...     m=2.5,
...     n=4.5,
... )

>>> pft2 = PlantFunctionalType(
...     name="Deciduous Shrub",
...     a_hd=100.0,
...     ca_ratio=350.0,
...     h_max=4.0,
...     rho_s=180.0,
...     lai=2.0,
...     sla=15.0,
...     tau_f=3.0,
...     tau_r=0.8,
...     par_ext=0.4,
...     yld=0.55,
...     zeta=0.15,
...     resp_r=0.85,
...     resp_s=0.05,
...     resp_f=0.1,
...     m=3.0,
...     n=5.0,
... )

Create a Flora collection:

>>> flora = Flora([pft1, pft2])

Define community data as size-structured cohorts of given plant functional types with a given number of individuals.

>>> cohort_dbh_values = np.array([0.10, 0.03, 0.12, 0.025])
>>> cohort_n_individuals = np.array([100, 200, 150, 180])
>>> cohort_pft_names = np.array(
...    ["Evergreen Tree", "Deciduous Shrub", "Evergreen Tree", "Deciduous Shrub"]
... )

Initialize a Community into an area of 1000 square meter with the given cohort data:

>>> community = Community(
...     cell_id=1,
...     cell_area=1000.0,
...     flora=flora,
...     cohorts=Cohorts(
...         dbh_values=cohort_dbh_values,
...         n_individuals=cohort_n_individuals,
...         pft_names=cohort_pft_names,
...     ),
... )

The data in the Community class is stored under three attributes, each of which stores an instance of a dataclass holding related parts of the community data. All have a to_pandas method that can be used to visualise and explore the data. Note that the Cohorts class automatically adds a unique internal ID to each cohort which is not shown here:

>>> community.cohorts.to_pandas().drop(columns="cohort_id")
   dbh_values  n_individuals        pft_names
0       0.100            100   Evergreen Tree
1       0.030            200  Deciduous Shrub
2       0.120            150   Evergreen Tree
3       0.025            180  Deciduous Shrub

>>> community.stem_allometry.to_pandas()[
...     ["stem_height", "crown_area", "stem_mass", "crown_r0", "crown_z_max"]
... ]  
                   stem_height  crown_area  stem_mass  crown_r0  crown_z_max
column_stem_index
0                     9.890399    2.459835   8.156296  0.339477     7.789552
1                     2.110534    0.174049   0.134266  0.083788     1.642777
2                    11.436498    3.413238  13.581094  0.399890     9.007241
3                     1.858954    0.127752   0.082126  0.071784     1.446955

>>> community.stem_traits.to_pandas()[
...     ["name", "a_hd", "ca_ratio", "sla", "par_ext", "q_m",  "z_max_prop"]
... ]
              name   a_hd  ca_ratio   sla  par_ext       q_m  z_max_prop
0   Evergreen Tree  120.0     380.0  12.0      0.6  2.606561    0.787587
1  Deciduous Shrub  100.0     350.0  15.0      0.4  2.809188    0.778371
2   Evergreen Tree  120.0     380.0  12.0      0.6  2.606561    0.787587
3  Deciduous Shrub  100.0     350.0  15.0      0.4  2.809188    0.778371

Classes:

`CohortSchema`(*[, only, exclude, many, ...])	A validation schema for Cohort data objects.
`Cohorts`(n_individuals, ...], ...)	A dataclass to hold data for a set of plant cohorts.
`Community`(cell_id, cell_area, flora, cohorts)	The plant community class.
`CommunityCSVDataSchema`(*[, only, exclude, ...])	A validation schema for community initialisation data in CSV format.
`CommunityStructuredDataSchema`(*[, only, ...])	A validation schema for Cohort data in a structured format (JSON/TOML).

A validation schema for Cohort data objects.

This schema can be used to validate the cohorts components of JSON and TOML community data files, which are simple dictionaries:

TOML

dbh_value = 0.2
n_individuals = 6
pft_name = "broadleaf"

JSON

{
    "pft_name": "broadleaf",
    "dbh_value": 0.2,
    "n_individuals": 6
}

class Cohorts(n_individuals: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.int64]], pft_names: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.str_]], dbh_values: dataclasses.InitVar[numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.floating]]] = <property object>)

A dataclass to hold data for a set of plant cohorts.

Experimental

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

The attributes should be numpy arrays of equal length, containing an entry for each cohort in the data class. The class automatically populates each cohort with a unique id in the cohort_id property, using UUID4 values. The setter for this property enforces unique values in this property. The most likely source of this error would be if the CohortMethods.add_cohort_data method was used to add a Cohorts instance to itself.

Attributes:

`cohort_id`	Automatically populated with a UUID4 id for each cohort.
`dbh_values`	The diameter at breast height of the cohorts (m).

property cohort_id: ndarray[tuple[Any, ...], dtype[str_]]: Automatically populated with a UUID4 id for each cohort.

property dbh_values: ndarray[tuple[Any, ...], dtype[floating]]: The diameter at breast height of the cohorts (m).

class Community(cell_id: int, cell_area: float, flora: Flora, cohorts: Cohorts)

The plant community class.

Experimental

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

A community is a set of size-structured plant cohorts in a given location, where the location has a specified numeric id and a known area in square meters.

A cohort defines a number of individual plants with the same diameter at breast height (DBH) and plant functional type (PFT). Internally, the cohort data is built into a pandas.DataFrame with each row representing a cohort and each column representing a property of the cohort. The initial input data is extended to include the plant functional type traits for each cohort (see PlantFunctionalType) and then is further extended to include the geometric and canopy predictions of the T Model for each cohort.

Factory methods are provided to load community data from csv, TOML or JSON files.

Parameters:

cell_id – An positive integer id for the community location.
cell_area – An area in square metres for the community location.
flora – A flora object containing the plant functional types for the community
cohort_dbh_values – A numpy array giving the diameter at breast height in metres for each cohort.
cohort_n_individuals – A numpy array giving the number of individuals in each cohort.
cohort_pft_names – A numpy array giving the name of the plant functional type in each cohort.

Methods:

`add_cohorts`(new_data)	Add a new set of cohorts to the community.
`drop_cohorts`(drop_indices)	Drop cohorts from the community.
`from_csv`(path, flora)	Create a Community object from a CSV file.
`from_json`(path, flora)	Create a Community object from a JSON file.
`from_toml`(path, flora)	Create a Community object from a TOML file.

add_cohorts(new_data: Cohorts) → None

Add a new set of cohorts to the community.

This method extends the cohorts attribute with the new cohort data and then also extends the stem_traits and stem_allometry to match.

Parameters:: new_data – An instance of Cohorts containing cohort data to add to the community.

drop_cohorts(drop_indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Drop cohorts from the community.

This method drops the identified cohorts from the cohorts attribute and then removes their data from the stem_traits and stem_allometry attributes to match.

classmethod from_csv(path: Path, flora: Flora) → Community

Create a Community object from a CSV file.

This factory method checks that the required fields are present in the CSV data and that the cell_id and cell_area values are constant. It then passes the data through further validation using the meth:~pyrealm.demography.community.Community._from_file_data method and returns a Community instance.

Parameters:

path – A path to a CSV file of community data
flora – A Flora instance providing plant functional types used in the community data

classmethod from_json(path: Path, flora: Flora) → Community

Create a Community object from a JSON file.

This factory method loads community data from a JSON community file and validates it using class:~pyrealm.demography.community.CommunityStructuredDataSchema before using the data to initialise a Community instance.

Parameters:

path – A path to a JSON file of community data
flora – A Flora instance providing plant functional types used in the community data

classmethod from_toml(path: Path, flora: Flora) → Community

Create a Community object from a TOML file.

This factory method loads community data from a TOML community file and validates it using class:~pyrealm.demography.community.CommunityStructuredDataSchema before using the data to initialise a Community instance.

Parameters:

path – A path to a TOML file of community data
flora – A Flora instance providing plant functional types used in the community data

A validation schema for community initialisation data in CSV format.

This schema can be used to validate data for creating a Community instance stored in CSV format. The file is expected to provide fields providing cell id and cell area and then functional type name, diameter at breast height (DBH) and number of individuals. Each row is taken to represent a cohort and the cell id and area must* be consistent across rows.

cell_id,cell_area,cohort_pft_names,cohort_dbh_values,cohort_n_individuals
1,100,broadleaf,0.2,6
1,100,broadleaf,0.25,6
1,100,broadleaf,0.3,3
1,100,broadleaf,0.35,1
1,100,conifer,0.5,1
1,100,conifer,0.6,1

The input data is expected to be provided to this schema as a dictionary of lists of field values keyed by field name, as for example by using pandas.DataFrame.to_dict() with the orient='list' argument.

The schema automatically validates that the cell id and area are consistent and then post-processing is used to simplify those fields to the scalar inputs required to initialise instances of the Community class and to convert the cohort data into arrays,

Methods:

`convert_to_community_args`(data, **kwargs)	Make cell data scalar.
`validate_consistent_cell_data`(data, **kwargs)	Schema wide validation.

convert_to_community_args(data: dict, **kwargs: Any) → dict[str, Any]

Make cell data scalar.

This post load method reduces the repeated cell id and cell area across CSV data rows into the scalar inputs required to initialise a Community object and packages the data on individual cohorts into a Cohorts object.

validate_consistent_cell_data(data: dict, **kwargs: Any) → None

Schema wide validation.

Parameters:

data – Data passed to the validator
kwargs – Additional keyword arguments passed by marshmallow

A validation schema for Cohort data in a structured format (JSON/TOML).

This schema can be used to validate data for creating a Community instance stored in a structured format such as JSON or TOML. The format is expected to provide a cell area and id along with an array of cohort objects providing the plant functional type name, diameter at breast height (DBH) and number of individuals (see CohortSchema). Example inputs with this structure are:

TOML

cell_area = 100
cell_id = 1

[[cohorts]]
dbh_value = 0.2
n_individuals = 6
pft_name = "broadleaf"

[[cohorts]]
dbh_value = 0.25
n_individuals = 6
pft_name = "conifer"

JSON

{
"cell_id": 1,
"cell_area": 100,
"cohorts": [
    {
        "pft_name": "broadleaf",
        "dbh_value": 0.2,
        "n_individuals": 6
    },
    {
        "pft_name": "broadleaf",
        "dbh_value": 0.25,
        "n_individuals": 6
    }]
}

Any data validated with this schema is post-processed to convert the cohort objects into the arrays of cohort data required to initialise instances of the Community class.

Methods:

convert_to_community_args(data, **kwargs)

Convert cohorts to arrays.

convert_to_community_args(data: dict, **kwargs: Any) → dict[str, Any]

Convert cohorts to arrays.

This post load method converts the cohort arrays into a Cohorts objects and packages the data up into the required arguments used to initialise a Community object.

Parameters:

data – Data passed to the validator
kwargs – Additional keyword arguments passed by marshmallow

The `canopy` module

Functionality for canopy modelling.

Classes:

`Canopy`(community[, layer_heights, fit_ppa, ...])	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(community: Community, layer_heights: ndarray[tuple[Any, ...], dtype[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[tuple[Any, ...], dtype[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[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]], n_individuals: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.int64]]], lai: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]], par_ext: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[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:

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.
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.
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[tuple[Any, ...], dtype[floating]]: The Beer-Lambert absorption fraction for each cohort.

community_data: CommunityCanopyData: The community wide canopy properties.

fapar: ndarray[tuple[Any, ...], dtype[floating]]: The across layer fractions of absorbed radiation for each cohort by layer.

lai: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: The leaf area index of the plant functional type for each cohort.

n_individuals: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.int64]]]: The number of individuals for each cohort.

par_ext: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: The extinction coefficient of the plant functional type for each cohort.

projected_leaf_area: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: An array of the stem projected leaf area for each cohort at each of the required heights.

stem_leaf_area: ndarray[tuple[Any, ...], dtype[floating]]: The leaf area of the crown model for each cohort by layer.

class CommunityCanopyData(absorption: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]], leaf_area_index: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]], cohort_leaf_area: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[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[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: The Beer Lambert light absorption fraction for each cohort.

average_layer_absorption: ndarray[tuple[Any, ...], dtype[floating]]: The average absorption within layers across the community.

average_layer_fapar: ndarray[tuple[Any, ...], dtype[floating]]: The average fAPAR of the community for each layer.

average_layer_lai: ndarray[tuple[Any, ...], dtype[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[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: The total leaf area per cohort for each layer.

leaf_area_index: dataclasses.InitVar[numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.floating]]]: The leaf area index for each cohort.

transmission_profile: ndarray[tuple[Any, ...], dtype[floating]]: The light transmission profile through the canopy by layer.

transmission_to_ground: ndarray[tuple[Any, ...], dtype[floating]]: The fraction of light reaching the ground below the canopy.

fit_perfect_plasticity_approximation(community: Community, canopy_gap_fraction: float, max_stem_height: float, solver_tolerance: float) → ndarray[tuple[Any, ...], dtype[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:

community – A community instance providing plant cohort data
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[tuple[Any, ...], dtype[floating]], crown_area: ndarray[tuple[Any, ...], dtype[floating]], m: ndarray[tuple[Any, ...], dtype[floating]], n: ndarray[tuple[Any, ...], dtype[floating]], q_m: ndarray[tuple[Any, ...], dtype[floating]], z_max: ndarray[tuple[Any, ...], dtype[floating]], n_individuals: ndarray[tuple[Any, ...], dtype[floating]], target_area: float = 0, validate: bool = True) → ndarray[tuple[Any, ...], dtype[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.
validate – Boolean flag to suppress argument validation.

The demography module

The core module

The flora module

The tmodel module

The crown module

The community module

Worked example

The canopy module

The `demography` module

The `core` module

The `flora` module

The `tmodel` module

The `crown` module

The `community` module

The `canopy` module