pyforestry.sweden.mortality package#

Submodules#

pyforestry.sweden.mortality.bengtsson module#

Bengtsson (1978) low-density stand mortality functions.

pyforestry.sweden.mortality.bengtsson.calibrate_bengtsson(*, context: MortalityContext, tree_probabilities: Sequence[float], period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, float], dict[str, float], dict[str, Any]][source]#

Calibrate tree probabilities to Bengtsson species mortality levels.

Reference:

Bengtsson, G. (1978). Beräkning av den naturliga avgången i avverkningsberäkningarna för 1973 års skogsutrednings slutbetänkande. In: Skog för framtid, SOU 1978:7, bilaga 6.

Predicts natural mortality in stands of lower (non-self-thinning) density; in Elfving’s (2010) established-stand mortality model this is combined as a density-weighted average with Söderberg (1986) self-thinning mortality (see Elfving 2010, “Growth modelling in the Heureka system”).

Parameters:

context – Unified mortality context.
tree_probabilities – Base tree probabilities before calibration.
period_years – Prediction period in years.
default_stems_per_tree – Fallback represented stems per tree record.

Returns:

A tuple with calibrated probabilities, target species fractions, correction factors, and diagnostics.

pyforestry.sweden.mortality.elfving_2013 module#

Elfving (2013) single-tree mortality equations for Sweden.

class pyforestry.sweden.mortality.elfving_2013.Elfving2013MortalityModel[source]#

Bases: object

Thin class facade for Elfving (2013) mortality equations.

predict_probabilities(*, context: MortalityContext, period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, Any]][source]#

Predict tree mortality probabilities using Elfving equations.

default_stems_per_tree is accepted for a uniform mortality-model interface but is unused: the Elfving (2013) equations are per-tree and need no represented-stem count.

pyforestry.sweden.mortality.elfving_2013.elfving_2013_probabilities(*, context: MortalityContext, period_years: float = 5.0) → tuple[list[float], dict[str, Any]][source]#

Calculate Elfving (2013) tree mortality probabilities.

Reference:: Elfving, B. (2013). Single-tree mortality functions for the Swedish forest, PM 2013-05-02 (unpublished working memo).

Parameters:

context – Unified mortality context.
period_years – Prediction period in years.

Returns:

A tuple with per-tree probabilities and diagnostics.

pyforestry.sweden.mortality.fridman_stahl_2001 module#

Fridman & Ståhl (2001) mortality equations for Swedish forests.

class pyforestry.sweden.mortality.fridman_stahl_2001.FridmanStahl2001Model(implementation_type: MortalityRealizationMode = MortalityRealizationMode.DETERMINISTIC, stochastic_seed: int | None = None, rng: Random | None = None)[source]#

Bases: object

Thin class facade for Fridman-Stahl mortality equations.

predict_probabilities(*, context: MortalityContext, period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, Any]][source]#: Predict tree mortality probabilities using Fridman-Stahl equations.

pyforestry.sweden.mortality.fridman_stahl_2001.fridman_stahl_2001_probabilities(*, context: MortalityContext, implementation_type: MortalityRealizationMode = MortalityRealizationMode.DETERMINISTIC, period_years: float = 5.0, rng: Random | None = None, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, Any]][source]#

Calculate Fridman-Stahl tree mortality probabilities.

Reference:: Fridman, J. & Ståhl, G. (2001). A three-step approach for modelling tree mortality in Swedish forests. Scandinavian Journal of Forest Research 16(5):455-466. Step I predicts the probability of mortality on a plot, step II the proportion of basal area that dies (ln(PBA)=a+b*X), and step III distributes mortality among trees. Coefficients reproduce the paper’s Tables 6-13.

Parameters:

context – Unified mortality context.
implementation_type – Deterministic or stochastic routing.
period_years – Prediction period in years.
rng – Optional random generator for stochastic mode.
default_stems_per_tree – Fallback represented stems per tree record.

Returns:

A tuple with per-tree probabilities and diagnostics.

Raises:

ValueError – If logarithm/division domains are invalid.

pyforestry.sweden.mortality.naslund_1986 module#

Naslund (1986) damage and mortality functions for young stands.

