mortality

pyfia.estimation.estimators.mortality

Mortality estimation for FIA data using GRM tables.

Implements FIA’s Growth-Removal-Mortality methodology for calculating annual tree mortality using TREE_GRM_COMPONENT and TREE_GRM_MIDPT tables.

Functions

mortality

mortality(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 = 'timber', tree_type: str = 'gs', measure: str = 'volume', tree_domain: str | None = None, area_domain: str | None = 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.

Args:

• db: Database connection or path to FIA database.

• grp_by: Column name(s) to group results by.

• by_species: If True, group results by species code (SPCD).

• by_size_class: If True, group results by diameter size classes.

• 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 (Pre-merchantable, Pulpwood, Chip-n-Saw, Sawtimber)

• land_type: Land type to include in estimation.

• tree_type: Tree population to include (GRM tables):

• ‘gs’: growing stock

• ‘al’ or ‘live’: all live trees at least 1 inch d.b.h., saplings on the microplot included (EVALIDator’s “trees at least 1 inch”)

• ‘sl’ or ‘sawtimber’: sawtimber-size trees

• measure: What to measure in the mortality estimation.

• tree_domain: SQL-like filter expression for tree-level filtering.

• area_domain: SQL-like filter expression for area/condition-level filtering.

• as_rate: If True, return mortality as a rate (mortality/live).

• totals: If True, include population-level total estimates.

• variance: If True, also return variance columns (*_VARIANCE) alongside the standard errors (*_SE, always returned). Variance = SE squared.

• most_recent: If True, automatically filter to the most recent evaluation.

Returns:

• 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
• MORT_TOTAL_SE: Standard error of total estimate (if totals=True)
• MORT_ACRE_VARIANCE, MORT_TOTAL_VARIANCE: Variance of the estimates, equal to the matching _SE squared (if variance=True)
• Additional grouping columns if specified

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=“tpa”) Pre-merchantable tree mortality (trees < 5” DBH): >>> results = mortality( … db, … tree_type=“live”, # Include all live trees, not just growing stock … by_size_class=True, … size_class_type=“market”, # Returns Pre-merchantable, Pulpwood, etc. … measure=“tpa”, # TPA recommended for small trees (no volume calculated) … )

Filter to pre-merchantable only:

premerch = results.filter(pl.col(“SIZE_CLASS”) == “Pre-merchantable”)

Classes

MortalityEstimator

Mortality estimator for FIA data using GRM methodology.

Estimates annual tree mortality in terms of volume, biomass, or trees per acre using the TREE_GRM_COMPONENT and TREE_GRM_MIDPT tables.

Methods:

component_type

component_type(self) -> Literal['growth', 'mortality', 'removals']

Return ‘mortality’ as the GRM component type.

get_component_filter

get_component_filter(self) -> pl.Expr | None

Filter to mortality components only.

load_data

load_data(self) -> pl.LazyFrame | None

Load GRM data for mortality estimation.

apply_filters

apply_filters(self, data: pl.LazyFrame) -> pl.LazyFrame

Apply mortality-specific filters.

calculate_values

calculate_values(self, data: pl.LazyFrame) -> pl.LazyFrame

Calculate mortality values per acre.

TPA_UNADJ is already annualized, so no remeasurement period adjustment needed.

aggregate_results

aggregate_results(self, data: pl.LazyFrame | None) -> AggregationResult

Aggregate mortality with two-stage aggregation.

Returns:

• Bundle containing results, plot_tree_data, and group_cols for explicit variance calculation.

calculate_variance

calculate_variance(self, agg_result: AggregationResult) -> pl.DataFrame

Calculate variance for mortality estimates using ratio-of-means formula.

Implements Bechtold & Patterson (2005) stratified variance calculation. MORT_RATE uses the same variance as MORT_ACRE since they represent the same per-acre estimate (MORT_RATE = mortality per acre, not mortality/growing_stock).

Args:

• agg_result: Bundle containing results, plot_tree_data, and group_cols from aggregate_results().

Returns:

• Results with variance columns added.

format_output

format_output(self, results: pl.DataFrame) -> pl.DataFrame

Format mortality estimation output.