Growth Estimation¶

Estimate annual tree growth rates.

Overview¶

The growth() function calculates annual growth estimates using GRM methodology.

import pyfia

db = pyfia.FIA("georgia.duckdb")
db.clip_by_state("GA")

# Net growth volume
result = pyfia.growth(db, measure="volume")

# Growth by species
by_species = pyfia.growth(db, measure="volume", grp_by="SPCD")

Function Reference¶

growth ¶

growth(db: str | FIA, grp_by: str | list[str] | None = None, by_species: bool = False, by_size_class: bool = False, size_class_type: str = 'standard', land_type: str = 'forest', tree_type: str = 'gs', measure: str = 'volume', tree_domain: str | None = None, area_domain: str | None = None, totals: bool = True, variance: bool = False, most_recent: bool = False) -> DataFrame

Estimate annual tree growth from FIA data using GRM methodology.

Calculates annual growth of tree volume, biomass, or tree count using FIA's Growth-Removal-Mortality (GRM) tables following EVALIDator methodology.

PARAMETER	DESCRIPTION
`db`	Database connection or path to FIA database. TYPE: `str \| FIA`
`grp_by`	Column name(s) to group results by. TYPE: `str or list of str` DEFAULT: `None`
`by_species`	If True, group results by species code (SPCD). TYPE: `bool` DEFAULT: `False`
`by_size_class`	If True, group results by diameter size classes. TYPE: `bool` DEFAULT: `False`
`size_class_type`	Type of size class grouping to use (only applies when by_size_class=True): - "standard": FIA numeric ranges (1.0-4.9, 5.0-9.9, etc.) - "descriptive": Text labels (Saplings, Small, Medium, Large) - "market": Timber market categories (Pulpwood, Chip-n-Saw, Sawtimber) TYPE: `('standard', 'descriptive', 'market')` DEFAULT: `'standard'`
`land_type`	Land type to include in estimation. TYPE: `('forest', 'timber')` DEFAULT: `'forest'`
`tree_type`	Tree type to include. TYPE: `('gs', 'al', 'sl')` DEFAULT: `'gs'`
`measure`	What to measure in the growth estimation. TYPE: `('volume', 'biomass', 'count')` DEFAULT: `'volume'`
`tree_domain`	SQL-like filter expression for tree-level filtering. TYPE: `str` DEFAULT: `None`
`area_domain`	SQL-like filter expression for area/condition-level filtering. TYPE: `str` DEFAULT: `None`
`totals`	If True, include population-level total estimates. TYPE: `bool` DEFAULT: `True`
`variance`	If True, calculate and include variance and standard error estimates. TYPE: `bool` DEFAULT: `False`
`most_recent`	If True, automatically filter to the most recent evaluation. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`DataFrame`	Growth estimates with columns: - GROWTH_ACRE: Annual growth per acre - GROWTH_TOTAL: Total annual growth (if totals=True) - GROWTH_ACRE_SE: Standard error of per-acre estimate (if variance=True) - Additional grouping columns if specified

See Also

mortality : Estimate annual mortality using GRM tables removals : Estimate annual removals/harvest using GRM tables

Examples:

Basic volume growth on forestland:

>>> results = growth(db, measure="volume", land_type="forest")

Growth by species (tree count):

>>> results = growth(db, by_species=True, measure="count")

Notes

This function uses FIA's GRM tables which contain component-level tree data for calculating annual growth. The implementation follows EVALIDator methodology for statistically valid estimation.

Source code in src/pyfia/estimation/estimators/growth.py