class pyforestry.sweden.mortality.naslund_1986.AspenCausalAgent(*values)[source]#

Bases: Enum

Causal agent ordering for aspen damage.

MOOSE = 0#

REMAINDER = 1#

class pyforestry.sweden.mortality.naslund_1986.BirchCausalAgent(*values)[source]#

Bases: Enum

Causal agent ordering for birch damage.

MOOSE = 0#

REMAINDER = 1#

class pyforestry.sweden.mortality.naslund_1986.ContortaCausalAgent(*values)[source]#

Bases: Enum

Causal agent ordering for contorta damage.

MOOSE = 0#

REMAINDER = 2#

VOLE = 1#

class pyforestry.sweden.mortality.naslund_1986.DamageDegree(*values)[source]#

Bases: Enum

Damage severity classes.

DEAD = 2#

MINOR = 0#

SEVERE = 1#

class pyforestry.sweden.mortality.naslund_1986.Naslund1986DamageModel[source]#

Bases: object

Deterministic damage proportions and severity for young stands.

static damage_degree(*, species_group: SaplingSpeciesGroup, causal_agent: int, height_m: float, moose_damage_prop: float | None = None) → list[float][source]#

Step 4: Damage degree probabilities (minor, severe, dead).

Parameters:

species_group (SaplingSpeciesGroup) – Species group.
causal_agent (int) – Causal agent enum value.
height_m (float) – Tree height (m).
moose_damage_prop (float | None) – Moose damage proportion. Required for pine/birch when causal_agent is moose.

Returns:

Probabilities for [minor, severe, dead].

Return type:

list[float]

static damage_proportions(*, stems: dict[SaplingSpeciesGroup, float], mean_heights: dict[SaplingSpeciesGroup, float], site_index_pine_m: float, site_index_spruce_m: float, latitude_deg: float, altitude_m: float, moose_factor: float = 1.0, vole_factor: float = 1.0, snow_break_factor: float = 1.0, whip_factor: float = 1.0, frost_factor: float = 1.0, snow_blight_factor: float = 1.0, other_factor: float = 1.0) → dict[SaplingSpeciesGroup, float][source]#

Compute proportion of damaged stems per species group.

Parameters:

stems (dict[SaplingSpeciesGroup, float]) – Stems per species group (per ha).
mean_heights (dict[SaplingSpeciesGroup, float]) – Mean height per group (m).
site_index_pine_m (float) – Pine site index (m).
site_index_spruce_m (float) – Spruce site index (m).
latitude_deg (float) – Latitude (degrees).
altitude_m (float) – Altitude (m).
moose_factor (float) – Adjustment factor for moose damage.
vole_factor (float) – Adjustment factor for vole damage.
snow_break_factor (float) – Adjustment factor for snow break damage.
whip_factor (float) – Adjustment factor for whipping damage.
frost_factor (float) – Adjustment factor for frost damage.
snow_blight_factor (float) – Adjustment factor for snow blight damage.
other_factor (float) – Adjustment factor for other agents.

Returns:

Proportion damaged per species group.

Return type:

dict[SaplingSpeciesGroup, float]

static damage_proportions_from_trees(trees: Sequence[Tree], *, site_index_pine_m: float, site_index_spruce_m: float, latitude_deg: float, altitude_m: float, expansion_factor: float = 1.0, moose_factor: float = 1.0, vole_factor: float = 1.0, snow_break_factor: float = 1.0, whip_factor: float = 1.0, frost_factor: float = 1.0, snow_blight_factor: float = 1.0, other_factor: float = 1.0) → dict[SaplingSpeciesGroup, float][source]#

Compute damage proportions from a tree list.

Parameters:

trees (Sequence[Tree]) – Trees with height_m, weight_n and species set.
site_index_pine_m (float) – Pine site index (m).
site_index_spruce_m (float) – Spruce site index (m).
latitude_deg (float) – Latitude (degrees).
altitude_m (float) – Altitude (m).
expansion_factor (float) – Factor to convert tree weights to stems per ha.
moose_factor (float) – Adjustment factor for moose damage.
vole_factor (float) – Adjustment factor for vole damage.
snow_break_factor (float) – Adjustment factor for snow break damage.
whip_factor (float) – Adjustment factor for whipping damage.
frost_factor (float) – Adjustment factor for frost damage.
snow_blight_factor (float) – Adjustment factor for snow blight damage.
other_factor (float) – Adjustment factor for other agents.

