pyforestry.base.helpers.primitives package#

Submodules#

pyforestry.base.helpers.primitives.age module#

Primitive data types for representing stand age measurements.

class pyforestry.base.helpers.primitives.age.Age(*values)[source]#

Bases: Enum

Enumeration of age measurement types.

Variables:

TOTAL (Age) – Total age measurement.
DBH (Age) – Diameter at breast height age measurement.

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

Bases: float

A float subclass representing an age measurement with type code.

Variables:: code (int) – Age enum code corresponding to measurement type.

property value: float#

Get the measurement value as a float.

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

pyforestry.base.helpers.primitives.area_aggregates module#

Lightweight numeric classes for common stand-level aggregates.

class pyforestry.base.helpers.primitives.area_aggregates.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).

property value: float#: Return the numeric basal area value.

class pyforestry.base.helpers.primitives.area_aggregates.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.

property value: float#: Return the numeric volume value.

class pyforestry.base.helpers.primitives.area_aggregates.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).

property value: float#: Return the numeric stems value.

pyforestry.base.helpers.primitives.bawad module#

Class representing the basal-area weighted mean diameter (BAWAD).

BAWAD is defined as the ratio of the sum of cubed diameters to the sum of squared diameters for a collection of trees:

BAWAD = sum(D^3) / sum(D^2)

It is expressed in centimetres and carries an optional precision attribute.

class pyforestry.base.helpers.primitives.bawad.BasalAreaWeightedDiameter(value: float, precision: float = 0.0)[source]#

Bases: float

A diameter measurement weighted by basal area.

This subclass of float stores the basal-area weighted mean diameter in centimetres along with an associated measurement precision.

Parameters:

value – The computed BAWAD value in centimetres. Must be non-negative.
precision – Optional precision (standard error) of the measurement in centimetres.

property value: float#: Return the raw BAWAD value in centimetres.

pyforestry.base.helpers.primitives.cartesian_position module#

Module for cartesian coordinate operations.

This module provides the Position class for handling 2D/3D coordinates, including construction from cartesian or polar inputs, optional CRS support, and utility methods for representation and input standardization.

class pyforestry.base.helpers.primitives.cartesian_position.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.

Variables:

X (float) – X-coordinate (easting) in specified CRS or local units.
Y (float) – Y-coordinate (northing) in specified CRS or local units.
Z (float) – Elevation or third dimension value; defaults to 0.0.
crs (Optional[CRS]) – Coordinate Reference System for interpreting coordinates.
coordinate_system (str) – Underlying coordinate system type, always ‘cartesian’.

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

property x: float#: Return the easting, for callers using the lower-case spelling.

property y: float#: Return the northing, for callers using the lower-case spelling.

pyforestry.base.helpers.primitives.diameter_cm module#

Diameter primitives and conversion helpers.

This module defines the Diameter_cm value object and helper functions for converting between diameter and basal-area representations. The formulas mirror the standard geometric relationships used in forestry growth calculations.

Source:: Standard basal-area geometry for diameter/basal-area conversion workflows in pyforestry.

class pyforestry.base.helpers.primitives.diameter_cm.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:

Variables:

over_bark (bool) – Whether the diameter is measured over bark.
measurement_height_m (float) – Height at which the diameter was measured (in meters).

property value: float#

Return the raw diameter value as a float.

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

pyforestry.base.helpers.primitives.diameter_cm.basal_area_cm2_to_diameter_cm(basal_area_cm2: float) → float[source]#

Compute diameter (cm) from basal area (cm²).

Source:: Standard basal-area geometry (area = pi * d^2 / 4).

Parameters:: basal_area_cm2 (float) – Basal area in cm².
Returns:: Diameter in centimeters.
Return type:: float
Raises:: ValueError – If basal_area_cm2 is negative.

pyforestry.base.helpers.primitives.diameter_cm.basal_area_growth_cm2_to_diameter_growth_cm(diameter_cm: float, basal_area_growth_cm2: float) → float[source]#

Convert basal area growth (cm²) to diameter growth (cm).

Source:: Standard basal-area geometry (d = sqrt(4 * area / pi)).

Parameters:

diameter_cm (float) – Current diameter (cm).
basal_area_growth_cm2 (float) – Basal area growth (cm²).

Returns:

Diameter increment (cm).

Return type:

float

Raises:

ValueError – If inputs are negative.

pyforestry.base.helpers.primitives.diameter_cm.diameter_growth_to_basal_area_growth_cm2(diameter_cm: float, diameter_growth_cm: float) → float[source]#

Convert diameter growth (cm) to basal area growth (cm²).

Source:: Standard basal-area geometry (area = pi * d^2 / 4).

Parameters:

diameter_cm (float) – Current diameter (cm).
diameter_growth_cm (float) – Diameter increment (cm).

Returns:

Basal area growth (cm²).

Return type:

float

Raises:

ValueError – If inputs are negative.

pyforestry.base.helpers.primitives.diameter_cm.diameter_to_basal_area_cm2(diameter_cm: float) → float[source]#

Compute basal area (cm²) from diameter (cm).

Source:: Standard basal-area geometry (area = pi * d^2 / 4).

Parameters:: diameter_cm (float) – Diameter at breast height in centimeters.
Returns:: Basal area in cm².
Return type:: float
Raises:: ValueError – If diameter_cm is negative.

