pyforestry.sweden.ingrowth package#

Submodules#

pyforestry.sweden.ingrowth.wikberg_2004 module#

Wikberg (2004) ingrowth model for established stands.

Implements the 4-step ingrowth model for trees recruited into the >=4 cm dbh class over a 5-year period.

Source:: Wikberg, P-E. (2004). “Occurrence, morphology and growth of understory saplings in Swedish forests”, doctoral thesis, Acta Universitatis Agriculturae Sueciae, SLU, Umeå.

class pyforestry.sweden.ingrowth.wikberg_2004.CommonData(basal_area_capped_m2_ha: float, basal_area_capped_sqrt: float, inv_basal_area_capped_plus5: float, mean_age_excl_overstorey_capped_years: float, log_mean_age_excl_overstorey_capped_years: float, inv_mean_age_excl_overstorey_capped_plus5: float, temperature_sum_scaled: float, temperature_sum_scaled_squared: float, inv_temperature_sum_scaled_minus3: float, altitude_scaled: float, log_altitude_scaled: float, altitude_scaled_squared: float, latitude_scaled: float, latitude_scaled_squared: float, latitude_over_60: bool, spruce_small_tree_probability: float, pine_presence_10cm: int, spruce_presence_10cm: int, birch_presence_10cm: int, other_broadleaf_presence_10cm: int, oak_presence_10cm: int, beech_presence_10cm: int, southern_broadleaf_presence_10cm: int, thinning_0_5_years: int, thinning_6_10_years: int, visibility_cleaning: int, gotland: int, soil_moisture_code: int, ground_water_indicator: int, soil_texture_code_sqrt: float, poor_vegetation: int, shrubs: int, poor_shrubs: int, herb: int, herb_without_shrubs: int, herb_with_shrubs: int, herb_without_shrubs_dry: int, no_vegetation: int, broadleaved_grass: int, thinleaved_grass: int, sedge: int, lichen: int, peat: int, bog_moss: int, swamp_moss: int, field: int, edge: int, road: int, rich_vegetation: int, site_index_m: float, spruce_basal_area_share: float, mesic_indicator: int)[source]#

Bases: object

Resolved and transformed stand/site variables for ingrowth calculations.

Variables:

