pyforestry.base.helpers package¶

Subpackages¶

pyforestry.base.helpers.primitives package

Submodules¶

pyforestry.base.helpers.bitterlich_angle_count module¶

Module for Bitterlich (angle count) sampling techniques.

This module provides classes to tally tree counts per species using the angle-count (relascope) method and to aggregate multiple sampling points into stand-level basal area and stem density metrics.

class pyforestry.base.helpers.bitterlich_angle_count.AngleCount(ba_factor: float, value: List[float] | None = None, species: List[TreeName] | None = None, point_id: str | None = None, slope: float = 0.0)[source]¶

Bases: object

Parameters and tallies for angle-count sampling at a single point.

pyforestry.base.helpers.plot module¶

Bases: object

Contains information from a (usually) circular plot in a stand.

Attributes:¶

idint | str: An identifier for this plot.
positionPosition | None: The location of the plot center (if known).
radius_mfloat | None: The radius of the circular plot in meters (if known).
occlusionfloat: Portion [0-1] of the stand to be adjusted for being outside of the stand. Adjustment is
area_m2float | None: The area of the plot in m² (if known). Must supply either radius_m or area_m2.
siteSiteBase | None: Reference to a site object, if any.
treeslist[RepresentationTree]: The trees recorded on this plot (each possibly representing multiple stems).

property area_ha: float¶: Returns the plot area in hectares.

pyforestry.base.helpers.stand module¶

class pyforestry.base.helpers.stand.Stand(site: ~pyforestry.base.helpers.primitives.sitebase.SiteBase | None = None, area_ha: float | None = None, plots: ~typing.List[~pyforestry.base.helpers.plot.CircularPlot] = <factory>, polygon: ~shapely.geometry.polygon.Polygon | None = None, crs: ~pyproj.crs.crs.CRS | None = None, top_height_definition: ~pyforestry.base.helpers.primitives.topheight.TopHeightDefinition = <factory>)[source]¶

Bases: object

Represents a forest stand, which may have:

A polygon boundary
A list of sample plots
A site reference
Additional attributes (attrs dict)
A user-defined definition of “top height”

If a polygon is provided, the area_ha is computed from the polygon geometry (reprojected to a suitable UTM if the original CRS is geographic).

property BasalArea: StandMetricAccessor¶

Access the stand’s basal-area aggregator. .. rubric:: Example

stand.BasalArea.TOTAL -> StandBasalArea for total stand.BasalArea(TreeName(…))-> species-level StandBasalArea float(stand.BasalArea) -> numeric total

property QMD: StandMetricAccessor¶

Access the stand’s quadratic mean diameter (QMD) aggregator.

Usage:

Stand.QMD.TOTAL               -> Total QMD (QuadraticMeanDiameter)
Stand.QMD(TreeSpecies(...))   -> Species-level QMD estimate
float(Stand.QMD)              -> Numeric total QMD value (in cm)

property Stems: StandMetricAccessor¶

Access the stand’s stems aggregator. .. rubric:: Example

stand.Stems.TOTAL -> Stems object stand.Stems(TreeName(…)) -> species-level Stems float(stand.Stems) -> numeric total

append_plot(plot: CircularPlot) → None[source]¶: Append a new plot to the stand and recalculate the stand-level metrics. If any plot in the updated stand has AngleCount data, those estimates take precedence.

area_ha: float | None = None¶

attrs: Dict[str, Any]¶

static calculate_top_height_bias(r: float, m: int, n_trees: int = 1000, n_simulations: int = 10000, nominal_top_n: int = 100, nominal_area: float = 10000.0, sigma: float = 3.0)[source]¶

Calculate the bias of the estimator h_hat for top height in a forest stand. Based on (a simplified interpretation of) Matérn’s ideas on top-height sampling.

Parameters:¶

rfloat: Radius of the circular plot (meters).
mint: Number of largest trees (by diameter) to average in the plot.
n_treesint: Number of trees in each simulated stand.
n_simulationsint: Number of Monte Carlo runs (default 10,000).
nominal_top_nint: The nominal definition of “top” trees (e.g. top 100 in 1.0 ha).
nominal_areafloat: The nominal area in which we define top_n (default: 10,000 m² = 1.0 ha).
sigmafloat: Percentage measurement error in height (default 3.0% of the tree’s height).

