The `phenology` module

The phenology module.

The FAPAR limitation module

Class to compute the fAPAR_max and annual peak Leaf Area Index (LAI).

class FaparLimitation(annual_total_potential_gpp: ndarray[tuple[Any, ...], dtype[float64]], annual_mean_ca: ndarray[tuple[Any, ...], dtype[float64]], annual_mean_chi: ndarray[tuple[Any, ...], dtype[float64]], annual_mean_vpd: ndarray[tuple[Any, ...], dtype[float64]], annual_total_precip: ndarray[tuple[Any, ...], dtype[float64]], annual_growing_season_length: ndarray[tuple[Any, ...], dtype[float64]], aridity_index: ndarray[tuple[Any, ...], dtype[float64]], phenology_const: PhenologyConst = PhenologyConst())

Compute maximum annual fAPAR and LAI.

Experimental

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

This class calculates maximum annual fAPAR and LAI, following (Cai et al., 2025). The maximum annual fAPAR is calculated as the minimum of two terms capturing energy-limited and water limited fAPAR:

\[\text{fAPAR}_{max} = \min{ \left(1 - z / \left(k A_0 \right) \right), \left( c_a \left( 1 - \chi \right) / 1.6 D \right) \left( f_0 P / A_0 \right) }\]

The maximum annual LAI is then calculated using Beer’s law:

\[\text{LAI}_{max} = - ( 1 / k ) \ln {1 - \text{fAPAR}_{max}}\]

The class also calculates the parameter \(m\), which is the steady state annual ratio of leaf area index to GPP:

\[m = \frac{ \sigma G \text{LAI}_{max}}{A_0 \text{fAPAR}_{max}}\]

The PhenologyConst class provides values for the following constants:

\(z\) accounts for the growth and maintenance costs of leaves.
\(k\) is the light extinction coefficient.
\(f_0\) is is the ratio of annual total transpiration of annual total precipitation, calculated from the climatological aridity index (AI) (see PhenologyConst.calculate_f0).
\(\sigma\) is a proportion that captures the departure of \(m\) from the maximum due to biological delays in deploying and dropping the canopy during the growing season.

The other variables are the required arguments to the class defined below. The most common source of these variables is from a P Model, and the from_pmodel() method can be used to create an instance directly from a fitted P Model.

Parameters:

annual_total_potential_gpp – The annual sum of potential GPP (\(A_0, \text{mol C m}^{-2} \text{year}^{-1}\))
annual_mean_ca – The ambient CO2 partial pressure during the growing season (\(c_a\), Pa)
annual_mean_chi – The annual mean ratio of ambient to leaf CO2 partial during the growing season (\(\chi\), Pa)
annual_mean_vpd – The annual mean vapour pressure deficit during the growing season (\(D\), Pa)
annual_total_precip – The annual total precipitation (\(P, \text{mol m}^{-2} \text{year}^{-1}\))
annual_growing_season_length – The length of the growing season in days for each year (\(G\), days)
aridity_index – A climatological estimate of the local aridity index, calculated as the long term (typically 20 years) total PET over total precipitation (\(AI\), unitless)
phenology_const – An instance of PhenologyConst

classmethod from_pmodel(pmodel: PModelABC, growing_season: ndarray[tuple[Any, ...], dtype[bool]], precip: ndarray[tuple[Any, ...], dtype[float64]], aridity_index: ndarray[tuple[Any, ...], dtype[float64]], datetimes: ndarray[tuple[Any, ...], dtype[datetime64]] | None = None, gpp_penalty_factor: ndarray[tuple[Any, ...], dtype[float64]] | None = None, phenology_const: PhenologyConst = PhenologyConst()) → Self

Create a FaparLimitation instance from a P Model and other inputs.

The annual summary values of \(A_0, c_a, \chi\) and \(D\) used by the FaparLimitation() class can be taken directly from the predictions of a P Model. This method automatically extracts the required data from a fitted P Model and returns a FaparLimitation instance.

Note

The calculation of fAPAR limitation requires estimates of potential GPP, so the PModelEnvironment instance used to fit the model must set fapar to be one.

Some additional information is needed:

The calculation requires annual summaries of variables, so the datetimes argument must be used to provide an array of datetimes for each observation.
The annual mean values \(c_a, \chi\) and \(D\) should be estimated during the growing season, so the growing_season argument must be used to provide a boolean value indicating which observations should be treated as in the growing season.
The calculation requires estimates of precipitation, so the precipitation argument must provide estimates of total precipitation during each observations in moles of water per metre squared.
The calculation of the \(f_0\) parameter requires estimates of site specific aridity index.

The method accepts both standard and subdaily P Models and automatically uses the actual time intervals between observations to calculate the required weighted annual means and sums. This might lead to unexpected values: the yearly mean of monthly values \(1, 2, \dots, 12\) would not be 6.5 because the monthly values are weighted according to the length of the month.

Lastly, potential GPP is taken directly from the P Model instance. If you want to apply a post-hoc penalty factor to GPP (e.g. a water limitation factor), then you can optionally provide per-observation penalty estimates and they will be applied when calculating annual total potential assimilation.

Parameters:

pmodel – A pyrealm.pmodel.pmodel.PModel or pyrealm.pmodel.pmodel.SubdailyPModel instance, fitted with fapar fixed at one.
datetimes – An array giving the datetimes of observations.
growing_season – A boolean array indicating which observations are to be considered as part of the growing season.
precip – An array of precipitation for each observation.
aridity_index – A climatological estimate of local aridity index.
gpp_penalty_factor – A post-hoc penalty factor to be applied to estimated GPP.
phenology_const – An instance of PhenologyConst

annual_growing_season_length: Annual growing season length (\(G\), days)

annual_mean_ca: Ambient CO2 partial pressure during the growing season (\(c_a\), Pa)

annual_mean_chi: Annual mean ratio of ambient to leaf CO2 partial during the growing season (\(\chi\), Pa)

annual_mean_vpd: Annual mean vapour pressure deficit during the growing season (\(D\), Pa)

annual_precip_molar: ndarray[tuple[Any, ...], dtype[floating]]: The annual total precipitation for each year (moles year-1).

annual_total_potential_gpp: The annual sum of potential GPP (\(A_0, \text{mol C m}^{-2} \text{year}^{-1}\))

annual_total_precip: Annual total precipitation (\(P, \text{mol m}^{-2} \text{year}^{-1}\))

aridity_index: Climatological estimate of local aridity index (AI, unitless)

energy_limited: ndarray[tuple[Any, ...], dtype[bool]]: Boolean array showing if annual \(fAPAR_{max}\) is water or energy limited.

fapar_max: ndarray[tuple[Any, ...], dtype[floating]]: Estimated annual maximum fAPAR (unitless).

lai_max: ndarray[tuple[Any, ...], dtype[floating]]: Estimated annual maximum LAI (unitless)

lai_to_gpp_ratio_m: The steady state ratio of leaf area index to potential GPP (\(m\))

The phenology module

The FAPAR limitation module

The `phenology` module