pyforestry.base.helpers.primitives.loreys_mean_height module#

Class representing Lorey’s mean height (basal-area weighted mean height).

Lorey’s mean height weights each tree’s height by its basal area:

HL = sum(g_i * h_i) / sum(g_i)

where g_i is the basal area of tree i and h_i its height. Only trees carrying a measured height contribute to both the numerator and the denominator, so the result is the basal-area weighted mean of the measured heights. It is expressed in metres and carries an optional precision.

class pyforestry.base.helpers.primitives.loreys_mean_height.LoreysMeanHeight(value: float, precision: float = 0.0)[source]#

Bases: float

A basal-area weighted mean tree height.

This subclass of float stores Lorey’s mean height in metres along with an associated measurement precision (typically a standard error).

Parameters:

value – The computed Lorey’s mean height in metres. Must be non-negative.
precision – Optional precision (standard error) of the estimate in metres.

property value: float#: Return the raw Lorey’s mean height in metres.

pyforestry.base.helpers.primitives.qmd module#

Module for computing and representing the quadratic mean diameter (QMD) of a stand.

The quadratic mean diameter is calculated as:

QMD = sqrt((40000 * basal_area) / (pi * stems))

where:

basal_areafloat: Basal area in square meters per hectare (m²/ha).
stemsfloat: Number of stems per hectare (stems/ha).

This module provides the QuadraticMeanDiameter class, a subclass of float that carries both the QMD value (in centimeters) and an associated precision.

class pyforestry.base.helpers.primitives.qmd.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))

Variables:: precision (float) – Uncertainty or precision of the QMD measurement (cm).

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

property value: float#

Retrieve the raw QMD value.

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

pyforestry.base.helpers.primitives.sitebase module#

Abstract base class for geographic site definitions.

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

Bases: ABC

Base dataclass for location information used across site models.

Variables:

latitude (float) – Geographic latitude in decimal degrees.
longitude (float) – Geographic longitude in decimal degrees.

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

pyforestry.base.helpers.primitives.siteindex_value module#

Representation of site index values with metadata.

This module defines SiteIndexValue, a lightweight class used to store site index measurements along with key contextual information. A site index is commonly expressed as a height (in meters) for a given tree species at a specified reference age and is often derived from empirical functions. The class in this module subclasses float so that it behaves like a numeric value while also carrying:

reference_age: The AgeMeasurement the value refers to.
species: A set of TreeName objects for which the site index applies.
fn: The callable that was used to compute the value, if applicable.

These additional attributes make it easier to keep track of how the site index was produced when using it in analyses or passing it between functions.

class pyforestry.base.helpers.primitives.siteindex_value.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.

Variables:

reference_age (AgeMeasurement) – The age at which the site index is defined.
species (set[TreeName]) – One or more tree species that the site index represents.
fn (Callable) – The function that produced the value, allowing the computation to be traced back.

pyforestry.base.helpers.primitives.topheight module#

Primitive helpers for working with top (dominant) height measurements.

class pyforestry.base.helpers.primitives.topheight.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.primitives.topheight.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.

property value: float#: Return the numeric height value in metres.

pyforestry.base.helpers.primitives.volume module#

Utility classes for working with tree volume measurements.

This module defines AtomicVolume and CompositeVolume which are lightweight containers for storing volumes of timber. They offer convenience methods for converting between units and for combining compatible volumes while preserving important metadata such as region and tree species.

class pyforestry.base.helpers.primitives.volume.AtomicVolume(value: float, region: str, species: str = 'unknown', type: str = 'm3sk')[source]#

Bases: object

Represents a single, indivisible volume measurement for a specific species and region. This is the fundamental building block.

region has no default, deliberately. It used to default to "Sweden", which made this data-contract primitive assert a country on every volume built without one – and the assertion was not inert, because __add__() merges two volumes only when their regions match. A caller who omitted the argument got a volume labelled Swedish that merged happily with Swedish volumes, while a volume correctly tagged region="Norway" refused to merge with a defaulted one and silently degraded to a CompositeVolume: the same addition returned a different type depending on whether someone had remembered a keyword. The default was also load-bearing for nobody – Sweden’s volume functions do not build AtomicVolume at all, and Norway’s four all pass their region explicitly.

TYPE_REGIONS: ClassVar[Dict[str, List[str]]] = {'m3sk': ['Sweden', 'Finland', 'Norway']}#: Which regions report a given volume type. m3sk (skogskubikmeter) is a Nordic standing-volume measure, so the entry names the countries that use it rather than expressing a preference among them.

UNIT_CONVERSION: ClassVar[Dict[str, float]] = {'cm3': 1e-06, 'dm3': 0.001, 'm3': 1.0}#

classmethod from_unit(value: float, unit: str, **kwargs) → AtomicVolume[source]#: Create an AtomicVolume from value expressed in unit.

to(unit: str) → float[source]#: Return the numeric value converted to unit.

type: str = 'm3sk'#

class pyforestry.base.helpers.primitives.volume.CompositeVolume(volumes: List[AtomicVolume])[source]#

Bases: object

Container for multiple AtomicVolume instances.

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.

Module contents#

Expose typed primitive data structures used throughout the package.