Returns:

Proportion damaged per species group.

Return type:

dict[SaplingSpeciesGroup, float]

static moose_damage_prop_birch(*, mean_height_birch: float, prop_pine: float, prop_birch: float, stems_birch: float, moose_factor: float = 1.0) → float[source]#

Compute moose damage proportion for birch.

Parameters:

mean_height_birch (float) – Mean height of birch (m).
prop_pine (float) – Proportion pine/larch of total stems.
prop_birch (float) – Proportion birch of total stems.
stems_birch (float) – Birch stems per ha.
moose_factor (float) – Adjustment factor for moose damage.

Returns:

Moose damage proportion for birch.

Return type:

float

static moose_damage_prop_contorta(*, mean_height_contorta: float, stems_contorta: float, latitude_deg: float, moose_factor: float = 1.0) → float[source]#

Compute moose damage proportion for contorta.

Parameters:

mean_height_contorta (float) – Mean height of contorta (m).
stems_contorta (float) – Contorta stems per ha.
latitude_deg (float) – Latitude (degrees).
moose_factor (float) – Adjustment factor for moose damage.

Returns:

Moose damage proportion for contorta.

Return type:

float

static moose_damage_prop_pine(*, mean_height_pine_larch: float, prop_pine: float, stems_pine_larch: float, total_stems: float, mean_height_leaf: float, total_mean_height: float, site_index_pine_m: float, climate_index: float, moose_factor: float = 1.0) → float[source]#

Compute moose damage proportion for pine/larch.

Parameters:

mean_height_pine_larch (float) – Mean height for pine + larch (m).
prop_pine (float) – Proportion pine/larch of total stems.
stems_pine_larch (float) – Pine + larch stems per ha.
total_stems (float) – Total stems per ha.
mean_height_leaf (float) – Mean height of broadleaves (m).
total_mean_height (float) – Stand mean height (m).
site_index_pine_m (float) – Pine site index (m).
climate_index (float) – Climate index (50 * latitude + altitude).
moose_factor (float) – Adjustment factor for moose damage.

Returns:

Moose damage proportion for pine/larch.

Return type:

float

static risk_of_damage(*, species_group: SaplingSpeciesGroup, height_m: float, moose_factor: float = 1.0, vole_factor: float = 1.0, snow_break_factor: float = 1.0, whip_factor: float = 1.0, frost_factor: float = 1.0, snow_blight_factor: float = 1.0, other_factor: float = 1.0) → list[float][source]#

Step 2: Risk of damage per causal agent for a tree.

Parameters:

species_group (SaplingSpeciesGroup) – Species group.
height_m (float) – Tree height (m).
moose_factor (float) – Adjustment factor for moose damage.
vole_factor (float) – Adjustment factor for vole damage.
snow_break_factor (float) – Adjustment factor for snow break damage.
whip_factor (float) – Adjustment factor for whipping damage.
frost_factor (float) – Adjustment factor for frost damage.
snow_blight_factor (float) – Adjustment factor for snow blight damage.
other_factor (float) – Adjustment factor for other agents.

Returns:

Risk values per causal agent (order per Enum).

Return type:

list[float]

class pyforestry.sweden.mortality.naslund_1986.PineCausalAgent(*values)[source]#

Bases: Enum

Causal agent ordering for pine/larch damage.

MOOSE = 0#

REMAINDER = 4#

SNOW = 3#

SNOWBLIGHT = 2#

WHIP = 1#

class pyforestry.sweden.mortality.naslund_1986.SaplingSpeciesGroup(*values)[source]#

Bases: Enum

Species groups used in the Naslund (1986) damage model.

ASPEN = 'aspen'#

BIRCH = 'birch'#

CONTORTA = 'contorta'#

LARCH = 'larch'#

OTHER_BROADLEAF = 'other_broadleaf'#

PINE = 'pine'#

