> ## Documentation Index > Fetch the complete documentation index at: https://pyfia.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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` ```python theme={null} 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 type to include. * `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, calculate and include variance and standard error estimates. * `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 (if variance=True) * MORT\_TOTAL\_SE: Standard error of total estimate (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` ```python theme={null} component_type(self) -> Literal['growth', 'mortality', 'removals'] ``` Return 'mortality' as the GRM component type. #### `get_component_filter` ```python theme={null} get_component_filter(self) -> pl.Expr | None ``` Filter to mortality components only. #### `load_data` ```python theme={null} load_data(self) -> pl.LazyFrame | None ``` Load GRM data for mortality estimation. #### `apply_filters` ```python theme={null} apply_filters(self, data: pl.LazyFrame) -> pl.LazyFrame ``` Apply mortality-specific filters. #### `calculate_values` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} format_output(self, results: pl.DataFrame) -> pl.DataFrame ``` Format mortality estimation output.