def growth(
    db: str | FIA,
    grp_by: str | list[str] | None = None,
    by_species: bool = False,
    by_size_class: bool = False,
    size_class_type: str = "standard",
    land_type: str = "forest",
    tree_type: str = "gs",
    measure: str = "volume",
    tree_domain: str | None = None,
    area_domain: str | None = None,
    totals: bool = True,
    variance: bool = False,
    most_recent: bool = False,
) -> pl.DataFrame:
    """
    Estimate annual tree growth from FIA data using GRM methodology.

    Calculates annual growth of tree volume, biomass, or tree count using
    FIA's Growth-Removal-Mortality (GRM) tables following EVALIDator
    methodology.

    Parameters
    ----------
    db : str | FIA
        Database connection or path to FIA database.
    grp_by : str or list of str, optional
        Column name(s) to group results by.
    by_species : bool, default False
        If True, group results by species code (SPCD).
    by_size_class : bool, default False
        If True, group results by diameter size classes.
    size_class_type : {'standard', 'descriptive', 'market'}, default 'standard'
        Type of size class grouping to use (only applies when by_size_class=True):
        - "standard": FIA numeric ranges (1.0-4.9, 5.0-9.9, etc.)
        - "descriptive": Text labels (Saplings, Small, Medium, Large)
        - "market": Timber market categories (Pulpwood, Chip-n-Saw, Sawtimber)
    land_type : {'forest', 'timber'}, default 'forest'
        Land type to include in estimation.
    tree_type : {'gs', 'al', 'sl'}, default 'gs'
        Tree type to include.
    measure : {'volume', 'biomass', 'count'}, default 'volume'
        What to measure in the growth estimation.
    tree_domain : str, optional
        SQL-like filter expression for tree-level filtering.
    area_domain : str, optional
        SQL-like filter expression for area/condition-level filtering.
    totals : bool, default True
        If True, include population-level total estimates.
    variance : bool, default False
        If True, calculate and include variance and standard error estimates.
    most_recent : bool, default False
        If True, automatically filter to the most recent evaluation.

    Returns
    -------
    pl.DataFrame
        Growth estimates with columns:
        - GROWTH_ACRE: Annual growth per acre
        - GROWTH_TOTAL: Total annual growth (if totals=True)
        - GROWTH_ACRE_SE: Standard error of per-acre estimate (if variance=True)
        - Additional grouping columns if specified

    See Also
    --------
    mortality : Estimate annual mortality using GRM tables
    removals : Estimate annual removals/harvest using GRM tables

    Examples
    --------
    Basic volume growth on forestland:

    >>> results = growth(db, measure="volume", land_type="forest")

    Growth by species (tree count):

    >>> results = growth(db, by_species=True, measure="count")

    Notes
    -----
    This function uses FIA's GRM tables which contain component-level tree
    data for calculating annual growth. The implementation follows
    EVALIDator methodology for statistically valid estimation.
    """
    from ...validation import (
        validate_boolean,
        validate_domain_expression,
        validate_grp_by,
        validate_land_type,
        validate_mortality_measure,
        validate_tree_type,
    )

    land_type = validate_land_type(land_type)
    tree_type = validate_tree_type(tree_type)
    measure = validate_mortality_measure(measure)
    grp_by = validate_grp_by(grp_by)
    tree_domain = validate_domain_expression(tree_domain, "tree_domain")
    area_domain = validate_domain_expression(area_domain, "area_domain")
    by_species = validate_boolean(by_species, "by_species")
    by_size_class = validate_boolean(by_size_class, "by_size_class")
    totals = validate_boolean(totals, "totals")
    variance = validate_boolean(variance, "variance")
    most_recent = validate_boolean(most_recent, "most_recent")

    valid_size_class_types = ("standard", "descriptive", "market")
    if size_class_type not in valid_size_class_types:
        raise ValueError(
            f"size_class_type must be one of {valid_size_class_types}, got {size_class_type!r}"
        )

    config = {
        "grp_by": grp_by,
        "by_species": by_species,
        "by_size_class": by_size_class,
        "size_class_type": size_class_type,
        "land_type": land_type,
        "tree_type": tree_type,
        "measure": measure,
        "tree_domain": tree_domain,
        "area_domain": area_domain,
        "totals": totals,
        "variance": variance,
        "most_recent": most_recent,
        "include_cv": False,
    }

    estimator = GrowthEstimator(db, config)
    return estimator.estimate()

Measurement Types¶

Measure	Description
`"volume"`	Net cubic-foot volume growth
`"sawlog"`	Board-foot sawlog growth
`"biomass"`	Above-ground biomass growth
`"tpa"`	Trees per acre growth

Technical Notes¶

Growth estimation uses:

TREE_GRM_COMPONENT table for growth components
TREE_GRM_MIDPT table for annualized values
TREE_GRM_BEGIN table for initial measurements
BEGINEND table for temporal alignment

Net growth = Survivor growth + Ingrowth - Mortality

Examples¶

Total Net Growth¶

result = pyfia.growth(
    db,
    measure="volume",
    land_type="forest"
)
print(f"Annual Growth: {result['estimate'][0]:,.0f} cu ft/year")

Growth by Species¶

result = pyfia.growth(
    db,
    measure="volume",
    grp_by="SPCD"
)
result = pyfia.join_species_names(result, db)
print(result.sort("estimate", descending=True).head(10))

Growing Stock Growth on Timberland¶

result = pyfia.growth(
    db,
    measure="volume",
    land_type="timber",
    tree_type="gs"
)

Biomass Growth¶

result = pyfia.growth(
    db,
    measure="biomass",
    land_type="forest"
)
print(f"Annual Biomass Growth: {result['estimate'][0]:,.0f} tons/year")

Growth by Size Class¶

Group growth by diameter size classes:

# Standard FIA size classes (1.0-4.9, 5.0-9.9, 10.0-19.9, etc.)
result = pyfia.growth(db, by_size_class=True)
print(result)

# Descriptive labels (Saplings, Small, Medium, Large)
result = pyfia.growth(db, by_size_class=True, size_class_type="descriptive")
print(result)

# Timber market classes (Pulpwood, Chip-n-Saw, Sawtimber)
result = pyfia.growth(db, by_size_class=True, size_class_type="market")
print(result)

See Mortality - Size Class Types for details on size class options.