basal_area_capped_m2_ha (float) – Basal area capped at 100 (m2/ha).
basal_area_capped_sqrt (float) – Square root of capped basal area.
inv_basal_area_capped_plus5 (float) – 1 / (5 + capped basal area).
mean_age_excl_overstorey_capped_years (float) – Mean age excluding overstorey capped at 160 (years).
log_mean_age_excl_overstorey_capped_years (float) – Natural log of capped mean age.
inv_mean_age_excl_overstorey_capped_plus5 (float) – 1 / (5 + capped mean age).
temperature_sum_scaled (float) – Temperature sum scaled by 0.01.
temperature_sum_scaled_squared (float) – Scaled temperature sum squared.
inv_temperature_sum_scaled_minus3 (float) – 1 / (temperature_sum_scaled - 3).
altitude_scaled (float) – Altitude scaled by 0.01.
log_altitude_scaled (float) – Natural log of altitude_scaled.
altitude_scaled_squared (float) – altitude_scaled squared.
latitude_scaled (float) – Latitude scaled by 10.
latitude_scaled_squared (float) – latitude_scaled squared scaled by 0.01.
latitude_over_60 (bool) – True if latitude > 60 degrees.
spruce_small_tree_probability (float) – Spruce small-tree probability (seed for pine and birch).
pine_presence_10cm (int) – Pine presence indicator for dbh >= 10 cm (0/1).
spruce_presence_10cm (int) – Spruce presence indicator for dbh >= 10 cm (0/1).
birch_presence_10cm (int) – Birch presence indicator for dbh >= 10 cm (0/1).
other_broadleaf_presence_10cm (int) – Other broadleaf indicator for dbh >= 10 cm (0/1).
oak_presence_10cm (int) – Oak presence indicator for dbh >= 10 cm (0/1).
beech_presence_10cm (int) – Beech presence indicator for dbh >= 10 cm (0/1).
southern_broadleaf_presence_10cm (int) – Southern broadleaf indicator for dbh >= 10 cm (0/1).
thinning_0_5_years (int) – Thinning indicator for years 0-5 (1 if thinned).
thinning_6_10_years (int) – Thinning indicator for years 6-10 (1 if thinned).
visibility_cleaning (int) – Visibility cleaning indicator (0/1).
gotland (int) – Gotland indicator (0/1).
soil_moisture_code (int) – Soil moisture code (1-4).
ground_water_indicator (int) – Ground-water indicator (0 if seldom/never, else 1).
soil_texture_code_sqrt (float) – Square root of soil texture code.
poor_vegetation (int) – Poor-vegetation indicator (poor shrub/low productivity).
shrubs (int) – Shrub indicator.
poor_shrubs (int) – Poor shrubs indicator.
herb (int) – Herb indicator.
herb_without_shrubs (int) – Herb without shrubs indicator.
herb_with_shrubs (int) – Herb with shrubs indicator.
herb_without_shrubs_dry (int) – Herb without shrubs (dry) indicator.
no_vegetation (int) – No vegetation indicator.
broadleaved_grass (int) – Broadleaved grass indicator.
thinleaved_grass (int) – Thinleaved grass indicator.
sedge (int) – Sedge indicator.
lichen (int) – Lichen indicator.
peat (int) – Peat indicator (0/1).
bog_moss (int) – Bog moss indicator (0/1).
swamp_moss (int) – Swamp moss indicator (0/1).
field (int) – Field position indicator (0/1).
edge (int) – Edge position indicator (0/1).
road (int) – Road position indicator (0/1).
rich_vegetation (int) – Rich vegetation indicator.
site_index_m (float) – Site index (m).
spruce_basal_area_share (float) – Spruce basal area share (0-1).
mesic_indicator (int) – Mesic soil indicator (0/1).

class pyforestry.sweden.ingrowth.wikberg_2004.IngrowthResult(probability_small_trees: dict[IngrowthSpeciesGroup, float], number_small_trees: dict[IngrowthSpeciesGroup, float], number_ingrowth_trees: dict[IngrowthSpeciesGroup, float], mean_diameter_cm: dict[IngrowthSpeciesGroup, float], ingrown_trees: list[Tree])[source]#

Bases: object

Container for ingrowth outputs (per ha) and generated trees.

Variables:

probability_small_trees (dict[IngrowthSpeciesGroup, float]) – Probability of small trees per group.
number_small_trees (dict[IngrowthSpeciesGroup, float]) – Expected number of small trees per ha.
number_ingrowth_trees (dict[IngrowthSpeciesGroup, float]) – Expected number of ingrown trees per ha.
mean_diameter_cm (dict[IngrowthSpeciesGroup, float]) – Mean diameter (cm) of ingrown trees.
ingrown_trees (list[Tree]) – Representative ingrown trees with per-ha weights.

class pyforestry.sweden.ingrowth.wikberg_2004.IngrowthSpeciesGroup(*values)[source]#

Bases: Enum

Species groups used in the Wikberg (2004) ingrowth model.

BEECH = 'beech'#

BIRCH = 'birch'#

OAK = 'oak'#

OTHER_BROADLEAF = 'other_broadleaf'#

PINE = 'pine'#

SOUTHERN_BROADLEAF = 'southern_broadleaf'#

SPRUCE = 'spruce'#

class pyforestry.sweden.ingrowth.wikberg_2004.Wikberg2004Ingrowth(*, deterministic: bool = True, use_initial_saplings: bool = False, min_mean_age_invoke: float = 50.0, ingrowth_species: Sequence[IngrowthSpeciesGroup] | None = None, rng: Random | None = None)[source]#

Bases: object

Predict ingrowth for established stands using Wikberg (2004).

Parameters:

