pyforestry.sweden.regeneration package#

Submodules#

pyforestry.sweden.regeneration.elfving_1982 module#

Extracted HUGIN (Elfving 1982) formulas and NYSKOG reconstruction kernels.

These are the kernel equations behind pyforestry.sweden.adapters.elfving_1982, which carries the catalog descriptor for the pair; the per-function docstrings below cite the section of the report each formula comes from.

Source:

Elfving, B. (1982). HUGINs ungskogstaxering 1976-1979. Sveriges lantbruksuniversitet, Projekt HUGIN, Rapport nr 27, Umeå, 115 s.

class pyforestry.sweden.regeneration.elfving_1982.HuginCropTreeProbabilityKernel(name: str = 'hugin_crop_tree_probability', version: str = '1.0.0', units_contract: Mapping[str, str]=<factory>)[source]#

Bases: object

Mapping-style kernel for Hugin crop-tree probability.

Reference:

Elfving, B. (1982). Hugins ungskogstaxering 1976-1979. SLU, Projekt Hugin, Rapport 27 (§2.1, prioritizing trees at pre-commercial thinning).

compute(inputs: Mapping[str, Any]) → Mapping[str, float][source]#

Evaluate the kernel and return {"crop_tree_probability": ...}.

name: str = 'hugin_crop_tree_probability'#
version: str = '1.0.0'#
class pyforestry.sweden.regeneration.elfving_1982.HuginMeanHeightKernel(name: str = 'hugin_mean_height', version: str = '1.0.0', units_contract: Mapping[str, str]=<factory>)[source]#

Bases: object

Mapping-style kernel for Hugin mean-height calculations.

Reference:

Elfving, B. (1982). Hugins ungskogstaxering 1976-1979. SLU, Projekt Hugin, Rapport 27 (§2.2, mean-height development in young stands).

compute(inputs: Mapping[str, Any]) → Mapping[str, float][source]#

Evaluate the kernel and return {"mean_height_m": ...}.

name: str = 'hugin_mean_height'#
version: str = '1.0.0'#
pyforestry.sweden.regeneration.elfving_1982.crop_tree_probability(*, height_m: float, mean_height_m: float, conifer_stems_per_100m2: float, rec_stems_per_ha: float, coniferous: bool) → float[source]#

Compute crop-tree probability for a single tree.

Reference: Elfving (1982), Rapport 27 §2.1. p = sin^2(…) in relative tree height H=h/HA and sqrt of conifer stem count; separate conifer/broadleaf forms.

pyforestry.sweden.regeneration.elfving_1982.dominant_conifer_share(*, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, qind: float, ln_si: float, wet: int, dry: int, rich: int, poor: int, hwod: int, hwd: int, shrubs: int, lichen: int, deterministic: bool = True, noise: float = 0.0) → float[source]#

Step 3 NYSKOG equation: dominant conifer share within conifers.

pyforestry.sweden.regeneration.elfving_1982.height_variation(*, species: TreeName, species_height_m: float, q: float, ln_q: float, self_rejuvenated: int, deterministic: bool = True, noise: float = 0.0, min_cv: float = 0.1, max_cv: float = 1.0) → float[source]#

Step 4B NYSKOG equation: height variation (CV).

pyforestry.sweden.regeneration.elfving_1982.mean_age(*, mean_height_m: float, species: TreeName, site_index_pine_m: float, site_index_spruce_m: float) → float[source]#

Invert mean height to mean age (years).

pyforestry.sweden.regeneration.elfving_1982.mean_height(*, age_years: float, species: TreeName, site_index_pine_m: float, site_index_spruce_m: float) → float[source]#

Compute mean height (m) from total age and site indices.

Reference: Elfving (1982), Rapport 27 §2.2. H = SI/(exp(Y)+1) with Y a quadratic in ln(total age); coefficients per species group.

pyforestry.sweden.regeneration.elfving_1982.nyskog_indicators_from_site(*, field_layer: SwedenFieldLayer | None, soil_moisture: SwedenSoilMoisture | None) → dict[str, int][source]#

Map Swedish site enums to NYSKOG indicator variables.

pyforestry.sweden.regeneration.elfving_1982.probabilities_from_tree_list(trees: Sequence[Tree], *, rec_stems_per_ha: float, expansion_factor: float = 1.0) → list[float][source]#