SPRUCE = 'spruce'#

class pyforestry.sweden.mortality.naslund_1986.SpruceCausalAgent(*values)[source]#

Bases: Enum

Causal agent ordering for spruce damage.

FROST = 1#

REMAINDER = 2#

WHIP = 0#

pyforestry.sweden.mortality.retained_trees module#

Retained-tree mortality overrides after final felling.

pyforestry.sweden.mortality.retained_trees.retained_tree_mortality_by_species(*, years_since_final_felling: float | None, mortality_year1_5: Mapping[TreeName | str, float], mortality_year6_10: Mapping[TreeName | str, float]) → dict[str, float] | None[source]#

Return retained-tree mortality by species for applicable year windows.

Source:: None. This is bookkeeping, not a model: both mortality levels are supplied by the caller and the function only selects the window that applies to the elapsed time and clamps the result. Whatever science the rates embody belongs to whoever produced them.

Parameters:

years_since_final_felling – Years elapsed since final felling.
mortality_year1_5 – Species mortality mapping for years 0-5.
mortality_year6_10 – Species mortality mapping for years 5-10.

Returns:

Species mortality mapping keyed by canonical species string, or None when retained-tree override is not applicable.

pyforestry.sweden.mortality.root_rot_thor_stahl_stenlid_2005 module#

Root-rot risk model by Thor, Stahl, and Stenlid (2005).

pyforestry.sweden.mortality.root_rot_thor_stahl_stenlid_2005.root_rot_risk_thor_stahl_stenlid_2005(*, context: MortalityContext, default_stems_per_tree: float = 1.0) → RootRotRiskResult[source]#

Calculate root-rot risk for each tree and stand totals.

Reference:: Thor, M., Ståhl, G. & Stenlid, J. (2005). Modelling root rot incidence in Sweden using tree, site and stand variables. Scandinavian Journal of Forest Research 20:165-176.

Parameters:

context – Unified mortality context.
default_stems_per_tree – Fallback represented stems per tree record.

Returns:

RootRotRiskResult with tree probabilities and stand totals.

pyforestry.sweden.mortality.siipilehto_2020 module#

Siipilehto et al. (2020) stand-level mortality equations for Sweden.

class pyforestry.sweden.mortality.siipilehto_2020.Siipilehto2020MortalityModel[source]#

Bases: object

Thin class facade for Siipilehto et al. (2020) mortality equations.

predict_probabilities(*, context: MortalityContext, period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, Any]][source]#: Predict tree mortality probabilities using Siipilehto (2020) equations.

pyforestry.sweden.mortality.siipilehto_2020.siipilehto_2020_probabilities(*, context: MortalityContext, period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, Any]][source]#

Calculate Siipilehto et al. (2020) stand-level mortality probabilities.

Reference:

Siipilehto, J., Allen, M., Nilsson, U., Brunner, A., Huuskonen, S., Haikarainen, S., Subramanian, N., Antón-Fernández, C., Holmström, E., Andreassen, K. & Hynynen, J. (2020). Stand-level mortality models for Nordic boreal forests. Silva Fennica 54(5), article id 10414. https://doi.org/10.14214/sf.10414

The model is stand-level and two-step: Model 1 (Table 5) predicts the probability of no mortality (survival) on a plot, and Model 2 (Table 6) the proportion of basal area in surviving trees. Mortality is then distributed among individual trees using the step-III per-tree functions and correction factor of Fridman & Ståhl (2001), as the paper directs. Historically labelled “SNS”, after the SNS (Nordic Forest Research) project that funded it.

Parameters:

context – Unified mortality context.
period_years – Prediction period in years.
default_stems_per_tree – Fallback represented stems per tree record.

Returns:

A tuple with per-tree probabilities and diagnostics.

pyforestry.sweden.mortality.soderberg_1986 module#

Soderberg (1986) self-thinning calibration for mortality.

pyforestry.sweden.mortality.soderberg_1986.calibrate_soderberg(*, context: MortalityContext, tree_probabilities: Sequence[float], site_index_adjustment_factor: float = 1.0, period_years: float = 5.0, default_stems_per_tree: float = 1.0) → tuple[list[float], dict[str, float], dict[str, float], dict[str, Any]][source]#