Returns:¶

(bias, bias_percentage):

biasfloat: Average difference (h_hat - H_bar).
bias_percentagefloat: That bias as a percentage of the true top height H_bar.

crs: CRS | None = None¶

get_dominant_height() → TopHeightMeasurement | None[source]¶

Attempts to compute a stand-level ‘dominant height’ (aka top height) from the available plots, then correct it by subtracting a simulated bias.

Returns:: The final best estimate of top height in meters, along with metadata. If insufficient data, returns None.
Return type:: TopHeightMeasurement | None

plots: List[CircularPlot]¶

polygon: Polygon | None = None¶

site: SiteBase | None = None¶

thin_trees(uids: List[Any] | None = None, rule: Callable[[RepresentationTree], bool] | None = None, polygon: Polygon | None = None) → None[source]¶

Remove trees from the stand based on various criteria.

Parameters:

uids – List of tree uid values to remove.
rule – Callable that returns True for trees that should be removed.
polygon – When provided, the rule and/or UIDs are applied only to trees whose coordinates fall inside this polygon. If both uids and rule are None all trees inside the polygon are removed.

top_height_definition: TopHeightDefinition¶

use_angle_count: bool = False¶

class pyforestry.base.helpers.stand.StandMetricAccessor(stand: Stand, metric_name: str)[source]¶

Bases: object

Provides access to stand-level metric data (e.g. BasalArea or Stems).

Usage:

stand.BasalArea.TOTAL
stand.BasalArea(TreeName(...))
float(stand.BasalArea) -> numeric total
stand.BasalArea.precision -> total's precision

property precision: float¶: Shortcut to the total aggregator’s precision.

property value: float¶: Shortcut to the total aggregator’s numeric value.

pyforestry.base.helpers.tree module¶

Bases: Tree

A “multiplicity” tree, i.e. a single record that represents multiple identical trees on a plot (spatially implicit or partially explicit).

Attributes:¶

positionPosition | tuple[float,float] | tuple[float,float,float] | None: Location if relevant (often None or the plot center).
speciesTreeName | str | None: Species of the tree(s).
ageAge | float | None: Age of the tree(s).
diameter_cmDiameter_cm | float | None: Diameter of the tree(s).
height_mfloat | None: Height of the tree(s).
weightfloat: Number of stems represented by this single record (e.g. 1, or 5).

Bases: Tree

A spatially explicit single tree: (x, y, [z]) in a coordinate system + attributes.

Attributes:¶

positionPosition | tuple[float,float] | tuple[float,float,float] | None: The location of the tree in some coordinate system.
speciesTreeName | str | None: The species of the tree (or a string name to be parsed).
ageAge | float | None: The age of the tree. If an Age enum is used, it wraps the value in AgeMeasurement.
diameter_cmDiameter_cm | float | None: The diameter (cm) if known. If a float is passed, it can be coerced to a Diameter_cm.
height_mfloat | None: The height (m) of the tree if known.

class pyforestry.base.helpers.tree.Tree[source]¶

Bases: object

Base class for all tree objects. You can expand this to include common fields/methods that should exist on any type of tree.

pyforestry.base.helpers.tree_species module¶

Utility classes and helpers for defining tree species.

This module exposes two related concepts: TreeName represents a single biological species (genus + species name), while TreeSpecies is a namespace that groups TreeName instances for a given region. For example TreeSpecies.Sweden.pinus_sylvestris returns the TreeName object for Scots pine.

class pyforestry.base.helpers.tree_species.RegionalGenusGroup(genus: str, species: List[TreeName])[source]¶

Bases: object

A container for a group of TreeName objects sharing the same genus. It is iterable and supports membership testing.

property full_name: str¶

class pyforestry.base.helpers.tree_species.RegionalTreeSpecies(region: str, allowed_species: List[TreeName])[source]¶

Bases: object