Compute crop-tree probabilities for a tree list.

pyforestry.sweden.regeneration.elfving_1982.production_potential_q(asinw: float) → float[source]#

Production potential Q (0-100) from ASINW = arcsin(sqrt(W)).

q = 100 * W, with W = sin^2(asinw). Elfving (1982), the published regeneration report (Elfving 1982).

pyforestry.sweden.regeneration.elfving_1982.proportion_conifer(*, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, q: float, ln_qind: float, stem_total: float, ln_si: float, wet: int, dry: int, rich: int, poor: int, deterministic: bool = True, noise: float = 0.0) → float[source]#

Step 2 NYSKOG equation: conifer proportion of total stems.

pyforestry.sweden.regeneration.elfving_1982.reconstruct_summary(*, asinw: float, mean_height_main_m: float, site_index_m: float, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, species_to_plant: TreeName, nfi_region: Literal['Reg1', 'Reg21', 'Reg22', 'Reg3', 'Reg4', 'Reg5'] | str, field_layer: SwedenFieldLayer | None = None, soil_moisture: SwedenSoilMoisture | None = None, indicators: dict[str, int] | None = None, deterministic: bool = True, noise: float = 0.0, rng: float | None = None) → dict[str, Any][source]#

Run the full NYSKOG reconstruction workflow and return summary outputs.

pyforestry.sweden.regeneration.elfving_1982.secondary_mean_height(*, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, secondary_species: TreeName, site_index_m: float, mean_height_main_m: float, herb: int, dry: int, wet: int, deterministic: bool = True, noise: float = 0.0) → float[source]#

Step 4A NYSKOG equation: mean height for secondary species.

pyforestry.sweden.regeneration.elfving_1982.site_index_for_species(species: TreeName, *, site_index_pine_m: float, site_index_spruce_m: float) → float[source]#

Translate pine/spruce site indices to a species-specific site index.

pyforestry.sweden.regeneration.elfving_1982.stems_per_species(*, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, species_to_plant: TreeName, stem_total: float, prop_conifer: float, prop_dom_conifer: float, site_index_m: float, nfi_region: Literal['Reg1', 'Reg21', 'Reg22', 'Reg3', 'Reg4', 'Reg5'] | str) → dict[str, float][source]#

Step 3 NYSKOG equation: resolve stems per species group.

pyforestry.sweden.regeneration.elfving_1982.total_stems(*, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, mean_height_main_m: float, q: float, ln_q: float, ln_si: float, under_dimension_prob: float, wet: int, dry: int, height_indicator_dm: float, deterministic: bool = True, noise: float = 0.0) → float[source]#

Step 1 NYSKOG equation: compute total stems per hectare.

pyforestry.sweden.regeneration.elfving_1982.udim_probability(q: float, *, deterministic: bool = True, rng: float | None = None) → float[source]#

Compute under-dimensioned probability or Bernoulli draw indicator.

pyforestry.sweden.regeneration.elfving_1982.weibull_parameters(*, species: TreeName, cvh: float, mean_height_m: float) → tuple[float, float][source]#

Step 5 NYSKOG equation: Weibull scale (beta) and shape (lambda).

pyforestry.sweden.regeneration.elfving_1982.young_stand_quality_asinw(*, stocking_arcsine_radians: float, regeneration_type: Literal['natural_regeneration', 'extensive', 'sown', 'pine_plantation', 'spruce_plantation', 'contorta_plantation', 'deciduous_plantation'] | str, latitude_deg: float | None = None) → float[source]#

Young-stand quality on the arcsine scale, ASINW = arcsin(sqrt(W)).

Elfving (1982), Hugin Rapport 27:

natural      W = sin^2(-0.11  + 1.671*asinslh - 0.583*asinslh^2)
cultivation  W = sin^2(-0.058 + 1.380*asinslh - 0.315*asinslh^2 - 0.031*NS)

where NS = 1 if latitude_deg > 60 N (cultivation only; ignored for natural, whose NS coefficient is 0). stocking_arcsine_radians is the SLH linear predictor (= 2*asinslh); the return value feeds production_potential_q() (q = 100*sin^2(asinw)).

pyforestry.sweden.regeneration.elfving_1992 module#

Regeneration quality and density (SLH), Elfving (1992) Arbetsrapporter nr 67.