deterministic (bool) – If True, return expected ingrowth (deterministic).
use_initial_saplings (bool) – Use sapling occurrence for period 0 step-1 probability.
min_mean_age_invoke (float) – Minimum mean age to invoke ingrowth (years).
ingrowth_species (Sequence[IngrowthSpeciesGroup] | None) – Species groups to include.
rng (random.Random | None) – RNG used when deterministic is False.

Example:

model = Wikberg2004Ingrowth(deterministic=True)
result = model.predict(
    stand=stand,
    site_index_m=26.0,
    mean_age_excl_overstorey_years=60.0,
    qmd_cm=12.0,
    temperature_sum_dd=1400.0,
    latitude_deg=58.0,
    altitude_m=100.0,
    soil_moisture=Sweden.SoilMoistureEnum.MESIC,
    soil_texture=Sweden.SoilTextureSediment.MEDIUM_SAND,
    soil_water=Sweden.SoilWater.SELDOM_NEVER,
    bottom_layer=Sweden.BottomLayer.FRESH_MOSS,
    field_layer=Sweden.FieldLayer.BILBERRY,
)

classmethod build_common_data(*, basal_area_m2_ha: float, mean_age_excl_overstorey_years: float, temperature_sum_dd: float, altitude_m: float, latitude_deg: float, soil_moisture: SwedenSoilMoisture, soil_texture: SwedenSoilTextureTill | SwedenSoilTextureSediment, soil_water: SwedenSoilWater, bottom_layer: SwedenBottomLayer, field_layer: SwedenFieldLayer, peat: bool, site_index_m: float, species_ba_m2_ha: Mapping[IngrowthSpeciesGroup, float], species_presence_10cm: Mapping[IngrowthSpeciesGroup, int], gotland: int = 0, thinning_0_5_years: int = 0, thinning_6_10_years: int = 0, visibility_cleaning: int = 0, field: int = 0, edge: int = 0, road: int = 0) → CommonData[source]#

Build common ingrowth variables from resolved inputs.

Parameters:

basal_area_m2_ha (float) – Basal area (m2/ha).
mean_age_excl_overstorey_years (float) – Mean age excluding overstorey.
temperature_sum_dd (float) – Temperature sum (degree-days > 5C).
altitude_m (float) – Altitude (m).
latitude_deg (float) – Latitude (degrees).
soil_moisture (Sweden.SoilMoistureEnum) – Soil moisture class.
soil_texture (Sweden.SoilTextureTill | Sweden.SoilTextureSediment) – Soil texture.
soil_water (Sweden.SoilWater) – Soil water class.
bottom_layer (Sweden.BottomLayer) – Bottom layer class.
field_layer (Sweden.FieldLayer) – Field layer vegetation class.
peat (bool) – Peat indicator.
site_index_m (float) – Site index (m). This should be the H100 site index for the stand’s main conifer species; use SiteIndexValue with predict if you want validation.
species_ba_m2_ha (Mapping[IngrowthSpeciesGroup, float]) – Basal area per group.
species_presence_10cm (Mapping[IngrowthSpeciesGroup, int]) – Presence indicators for dbh >= 10 cm (pine_presence_10cm, spruce_presence_10cm, birch_presence_10cm, other_broadleaf_presence_10cm, oak_presence_10cm, beech_presence_10cm, southern_broadleaf_presence_10cm).
gotland (int) – Gotland indicator (1 if county is Gotland, else 0).
thinning_0_5_years (int) – Thinning indicator for years 0-5 (1 if thinned).
thinning_6_10_years (int) – Thinning indicator for years 6-10 (1 if thinned).
visibility_cleaning (int) – Visibility cleaning indicator (0/1).
field (int) – Field position indicator (0/1).
edge (int) – Stand edge indicator (0/1).
road (int) – Road position indicator (0/1).

Returns:

Transformed variables used in the ingrowth model.

Return type:

CommonData

Raises:

ValueError – If transformed variables are undefined (e.g. Ts == 3 or alt <= 0).