Exposes a subset of globally defined TreeName objects as attributes. Also computes regional genus groups (e.g. ‘alnus’) that contain only the allowed species.

class pyforestry.base.helpers.tree_species.TreeGenus(name: str, code: str)[source]¶

Bases: object

Represents a botanical genus.

code: str¶

name: str¶

class pyforestry.base.helpers.tree_species.TreeName(genus: TreeGenus, species_name: str, code: str)[source]¶

Bases: object

A specific tree species within a genus.

code: str¶

property full_name: str¶

genus: TreeGenus¶

species_name: str¶

property tree_type: str¶

class pyforestry.base.helpers.tree_species.TreeSpecies[source]¶

Bases: object

Namespace exposing regional groups of tree species.

Sweden = <pyforestry.base.helpers.tree_species.RegionalTreeSpecies object>¶

pyforestry.base.helpers.tree_species.get_tree_type_by_genus(genus: str) → str[source]¶

pyforestry.base.helpers.tree_species.parse_tree_species(species_str: str | TreeName) → TreeName[source]¶

Return the TreeName corresponding to species_str.

species_str may be either a TreeName instance or a string such as "Pinus sylvestris". Strings are normalized and looked up among the globally defined species (for example those exposed through TreeSpecies).

pyforestry.base.helpers.utils module¶

Miscellaneous helper utilities.

pyforestry.base.helpers.utils.enum_code(value: int | float | bool | str) → int | float | bool | str[source]¶: Return numeric or label from an enum member or dataclass.

Module contents¶

Convenience imports for common helper types.