This module implements the full tabulated form – the Tab. 1-2 coefficient tables with their application notes.

Note: A simplified form of the same functions also circulates, expressed directly in ASINSLH/ASINW. It differs in several respects: seed trees are scaled by /100, inverse_area uses 1/(plot_area + 1), inverse_map_number uses 1/(map_number + 5), wet is used instead of moist, and the SYZ flag includes X (Gävleborg). The two forms therefore do not agree numerically, and this module follows the tabulated one. (The two were previously labelled after the appendix numbers of a secondary document, which said nothing about what actually distinguishes them.)

Note: Is Jonsbon actually site index scale [1-9], or MAImax according to Jonson scale? MAImax= 8*0.75(Jonson index - 2).

class pyforestry.sweden.regeneration.elfving_1992.Elfving1992Regeneration[source]#

Bases: object

SLH regeneration functions for natural and cultivated stands (full tabulated form).

Defaults follow the tabulated form’s application notes: - age_years = 12 - n_full = 2_500 - coefficient adjustments enabled (use_adjusted_coeffs=True)

N.B. At application of the functions in Tab. 1-2 age was set to 12 and N-full to 2.5. Increased efficiency in provenance selection and scarification has also been considered by assumed influence on the cofficients. For cultivations the negative effect by increasing height above see level has been reduced from -0.0514 to -0.0257 and the positive effect by scarification has been increased from 0.0757 to 0.2. For natural regenerations the effect by scarification has been modified to 0.30 on mesic sites and 0.15 on other sites.

Example

>>> site = SwedishSite(...)
>>> jonson_index = jonson_index_from_site_index(
...     h100_input=site_index_value,
...     main_species=TreeSpecies.Sweden.picea_abies,
...     vegetation=site.field_layer,
...     altitude=site.altitude or 0.0,
...     county=site.county,
... )
>>> Elfving1992Regeneration.slh_natural(
...     latitude_deg=site.latitude,
...     altitude_m=site.altitude or 0.0,
...     county=site.county,
...     soil_moisture=site.soil_moisture,
...     jonson_index=jonson_index,
... )
static slh_cultivated(*, latitude_deg: float, altitude_m: float, county: SwedenCounty | None, jonson_index: float | None = None, h100_input: SiteIndexValue | None = None, main_species: TreeName | None = None, vegetation: SwedenFieldLayer | None = None, age_years: float = 12.0, n_full: float = 2500.0, spacing_m: float | None = None, plant_count_per_ha: float | None = None, scarified: bool = False, burnt: bool = False, sown: bool = False, spruce: bool = False, use_adjusted_coeffs: bool = True, cultivation_altxns_coeff: float = -0.0257, cultivation_scarif_coeff: float = 0.2) → tuple[float, float, float][source]#

Compute SLH for cultivation (sowing/planting).

Parameters:

  • latitude_deg (float) – Latitude in decimal degrees.

  • altitude_m (float) – Altitude in meters above sea level.

  • county (Sweden.County | None) – Swedish county enum. Used for T-area indicator and for Jonson index derivation when jonson_index is not supplied.

  • jonson_index (float | None) – Jonson site index (1..9). If omitted, supply h100_input, main_species, vegetation, and county to derive it.

  • h100_input (SiteIndexValue | None) – H100 site index value used to derive Jonson index if jonson_index is not provided.

  • main_species (TreeName | None) – Species for H100 (pine or spruce) when deriving Jonson index.

  • vegetation (Sweden.FieldLayer | None) – Field layer vegetation enum for Hagglund 1981 translation when deriving Jonson index.

  • age_years (float) – Vegetation periods since sowing/planting. Default is 12.

  • n_full (float) – Demanded seedlings per ha for full stocking (plants/ha). Default is 2_500 (the tabulated form uses 2.5 thousand/ha).

  • spacing_m (float | None) – Plant spacing in meters. If omitted, plant_count_per_ha must be provided and spacing is derived as 100/sqrt(plant_count_per_ha).

  • plant_count_per_ha (float | None) – Plants per ha for spacing derivation when spacing_m is not provided.

  • scarified (bool) – Indicator for scarification treatment.

  • burnt (bool) – Indicator for prescribed burning after final felling.

  • sown (bool) – Indicator for sown regenerations.

  • spruce (bool) – Indicator for spruce cultivation.

  • use_adjusted_coeffs (bool) – Use the tabulated form’s adjusted coefficients for altitude and scarification.

  • cultivation_altxns_coeff (float) – Adjusted altitude coefficient when enabled.

  • cultivation_scarif_coeff (float) – Adjusted scarification coefficient when enabled.