predict(*, stand: Stand | None = None, site: SwedishSite | None = None, site_index_m: float | SiteIndexValue | None = None, basal_area_m2_ha: float | None = None, qmd_cm: float | QuadraticMeanDiameter | None = None, mean_age_excl_overstorey_years: float | None = None, temperature_sum_dd: float | None = None, latitude_deg: float | None = None, altitude_m: float | None = None, soil_moisture: SwedenSoilMoisture | None = None, soil_texture: SwedenSoilTextureTill | SwedenSoilTextureSediment | None = None, soil_water: SwedenSoilWater | None = None, bottom_layer: SwedenBottomLayer | None = None, field_layer: SwedenFieldLayer | None = None, peat: bool | None = None, gotland: int | None = None, species_ba_m2_ha: Mapping[IngrowthSpeciesGroup, float] | None = None, species_presence_10cm: Mapping[IngrowthSpeciesGroup, int] | None = None, sapling_occurrence: Mapping[IngrowthSpeciesGroup, float] | None = None, period_index: int = 0, ingrowth_species: Sequence[IngrowthSpeciesGroup] | None = None, thinning_0_5_years: int = 0, thinning_6_10_years: int = 0, visibility_cleaning: int = 0, field: int = 0, edge: int = 0, road: int = 0, plot_is_saplings: bool = False) → IngrowthResult[source]#

Compute per-ha ingrowth and return a generated tree list.

Parameters:

stand (Stand | None) – Optional stand used for basal area, QMD, and tree list. Tree diameters are read from Tree.diameter_cm (usually Diameter_cm).
site (SwedishSite | None) – Optional site used to populate missing site inputs.
site_index_m (float | SiteIndexValue | None) – Site index for the stand (m). Prefer SiteIndexValue (H100 from Hagglund 1970) for pine or spruce.
basal_area_m2_ha (float | None) – Basal area (m2/ha).
qmd_cm (float | QuadraticMeanDiameter | None) – Quadratic mean diameter (cm) used for gating.
mean_age_excl_overstorey_years (float | None) – Mean age excluding overstorey.
temperature_sum_dd (float | None) – Temperature sum (degree-days > 5C).
latitude_deg (float | None) – Latitude (degrees).
altitude_m (float | None) – Altitude (m).
soil_moisture (Sweden.SoilMoistureEnum | None) – Soil moisture class.
soil_texture (Sweden.SoilTextureTill | Sweden.SoilTextureSediment | None) – Soil texture.
soil_water (Sweden.SoilWater | None) – Soil water class.
bottom_layer (Sweden.BottomLayer | None) – Bottom layer class.
field_layer (Sweden.FieldLayer | None) – Field layer vegetation class.
peat (bool | None) – Peat indicator. If None, derived from soil_texture if possible.
gotland (int | None) – Gotland indicator (1 if county is Gotland, else 0).
species_ba_m2_ha (Mapping | None) – Basal area per ingrowth species group (m2/ha).
species_presence_10cm (Mapping | None) – Presence indicators for dbh >= 10 cm (pine_presence_10cm, spruce_presence_10cm, birch_presence_10cm, other_broadleaf_presence_10cm, oak_presence_10cm, beech_presence_10cm, southern_broadleaf_presence_10cm).
sapling_occurrence (Mapping | None) – Sapling occurrence indicators for dbh < 4 cm.
period_index (int) – Period index (0 for first period).
ingrowth_species (Sequence[IngrowthSpeciesGroup] | None) – Species groups to include.
thinning_0_5_years (int) – Thinning indicator for years 0-5 (1 if thinned).
thinning_6_10_years (int) – Thinning indicator for years 6-10 (1 if thinned).
visibility_cleaning (int) – Visibility cleaning indicator (0/1).
field (int) – Field position indicator (0/1).
edge (int) – Stand edge indicator (0/1).
road (int) – Road position indicator (0/1).
plot_is_saplings (bool) – Skip ingrowth if plot type is saplings.

Returns:

Per-ha metrics and a generated tree list.

Return type:

IngrowthResult

Raises:

ValueError – If required inputs are missing or invalid.

static to_plot_trees(result: IngrowthResult, plot_area_ha: float) → list[Tree][source]#

Scale per-ha ingrowth trees to a plot area.

Parameters:

result (IngrowthResult) – Per-ha ingrowth result.
plot_area_ha (float) – Plot area in hectares.

Returns:

Trees scaled to plot area.

Return type:

list[Tree]

pyforestry.sweden.ingrowth.wikberg_2004.build_common_data(*, basal_area_m2_ha: float, mean_age_excl_overstorey_years: float, temperature_sum_dd: float, altitude_m: float, latitude_deg: float, soil_moisture: SwedenSoilMoisture, soil_texture: SwedenSoilTextureTill | SwedenSoilTextureSediment, soil_water: SwedenSoilWater, bottom_layer: SwedenBottomLayer, field_layer: SwedenFieldLayer, peat: bool, site_index_m: float, species_ba_m2_ha: Mapping[IngrowthSpeciesGroup, float], species_presence_10cm: Mapping[IngrowthSpeciesGroup, int], gotland: int = 0, thinning_0_5_years: int = 0, thinning_6_10_years: int = 0, visibility_cleaning: int = 0, field: int = 0, edge: int = 0, road: int = 0) → CommonData[source]#

Build common ingrowth variables from resolved inputs.

Parameters:

basal_area_m2_ha (float) – Basal area (m2/ha).
mean_age_excl_overstorey_years (float) – Mean age excluding overstorey.
temperature_sum_dd (float) – Temperature sum (degree-days > 5C).
altitude_m (float) – Altitude (m).
latitude_deg (float) – Latitude (degrees).
soil_moisture (Sweden.SoilMoistureEnum) – Soil moisture class.
soil_texture (Sweden.SoilTextureTill | Sweden.SoilTextureSediment) – Soil texture.
soil_water (Sweden.SoilWater) – Soil water class.
bottom_layer (Sweden.BottomLayer) – Bottom layer class.
field_layer (Sweden.FieldLayer) – Field layer vegetation class.
peat (bool) – Peat indicator.
site_index_m (float) – Site index (m). This should be the H100 site index for the stand’s main conifer species; use SiteIndexValue with predict if you want validation.
species_ba_m2_ha (Mapping[IngrowthSpeciesGroup, float]) – Basal area per group.
species_presence_10cm (Mapping[IngrowthSpeciesGroup, int]) – Presence indicators for dbh >= 10 cm (pine_presence_10cm, spruce_presence_10cm, birch_presence_10cm, other_broadleaf_presence_10cm, oak_presence_10cm, beech_presence_10cm, southern_broadleaf_presence_10cm).
gotland (int) – Gotland indicator (1 if county is Gotland, else 0).
thinning_0_5_years (int) – Thinning indicator for years 0-5 (1 if thinned).
thinning_6_10_years (int) – Thinning indicator for years 6-10 (1 if thinned).
visibility_cleaning (int) – Visibility cleaning indicator (0/1).
field (int) – Field position indicator (0/1).
edge (int) – Stand edge indicator (0/1).
road (int) – Road position indicator (0/1).

Returns:

Transformed variables used in the ingrowth model.

Return type:

CommonData

Raises:

ValueError – If transformed variables are undefined (e.g. Ts == 3 or alt <= 0).

pyforestry.sweden.ingrowth.wikberg_2004.ingrowth_predict(*, stand: Stand | None = None, site: SwedishSite | None = None, site_index_m: float | SiteIndexValue | None = None, basal_area_m2_ha: float | None = None, qmd_cm: float | QuadraticMeanDiameter | None = None, mean_age_excl_overstorey_years: float | None = None, temperature_sum_dd: float | None = None, latitude_deg: float | None = None, altitude_m: float | None = None, soil_moisture: SwedenSoilMoisture | None = None, soil_texture: SwedenSoilTextureTill | SwedenSoilTextureSediment | None = None, soil_water: SwedenSoilWater | None = None, bottom_layer: SwedenBottomLayer | None = None, field_layer: SwedenFieldLayer | None = None, peat: bool | None = None, gotland: int | None = None, species_ba_m2_ha: Mapping[IngrowthSpeciesGroup, float] | None = None, species_presence_10cm: Mapping[IngrowthSpeciesGroup, int] | None = None, sapling_occurrence: Mapping[IngrowthSpeciesGroup, float] | None = None, deterministic: bool = True, rng: Random | None = None, use_initial_saplings: bool = False, period_index: int = 0, min_mean_age_invoke: float = 50.0, ingrowth_species: Sequence[IngrowthSpeciesGroup] | None = None, thinning_0_5_years: int = 0, thinning_6_10_years: int = 0, visibility_cleaning: int = 0, field: int = 0, edge: int = 0, road: int = 0, plot_is_saplings: bool = False) → IngrowthResult[source]#