class pyforestry.base.helpers.Age(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Enumeration of age measurement types.

TOTAL¶

Total age measurement.

Type:: Age

DBH¶

Diameter at breast height age measurement.

Type:: Age

DBH = 2¶

TOTAL = 1¶

class pyforestry.base.helpers.AgeMeasurement(value: float, code: int)[source]¶

Bases: float

A float subclass representing an age measurement with type code.

code¶

Age enum code corresponding to measurement type.

Type:: int

code¶

property value: float¶

Get the measurement value as a float.

Returns:: The age value.
Return type:: float

class pyforestry.base.helpers.AngleCount(ba_factor: float, value: List[float] | None = None, species: List[TreeName] | None = None, point_id: str | None = None, slope: float = 0.0)[source]¶

Bases: object

Parameters and tallies for angle-count sampling at a single point.

Attributes:¶

idint | str: An identifier for this plot.
positionPosition | None: The location of the plot center (if known).
radius_mfloat | None: The radius of the circular plot in meters (if known).
occlusionfloat: Portion [0-1] of the stand to be adjusted for being outside of the stand. Adjustment is
area_m2float | None: The area of the plot in m² (if known). Must supply either radius_m or area_m2.
siteSiteBase | None: Reference to a site object, if any.
treeslist[RepresentationTree]: The trees recorded on this plot (each possibly representing multiple stems).

property area_ha: float¶: Returns the plot area in hectares.

class pyforestry.base.helpers.CompositeVolume(volumes: List[AtomicVolume])[source]¶

Bases: object

Represents a collection of AtomicVolume objects. It preserves all underlying information while providing aggregate views.

property regions: Set[str]¶: A set of all unique regions represented in the composite.

property species_composition: Dict[str, float]¶: Returns a dictionary detailing the total volume for each species. This directly answers your request to preserve component information.

property type: str¶: The shared type of all component volumes.

property value: float¶: The total summed value of all component volumes.

class pyforestry.base.helpers.Diameter_cm(value: float, over_bark: bool = True, measurement_height_m: float = 1.3)[source]¶

Bases: float

A diameter measurement in centimeters, with metadata.

This class subclasses float to store a diameter value (cm) while also carrying:

over_bark¶

Whether the diameter is measured over bark.

Type:: bool

measurement_height_m¶

Height at which the diameter was measured (in meters).

Type:: float

measurement_height_m¶

over_bark¶

property value: float¶

Return the raw diameter value as a float.

Returns:: The diameter in centimeters.
Return type:: float

class pyforestry.base.helpers.Position(X: float, Y: float, Z: float | None = 0.0, crs: CRS | None = None)[source]¶

Bases: object

Container for an (X, Y, Z) coordinate with optional CRS.

X¶

X-coordinate (easting) in specified CRS or local units.

Type:: float

Y¶

Y-coordinate (northing) in specified CRS or local units.

Type:: float

Z¶

Elevation or third dimension value; defaults to 0.0.

Type:: float

crs¶

Coordinate Reference System for interpreting coordinates.

Type:: Optional[CRS]

coordinate_system¶

Underlying coordinate system type, always ‘cartesian’.

Type:: str

classmethod from_polar(r: float, theta: float, z: float | None = 0.0)[source]¶

Create a Position from polar coordinates.

Converts radial distance and angle to cartesian X/Y.

Parameters:

r (float) – Radial distance from origin.
theta (float) – Angle in radians from X-axis.
z (Optional[float], optional) – Z-coordinate; defaults to 0.0.

Returns:

New Position instance in cartesian space.

Return type:

Position

class pyforestry.base.helpers.QuadraticMeanDiameter(value: float, precision: float = 0.0)[source]¶

Bases: float

A diameter measurement representing the quadratic mean diameter (QMD) in centimeters.

This class subclasses float to store a QMD value while carrying an associated measurement precision. The QMD is defined as:

QMD = sqrt((40000 * basal_area_m2_per_ha) / (pi * stems_per_ha))

precision¶

Uncertainty or precision of the QMD measurement (cm).

Type:: float

static compute_from(basal_area_m2_per_ha: float, stems_per_ha: float) → QuadraticMeanDiameter[source]¶

Compute QMD from basal area and stem count.

This static method calculates the QMD using the formula:

QMD = sqrt((40000 * basal_area_m2_per_ha) / (pi * stems_per_ha))

Parameters:

basal_area_m2_per_ha (float) – Basal area in square meters per hectare.
stems_per_ha (float) – Number of stems per hectare.

Raises:

ValueError – If either basal_area_m2_per_ha or stems_per_ha is non-positive.

Returns:

The computed QMD with default precision 0.0.

Return type:

QuadraticMeanDiameter

precision¶

property value: float¶

Retrieve the raw QMD value.

Returns:: The QMD in centimeters.
Return type:: float

Bases: Tree

A “multiplicity” tree, i.e. a single record that represents multiple identical trees on a plot (spatially implicit or partially explicit).

Attributes:¶

positionPosition | tuple[float,float] | tuple[float,float,float] | None: Location if relevant (often None or the plot center).
speciesTreeName | str | None: Species of the tree(s).
ageAge | float | None: Age of the tree(s).
diameter_cmDiameter_cm | float | None: Diameter of the tree(s).
height_mfloat | None: Height of the tree(s).
weightfloat: Number of stems represented by this single record (e.g. 1, or 5).

Bases: Tree

A spatially explicit single tree: (x, y, [z]) in a coordinate system + attributes.

Attributes:¶

positionPosition | tuple[float,float] | tuple[float,float,float] | None: The location of the tree in some coordinate system.
speciesTreeName | str | None: The species of the tree (or a string name to be parsed).
ageAge | float | None: The age of the tree. If an Age enum is used, it wraps the value in AgeMeasurement.
diameter_cmDiameter_cm | float | None: The diameter (cm) if known. If a float is passed, it can be coerced to a Diameter_cm.
height_mfloat | None: The height (m) of the tree if known.

class pyforestry.base.helpers.SiteBase(latitude: float, longitude: float)[source]¶

Bases: ABC

abstract compute_attributes() → None[source]¶: Compute site-specific derived attributes. Subclasses must implement this method.

latitude: float¶

longitude: float¶

class pyforestry.base.helpers.SiteIndexValue(value: float, reference_age: AgeMeasurement, species: set[TreeName], fn: Callable)[source]¶

Bases: float

Site index value with associated metadata.

This class stores a numeric site index while also tracking the reference age, species, and function used to derive the value. It subclasses float so it can be used directly in numeric operations.

reference_age¶

The age at which the site index is defined.

Type:: AgeMeasurement

species¶

One or more tree species that the site index represents.

Type:: set[TreeName]

fn¶

The function that produced the value, allowing the computation to be traced back.

Type:: Callable

fn¶

reference_age¶

species¶

class pyforestry.base.helpers.Stand(site: ~pyforestry.base.helpers.primitives.sitebase.SiteBase | None = None, area_ha: float | None = None, plots: ~typing.List[~pyforestry.base.helpers.plot.CircularPlot] = <factory>, polygon: ~shapely.geometry.polygon.Polygon | None = None, crs: ~pyproj.crs.crs.CRS | None = None, top_height_definition: ~pyforestry.base.helpers.primitives.topheight.TopHeightDefinition = <factory>)[source]¶

Bases: object

Represents a forest stand, which may have:

A polygon boundary
A list of sample plots
A site reference
Additional attributes (attrs dict)
A user-defined definition of “top height”

If a polygon is provided, the area_ha is computed from the polygon geometry (reprojected to a suitable UTM if the original CRS is geographic).

property BasalArea: StandMetricAccessor¶

Access the stand’s basal-area aggregator. .. rubric:: Example

stand.BasalArea.TOTAL -> StandBasalArea for total stand.BasalArea(TreeName(…))-> species-level StandBasalArea float(stand.BasalArea) -> numeric total

property QMD: StandMetricAccessor¶

Access the stand’s quadratic mean diameter (QMD) aggregator.

Usage:

Stand.QMD.TOTAL               -> Total QMD (QuadraticMeanDiameter)
Stand.QMD(TreeSpecies(...))   -> Species-level QMD estimate
float(Stand.QMD)              -> Numeric total QMD value (in cm)

property Stems: StandMetricAccessor¶

Access the stand’s stems aggregator. .. rubric:: Example

stand.Stems.TOTAL -> Stems object stand.Stems(TreeName(…)) -> species-level Stems float(stand.Stems) -> numeric total

append_plot(plot: CircularPlot) → None[source]¶: Append a new plot to the stand and recalculate the stand-level metrics. If any plot in the updated stand has AngleCount data, those estimates take precedence.

area_ha: float | None = None¶

attrs: Dict[str, Any]¶

Calculate the bias of the estimator h_hat for top height in a forest stand. Based on (a simplified interpretation of) Matérn’s ideas on top-height sampling.

Parameters:¶

rfloat: Radius of the circular plot (meters).
mint: Number of largest trees (by diameter) to average in the plot.
n_treesint: Number of trees in each simulated stand.
n_simulationsint: Number of Monte Carlo runs (default 10,000).
nominal_top_nint: The nominal definition of “top” trees (e.g. top 100 in 1.0 ha).
nominal_areafloat: The nominal area in which we define top_n (default: 10,000 m² = 1.0 ha).
sigmafloat: Percentage measurement error in height (default 3.0% of the tree’s height).

Returns:¶

(bias, bias_percentage):

biasfloat: Average difference (h_hat - H_bar).
bias_percentagefloat: That bias as a percentage of the true top height H_bar.

crs: CRS | None = None¶

get_dominant_height() → TopHeightMeasurement | None[source]¶

Attempts to compute a stand-level ‘dominant height’ (aka top height) from the available plots, then correct it by subtracting a simulated bias.

Returns:: The final best estimate of top height in meters, along with metadata. If insufficient data, returns None.
Return type:: TopHeightMeasurement | None

plots: List[CircularPlot]¶

polygon: Polygon | None = None¶

site: SiteBase | None = None¶

thin_trees(uids: List[Any] | None = None, rule: Callable[[RepresentationTree], bool] | None = None, polygon: Polygon | None = None) → None[source]¶

Remove trees from the stand based on various criteria.

Parameters:

uids – List of tree uid values to remove.
rule – Callable that returns True for trees that should be removed.
polygon – When provided, the rule and/or UIDs are applied only to trees whose coordinates fall inside this polygon. If both uids and rule are None all trees inside the polygon are removed.

top_height_definition: TopHeightDefinition¶

use_angle_count: bool = False¶

class pyforestry.base.helpers.StandBasalArea(value: float, species: TreeName | None = None, precision: float = 0.0, over_bark: bool = True, direct_estimate: bool = True)[source]¶

Bases: float

Represents basal area (m²/ha) for one or more species.

Attributes:¶

speciesTreeName | list[TreeName]: The species (or list of species) to which this basal area applies.
precisionfloat: Standard deviation, standard error, or other measure of precision (if known).
over_barkbool: True if the basal area is measured over bark.
direct_estimatebool: True if this is a direct field estimate (e.g. from Bitterlich sampling).

direct_estimate¶

over_bark¶

precision¶

species¶

property value: float¶

class pyforestry.base.helpers.StandMetricAccessor(stand: Stand, metric_name: str)[source]¶

Bases: object

Provides access to stand-level metric data (e.g. BasalArea or Stems).

Usage:

stand.BasalArea.TOTAL
stand.BasalArea(TreeName(...))
float(stand.BasalArea) -> numeric total
stand.BasalArea.precision -> total's precision

property precision: float¶: Shortcut to the total aggregator’s precision.

property value: float¶: Shortcut to the total aggregator’s numeric value.

class pyforestry.base.helpers.StandVolume(value: float, species: TreeName | None = None, precision: float = 0.0, over_bark: bool = True, fn=None)[source]¶

Bases: float

Represents a volume (m³/ha, typically) of standing trees in a stand, optionally for a single species or multiple species.

Attributes:¶

speciesTreeName | list[TreeName]: The species or list of species for which the volume is estimated.
precisionfloat: Standard deviation or other measure of precision (if known).
over_barkbool: True if the volume is measured over bark.
fncallable | None: An optional reference to the function or model used to derive the volume.

fn¶

over_bark¶

precision¶

species¶

property value: float¶

class pyforestry.base.helpers.Stems(value: float, species: TreeName | None = None, precision: float = 0.0)[source]¶

Bases: float

Represents the number of stems per hectare (stems/ha) for one or more species.

Attributes:¶

speciesTreeName | list[TreeName]: The species (or list of species) to which this stems count applies.
precisionfloat: Standard deviation or similar measure of precision (if known).

precision¶

species¶

property value: float¶

class pyforestry.base.helpers.TopHeightDefinition(nominal_n: int = 100, nominal_area_ha: float = 1.0)[source]¶

Bases: object

Defines how the ‘top height’ (dominant height) is conceptually measured in a stand: - nominal_n: number of top trees in 1.0 hectare to average - nominal_area_ha: the area basis for that count

class pyforestry.base.helpers.TopHeightMeasurement(value: float, definition: TopHeightDefinition, species: TreeName | List[TreeName] | None = None, precision: float = 0.0, est_bias: float = 0.0)[source]¶

Bases: float

A float-like class that stores the measured top (dominant) height of a stand.

Attributes:¶

definitionTopHeightDefinition: The definition used to identify the top height (e.g. top 100 trees per ha).
speciesTreeName | list[TreeName]: The species or species mixture that this top height applies to.
precisionfloat: An estimate of precision (e.g. standard error) of the top height.
est_biasfloat: Any known or estimated bias that might be subtracted (or added) from the measurement.

definition¶

est_bias¶

precision¶

species¶

property value: float¶

class pyforestry.base.helpers.Tree[source]¶

Bases: object

Base class for all tree objects. You can expand this to include common fields/methods that should exist on any type of tree.

class pyforestry.base.helpers.TreeGenus(name: str, code: str)[source]¶

Bases: object

Represents a botanical genus.

code: str¶

name: str¶

class pyforestry.base.helpers.TreeName(genus: TreeGenus, species_name: str, code: str)[source]¶

Bases: object

A specific tree species within a genus.

code: str¶

property full_name: str¶

genus: TreeGenus¶

species_name: str¶

property tree_type: str¶

pyforestry.base.helpers.enum_code(value: int | float | bool | str) → int | float | bool | str[source]¶: Return numeric or label from an enum member or dataclass.

pyforestry.base.helpers.parse_tree_species(species_str: str | TreeName) → TreeName[source]¶

Return the TreeName corresponding to species_str.