Returns:

(asinslh, slh_est, slh_corr) where: - asinslh is the linear predictor (radians), - slh_est is back-transformed stocking (0..1), - slh_corr is bias-corrected stocking (0..1).

Return type:

tuple[float, float, float]

Raises:

ValueError – If jonson_index is not supplied and required inputs for deriving it are missing, if h100_input is not from Hagglund 1970, or if spacing cannot be derived.

static slh_natural(*, latitude_deg: float, altitude_m: float, county: SwedenCounty | None, soil_moisture: SwedenSoilMoisture | None, jonson_index: float | None = None, h100_input: SiteIndexValue | None = None, main_species: TreeName | None = None, vegetation: SwedenFieldLayer | None = None, age_years: float = 12.0, n_full: float = 2500.0, prop_cultivated: float = 0.0, seed_trees_per_ha: float = 0.0, regen_area_ha: float = 1.0, scarified: bool = False, burnt: bool = False, no_treat: bool = False, uncleaned: bool = False, use_adjusted_coeffs: bool = True, natural_scarif_coeff_mesic: float = 0.3, natural_scarif_coeff_other: float = 0.15) → tuple[float, float, float][source]#

Compute SLH for natural regeneration.

Parameters:

  • latitude_deg (float) – Latitude in decimal degrees.

  • altitude_m (float) – Altitude in meters above sea level.

  • county (Sweden.County | None) – Swedish county enum. Used for Gotland/SYZ/T-area indicators and for Jonson index derivation when jonson_index is not supplied.

  • soil_moisture (Sweden.SoilMoistureEnum | None) – Soil moisture class. Used to set dry/mesic/moist indicator variables.

  • jonson_index (float | None) – Jonson site index (1..9). If omitted, supply h100_input, main_species, vegetation, and county to derive it.

  • h100_input (SiteIndexValue | None) – H100 site index value used to derive Jonson index if jonson_index is not provided.

  • main_species (TreeName | None) – Species for H100 (pine or spruce) when deriving Jonson index.

  • vegetation (Sweden.FieldLayer | None) – Field layer vegetation enum for Hagglund 1981 translation when deriving Jonson index.

  • age_years (float) – Vegetation periods since regeneration. Default is 12.

  • n_full (float) – Demanded seedlings per ha for full stocking (plants/ha). Default is 2_500 (the tabulated form uses 2.5 thousand/ha).

  • prop_cultivated (float) – Proportion cultivated seedlings in natural regeneration (0..1).

  • seed_trees_per_ha (float) – Number of seed trees per hectare. Set to 0 for stands without seed trees.

  • regen_area_ha (float) – Regeneration area (ha). Used as inverse_area = 1/area.

  • scarified (bool) – Indicator for scarification treatment.

  • burnt (bool) – Indicator for prescribed burning after final felling.

  • no_treat (bool) – Indicator for no regeneration treatments.

  • uncleaned (bool) – Indicator for uncleaned sites after clear-felling.

  • use_adjusted_coeffs (bool) – Use the tabulated form’s adjusted scarification coefficients.

  • natural_scarif_coeff_mesic (float) – Scarification coefficient on mesic sites when adjusted (default 0.30).

  • natural_scarif_coeff_other (float) – Scarification coefficient on non-mesic sites when adjusted (default 0.15).

Returns:

(asinslh, slh_est, slh_corr) where: - asinslh is the linear predictor (radians), - slh_est is back-transformed stocking (0..1), - slh_corr is bias-corrected stocking (0..1).

Return type:

tuple[float, float, float]

Raises:

ValueError – If jonson_index is not supplied and required inputs for deriving it are missing, or if h100_input is not from Hagglund 1970.

Module contents#

Swedish regeneration quality equations.

Regeneration stocking (SLH) is Elfving (1992), in elfving_1992. The young-stand quality (W / ASINW) derived from stocking is Elfving (1982) and lives with the Hugin/NYSKOG functions in pyforestry.sweden.adapters.elfving_1982.