Mortality Estimation¶

Estimate annual tree mortality rates and volumes.

Overview¶

The mortality() function calculates annual mortality estimates using GRM (Growth, Removals, Mortality) methodology.

import pyfia

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

# Mortality volume
result = pyfia.mortality(db, measure="volume")

# Mortality by cause
by_agent = pyfia.mortality(db, measure="volume", grp_by="AGENTCD")

Function Reference¶

mortality ¶

mortality(db: Union[str, FIA], grp_by: Optional[Union[str, List[str]]] = None, by_species: bool = False, by_size_class: bool = False, land_type: str = 'timber', tree_type: str = 'gs', measure: str = 'volume', tree_domain: Optional[str] = None, area_domain: Optional[str] = None, as_rate: bool = False, totals: bool = True, variance: bool = False, most_recent: bool = False) -> DataFrame

Estimate annual tree mortality from FIA data using GRM methodology.

Uses TREE_GRM_COMPONENT and TREE_GRM_MIDPT tables to calculate annual mortality following FIA's Growth-Removal-Mortality approach. This is the correct FIA statistical methodology for mortality estimation.

PARAMETER	DESCRIPTION
`db`	Database connection or path to FIA database. TYPE: `Union[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`
`land_type`	Land type to include in estimation. TYPE: `(forest, timber)` DEFAULT: `'forest'`
`tree_type`	Tree type to include. TYPE: `(gs, al, sawtimber, live)` DEFAULT: `'gs'`
`measure`	What to measure in the mortality estimation. TYPE: `(volume, sawlog, biomass, tpa, count, basal_area)` 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`
`as_rate`	If True, return mortality as a rate (mortality/live). TYPE: `bool` DEFAULT: `False`
`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`	Mortality estimates with columns: - MORT_ACRE: Annual mortality per acre - MORT_TOTAL: Total annual mortality (if totals=True) - MORT_ACRE_SE: Standard error of per-acre estimate (if variance=True) - MORT_TOTAL_SE: Standard error of total estimate (if variance=True) - Additional grouping columns if specified

See Also

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

Examples:

Basic volume mortality on forestland:

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

Mortality by species (tree count):

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

Notes

This function uses FIA's GRM tables which contain pre-calculated annual mortality values. The TPA_UNADJ fields are already annualized.

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

def mortality(
    db: Union[str, FIA],
    grp_by: Optional[Union[str, List[str]]] = None,
    by_species: bool = False,
    by_size_class: bool = False,
    land_type: str = "timber",
    tree_type: str = "gs",
    measure: str = "volume",
    tree_domain: Optional[str] = None,
    area_domain: Optional[str] = None,
    as_rate: bool = False,
    totals: bool = True,
    variance: bool = False,
    most_recent: bool = False,
) -> pl.DataFrame:
    """
    Estimate annual tree mortality from FIA data using GRM methodology.

    Uses TREE_GRM_COMPONENT and TREE_GRM_MIDPT tables to calculate
    annual mortality following FIA's Growth-Removal-Mortality approach.
    This is the correct FIA statistical methodology for mortality estimation.

    Parameters
    ----------
    db : Union[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.
    land_type : {'forest', 'timber'}, default 'timber'
        Land type to include in estimation.
    tree_type : {'gs', 'al', 'sawtimber', 'live'}, default 'gs'
        Tree type to include.
    measure : {'volume', 'sawlog', 'biomass', 'tpa', 'count', 'basal_area'}, default 'volume'
        What to measure in the mortality 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.
    as_rate : bool, default False
        If True, return mortality as a rate (mortality/live).
    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
        Mortality estimates with columns:
        - MORT_ACRE: Annual mortality per acre
        - MORT_TOTAL: Total annual mortality (if totals=True)
        - MORT_ACRE_SE: Standard error of per-acre estimate (if variance=True)
        - MORT_TOTAL_SE: Standard error of total estimate (if variance=True)
        - Additional grouping columns if specified

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

    Examples
    --------
    Basic volume mortality on forestland:

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

    Mortality by species (tree count):

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

    Notes
    -----
    This function uses FIA's GRM tables which contain pre-calculated annual
    mortality values. The TPA_UNADJ fields are already annualized.
    """
    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")
    as_rate = validate_boolean(as_rate, "as_rate")
    totals = validate_boolean(totals, "totals")
    variance = validate_boolean(variance, "variance")
    most_recent = validate_boolean(most_recent, "most_recent")

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

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

Measurement Types¶

Measure	Description
`"volume"`	Net cubic-foot volume mortality
`"sawlog"`	Board-foot sawlog mortality
`"biomass"`	Above-ground biomass mortality
`"tpa"`	Trees per acre mortality
`"count"`	Tree count mortality
`"basal_area"`	Basal area mortality

Technical Notes¶

Mortality estimation uses:

TREE_GRM_COMPONENT table for mortality attributes
TREE_GRM_MIDPT table for annualized values
Trees with TPAMORT_UNADJ > 0 are mortality trees
Annual rates calculated using measurement interval

Examples¶

Total Mortality Volume¶

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

Mortality by Agent¶

result = pyfia.mortality(
    db,
    measure="volume",
    grp_by="AGENTCD"
)
# AGENTCD: 10=Insect, 20=Disease, 30=Fire, etc.
print(result)

Mortality by Species¶

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

Growing Stock Mortality on Timberland¶

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

Biomass Mortality¶

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