Convenience wrapper around Wikberg2004Ingrowth.

Parameters:

stand (Stand | None) – Optional stand used for basal area, QMD, and tree list. Tree diameters are read from Tree.diameter_cm (usually Diameter_cm).
site (SwedishSite | None) – Optional site used to populate missing site inputs.
site_index_m (float | SiteIndexValue | None) – Site index for the stand (m). Prefer SiteIndexValue (H100 from Hagglund 1970) for pine or spruce.
basal_area_m2_ha (float | None) – Basal area (m2/ha).
qmd_cm (float | QuadraticMeanDiameter | None) – Quadratic mean diameter (cm) used for gating.
mean_age_excl_overstorey_years (float | None) – Mean age excluding overstorey.
temperature_sum_dd (float | None) – Temperature sum (degree-days > 5C).
latitude_deg (float | None) – Latitude (degrees).
altitude_m (float | None) – Altitude (m).
soil_moisture (Sweden.SoilMoistureEnum | None) – Soil moisture class.
soil_texture (Sweden.SoilTextureTill | Sweden.SoilTextureSediment | None) – Soil texture.
soil_water (Sweden.SoilWater | None) – Soil water class.
bottom_layer (Sweden.BottomLayer | None) – Bottom layer class.
field_layer (Sweden.FieldLayer | None) – Field layer vegetation class.
peat (bool | None) – Peat indicator. If None, derived from soil_texture if possible.
gotland (int | None) – Gotland indicator (1 if county is Gotland, else 0).
species_ba_m2_ha (Mapping | None) – Basal area per ingrowth species group (m2/ha).
species_presence_10cm (Mapping | None) – Presence indicators for dbh >= 10 cm (pine_presence_10cm, spruce_presence_10cm, birch_presence_10cm, other_broadleaf_presence_10cm, oak_presence_10cm, beech_presence_10cm, southern_broadleaf_presence_10cm).
sapling_occurrence (Mapping | None) – Sapling occurrence indicators for dbh < 4 cm.
deterministic (bool) – If True, apply deterministic ingrowth.
rng (random.Random | None) – RNG used when deterministic is False.
use_initial_saplings (bool) – If True, use sapling occurrence in period 0.
period_index (int) – Period index (0 for first period).
min_mean_age_invoke (float) – Minimum mean age to invoke ingrowth.
ingrowth_species (Sequence[IngrowthSpeciesGroup] | None) – Species groups to include.
thinning_0_5_years (int) – Thinning indicator for years 0-5 (1 if thinned).
thinning_6_10_years (int) – Thinning indicator for years 6-10 (1 if thinned).
visibility_cleaning (int) – Visibility cleaning indicator (0/1).
field (int) – Field position indicator (0/1).
edge (int) – Stand edge indicator (0/1).
road (int) – Road position indicator (0/1).
plot_is_saplings (bool) – Skip ingrowth if plot type is saplings.

Returns:

Per-ha metrics and a generated tree list.

Return type:

IngrowthResult

pyforestry.sweden.ingrowth.wikberg_2004.ingrowth_to_plot_trees(result: IngrowthResult, plot_area_ha: float) → list[Tree][source]#

Scale per-ha ingrowth trees to a plot area.

Parameters:

result (IngrowthResult) – Per-ha ingrowth result.
plot_area_ha (float) – Plot area in hectares.

Returns:

Trees scaled to plot area.

Return type:

list[Tree]

Module contents#

Swedish ingrowth and recruitment equations.