Calibrate tree probabilities to Soderberg self-thinning response.

Reference:: Söderberg, U. (1986). Funktioner för skogliga produktionsprognoser: tillväxt och formhöjd för enskilda träd av inhemska trädslag i Sverige. Report 14, Section of Forest Mensuration and Management, Swedish University of Agricultural Sciences (SLU), Umeå.

Parameters:

context – Unified mortality context.
tree_probabilities – Base tree probabilities before calibration.
site_index_adjustment_factor – Multiplier applied to spruce SI branch.
period_years – Prediction period in years.
default_stems_per_tree – Fallback represented stems per tree record.

Returns:

A tuple with calibrated probabilities, adjusted species fractions, correction factors, and diagnostics.

pyforestry.sweden.mortality.types module#

Type definitions for Swedish mortality models.

This module contains explicit, unit-bearing context containers and configuration objects used by mortality equations and orchestration engines.

class pyforestry.sweden.mortality.types.MortalityConfig(implementation_type: MortalityRealizationMode = MortalityRealizationMode.DETERMINISTIC, tree_model: MortalityTreeModel = MortalityTreeModel.FRIDMAN_STAHL_2001, calibrate_bengtsson: bool = True, calibrate_soderberg: bool = True, site_index_adjustment_factor: float = 1.0, global_adjustment_factor: float = 1.0, species_adjustment_factors: Mapping[TreeName | str, float] | None = None, use_retained_tree_override: bool = True, retained_tree_mortality_years_1_to_5: Mapping[TreeName | str, float] | None = None, retained_tree_mortality_years_6_to_10: Mapping[TreeName | str, float] | None = None, period_years: float = 5.0, stochastic_seed: int | None = None, default_stems_per_tree: float = 1.0)[source]#

Bases: object

Configuration for mortality orchestration engines.

class pyforestry.sweden.mortality.types.MortalityContext(trees: list[MortalityTreeRecord], stand: MortalityStandConditions, site: MortalitySiteConditions, history: MortalityHistoryConditions | None = None)[source]#

Bases: object

Canonical unified mortality context (pure inputs; the engine owns config).

class pyforestry.sweden.mortality.types.MortalityHistoryConditions(thinned_within_0_2_years: bool = False, thinned_within_0_5_years: bool = False, thinned_within_2_20_years: bool = False, thinning_intensity_fraction: float = 0.0, thinning_form_q: float = 0.0, years_since_final_felling: float | None = None)[source]#

Bases: object

Historical disturbance/treatment conditions for mortality routing.

class pyforestry.sweden.mortality.types.MortalityRealizationMode(*values)[source]#

Bases: Enum

Implementation mode for mortality assignment.

DETERMINISTIC = 'deterministic'#

STOCHASTIC = 'stochastic'#

class pyforestry.sweden.mortality.types.MortalityResult(tree_probabilities: list[float], tree_realized_mortality: list[float], species_mortality_fraction: dict[str, float], species_mortality_fraction_before_calibration: dict[str, float], diagnostics: dict[str, ~typing.Any] = <factory>)[source]#

Bases: object

Result container for mortality orchestration runs.

class pyforestry.sweden.mortality.types.MortalitySiteConditions(latitude_deg: float, altitude_m: float, site_index_m: float | SiteIndexValue, soil_moisture: SwedenSoilMoisture | int, peat: bool = False, temperature_sum: float = 0.0, part_of_sweden: str = 'middle', field_layer: SwedenFieldLayer | None = None, vegetation_type_code: int | None = None, texture_is_sand_medium: bool = False, is_rich: bool | None = None, is_poor: bool | None = None)[source]#

Bases: object

Site-level mortality input conditions.

Variables:

latitude_deg (float) – Latitude in decimal degrees.
altitude_m (float) – Altitude in meters above sea level.
site_index_m (float | pyforestry.base.helpers.primitives.siteindex_value.SiteIndexValue) – Site index in meters (H100 scale where applicable). Can be provided as a numeric value or as SiteIndexValue.
soil_moisture (pyforestry.sweden.site.enums.SwedenSoilMoisture | int) – Soil moisture class (Sweden.SoilMoistureEnum or code).
peat (bool) – Whether peat soil is present.
temperature_sum (float) – Temperature sum in degree-days.
part_of_sweden (str) – Region label (north, middle, south).
field_layer (pyforestry.sweden.site.enums.SwedenFieldLayer | None) – Optional field-layer enum used for vegetation coding.
vegetation_type_code (int | None) – Optional direct vegetation type code.
texture_is_sand_medium (bool) – True for sandy-silty till indicator.
is_rich (bool | None) – Optional rich-site indicator for Nystrom-based routing.
is_poor (bool | None) – Optional poor-site indicator for Nystrom-based routing.

class pyforestry.sweden.mortality.types.MortalityStandConditions(plot_area_m2: float, total_basal_area_m2_ha: float | None = None, total_stems_per_ha: float | None = None, mean_diameter_arithmetic_cm: float | None = None, mean_diameter_dg_cm: float | None = None, mean_age_total_years: float | None = None, mean_age_excl_overstorey_years: float | None = None, mean_age_overstorey_years: float = 0.0, species_basal_area_m2_ha: Mapping[TreeName | str, float] | None = None, slope_percent: float = 0.0, aspect_degrees: float | None = None)[source]#

Bases: object

Stand-level mortality input conditions.

Variables:

plot_area_m2 (float) – Plot area in square meters.
total_basal_area_m2_ha (float | None) – Total stand basal area in m2/ha.
total_stems_per_ha (float | None) – Total stems in stems/ha.
mean_diameter_arithmetic_cm (float | None) – Arithmetic mean diameter in centimeters.
mean_diameter_dg_cm (float | None) – Basal-area weighted mean diameter in centimeters.
mean_age_total_years (float | None) – Mean total age in years.
mean_age_excl_overstorey_years (float | None) – Mean total age excluding overstorey.
mean_age_overstorey_years (float) – Mean total age overstorey trees.
species_basal_area_m2_ha (Mapping[pyforestry.base.helpers.tree_species.TreeName | str, float] | None) – Optional species-level basal area mapping.
slope_percent (float) – Terrain slope in percent.
aspect_degrees (float | None) – Terrain aspect in degrees.

class pyforestry.sweden.mortality.types.MortalityTreeModel(*values)[source]#

Bases: Enum

Supported single-tree mortality model families.

ELFVING_2013 = 'elfving_2013'#

FRIDMAN_STAHL_2001 = 'fridman_stahl_2001'#

SIIPILEHTO_2020 = 'siipilehto_2020'#

class pyforestry.sweden.mortality.types.MortalityTreeRecord(species: TreeName | str, diameter_cm: float, bal: float = 0.0, stems_per_tree: float | None = None, basal_area_cm2: float | None = None, age_total_years: float | None = None, is_overstorey: bool = False, volume_m3: float | None = None, metadata: dict[str, ~typing.Any]=<factory>)[source]#

Bases: object

Tree-level mortality input record.

Variables:

species (pyforestry.base.helpers.tree_species.TreeName | str) – Tree species.
diameter_cm (float) – Diameter at breast height in centimeters.
bal (float) – Basal area larger trees (BAL) for the tree, unitless.
stems_per_tree (float | None) – Number of represented stems. Used for stochastic assignment and basal-area weighting.
basal_area_cm2 (float | None) – Optional tree basal area in square centimeters. When omitted, it is derived from diameter_cm.
age_total_years (float | None) – Optional total age in years for tree-level equations.
is_overstorey (bool) – Whether the tree is classified as overstorey.
volume_m3 (float | None) – Optional per-tree volume in cubic meters.
metadata (dict[str, Any]) – Optional extra attributes used by adapters.

class pyforestry.sweden.mortality.types.RootRotRiskResult(tree_risk_probabilities: list[float], stems_with_root_rot: float, basal_area_with_root_rot_m2_ha: float, volume_with_root_rot_m3_ha: float)[source]#

Bases: object

Root-rot risk outputs for the Thor-Stahl-Stenlid (2005) model.

Module contents#

Swedish mortality equations, calibrations, and orchestration.