Plant functional types and cohorts

Run this notebook

Warning

This area of pyrealm is in active development and this notebook currently contains notes and initial demonstration code.

This page introduces the main components of the demography module that:

  • describe plant functional types (PFTs) and their traits

  • define size-structured cohorts as a number of individuals from a specific PFT with a given diameter at breast height (DBH).

import numpy as np

from pyrealm.demography.flora import Flora
from pyrealm.demography.cohorts import (
    create_cohorts,
    create_cohorts_from_csv,
    cohort_id_generator,
)

Plant traits

The table below shows the traits used to define the behaviour of different PFTs in demographic simulations. These traits mostly consist of the parameters defined in the T Model (Li et al., 2014) to govern the allometric scaling and carbon allocation of trees, but also include parameters for crown shape that follow the implementation developed in the PlantFATE model (Joshi et al., 2022).

Trait name

Description

a_hd

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

ca_ratio

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

h_max

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

rho_s

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

lai

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

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)

par_ext

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

yld

Yield factor (\(y\), -)

zeta

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

resp_r

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

resp_s

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

resp_f

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

m

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

n

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

f_g

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

q_m

Scaling factor to derive maximum crown radius from crown area.

z_max_prop

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

The Flora class

The Flora class is used to create a set of PFTs that will be used in a demographic simulation. It can be created directly by providing a list of values for each trait: you must provide the same length list of values for each trait but if you omit some traits then they will be automatically populated from default values.

flora = Flora(name=["short", "medium", "tall"], h_max=[10, 20, 30])
flora

Flora with 3 PFTS: short,medium,tall

You can use the to_dataframe() method of Flora to export the trait data as a pandas.DataFrame, making it easier to use for plotting or calculations outside of pyrealm.

flora.to_dataframe().transpose()
0 1 2
name short medium tall
a_hd 116.0 116.0 116.0
ca_ratio 390.43 390.43 390.43
h_max 10.0 20.0 30.0
rho_s 200.0 200.0 200.0
lai 1.8 1.8 1.8
sla 14.0 14.0 14.0
tau_f 4.0 4.0 4.0
tau_r 1.04 1.04 1.04
tau_b inf inf inf
par_ext 0.5 0.5 0.5
yld 0.6 0.6 0.6
zeta 0.17 0.17 0.17
resp_r 0.913 0.913 0.913
resp_s 0.044 0.044 0.044
resp_f 0.1 0.1 0.1
m 2 2 2
n 5 5 5
f_g 0.05 0.05 0.05
q_m 2.903899 2.903899 2.903899
z_max_prop 0.850283 0.850283 0.850283

You can also create a Flora instance using PFT data stored in a CSV file. Note that this CSV only provides some of the PFT traits, you can use Flora.from_csv("pfts.csv", strict=True) to require that the file provides all the traits.

flora_from_csv = Flora.from_csv("pfts.csv")
flora_from_csv

Flora with 2 PFTS: short,tall

Plant Cohorts

The demography module works with size-structured cohorts, where each cohort is simply a number of individuals of a given PFT of a given size. In pyrealm, the size of cohorts is captured using the diameter at breast height (DBH, metres) and the T model is then used to predict the wider allometry and carbon allocation of those individuals.

The Cohorts structure is therefore simply a dataframe. Each row describes a separate cohort, with a unique ID tag, and the columns provide the cohort details, including the matching trait data for the PFT. Cohorts can also optionally be assigned into communities, allowing data for several locations to be held in the same Cohorts instance.

A Cohorts instance is generated using either create_cohorts or create_cohorts_from_csv. Both functions require a Flora object to match cohort PFT names to trait data and a cohort ID generator.

# Create a simple community with three cohorts
# - 15 saplings of the short PFT
# - 5 larger stems of the short PFT
# - 2 large stems of tall PFT

cid_generator = cohort_id_generator()

cohorts = create_cohorts(
    dbh_value=np.array([0.02, 0.20, 0.5]),
    n_individuals=np.array([15, 5, 2]),
    pft_name=np.array(["short", "short", "tall"]),
    flora=flora,
    cid_generator=cid_generator,
)

cohorts.transpose()
0 1 2
cohort_id fdeb7ad0-3922-4166-a5db-a35e0047909a 83f6b33a-7a92-48e7-8ab5-1cfde130fa33 2d71f7ff-393e-4fcb-bf81-40956e3db4ba
pft_name short short tall
dbh_value 0.02 0.2 0.5
n_individuals 15 5 2
name short short tall
a_hd 116.0 116.0 116.0
ca_ratio 390.43 390.43 390.43
h_max 10.0 10.0 30.0
rho_s 200.0 200.0 200.0
lai 1.8 1.8 1.8
sla 14.0 14.0 14.0
tau_f 4.0 4.0 4.0
tau_r 1.04 1.04 1.04
tau_b inf inf inf
par_ext 0.5 0.5 0.5
yld 0.6 0.6 0.6
zeta 0.17 0.17 0.17
resp_r 0.913 0.913 0.913
resp_s 0.044 0.044 0.044
resp_f 0.1 0.1 0.1
m 2 2 2
n 5 5 5
f_g 0.05 0.05 0.05
q_m 2.903899 2.903899 2.903899
z_max_prop 0.850283 0.850283 0.850283

Using the create_cohorts_from_csv function works in much the same way and is used below to show a Cohorts instance being created from cohort data in a CSV file. This data contains a community_id field.

A new ID generator instance is used below to show an alternative ID style but in general you would create one generator and use it throughout any simulation.

cid_generator = cohort_id_generator(mode="str")

cohorts = create_cohorts_from_csv(
    path="./cohorts.csv",
    flora=flora,
    cid_generator=cid_generator,
)

cohorts.transpose()
0 1 2 3 4 5
cohort_id C_000000 C_000001 C_000002 C_000003 C_000004 C_000005
pft_name short short tall short short tall
dbh_value 0.02 0.2 0.5 0.02 0.2 0.5
n_individuals 15 5 2 15 5 2
community_id 1 1 1 2 2 2
name short short tall short short tall
a_hd 116.0 116.0 116.0 116.0 116.0 116.0
ca_ratio 390.43 390.43 390.43 390.43 390.43 390.43
h_max 10.0 10.0 30.0 10.0 10.0 30.0
rho_s 200.0 200.0 200.0 200.0 200.0 200.0
lai 1.8 1.8 1.8 1.8 1.8 1.8
sla 14.0 14.0 14.0 14.0 14.0 14.0
tau_f 4.0 4.0 4.0 4.0 4.0 4.0
tau_r 1.04 1.04 1.04 1.04 1.04 1.04
tau_b inf inf inf inf inf inf
par_ext 0.5 0.5 0.5 0.5 0.5 0.5
yld 0.6 0.6 0.6 0.6 0.6 0.6
zeta 0.17 0.17 0.17 0.17 0.17 0.17
resp_r 0.913 0.913 0.913 0.913 0.913 0.913
resp_s 0.044 0.044 0.044 0.044 0.044 0.044
resp_f 0.1 0.1 0.1 0.1 0.1 0.1
m 2 2 2 2 2 2
n 5 5 5 5 5 5
f_g 0.05 0.05 0.05 0.05 0.05 0.05
q_m 2.903899 2.903899 2.903899 2.903899 2.903899 2.903899
z_max_prop 0.850283 0.850283 0.850283 0.850283 0.850283 0.850283