pyforestry.base.helpers.primitives package

Submodules

pyforestry.base.helpers.primitives.age module

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

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.primitives.age.AgeMeasurement(value: float, code: int)

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

pyforestry.base.helpers.primitives.area_aggregates module

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)

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.primitives.area_aggregates.StandVolume(value: float, species: TreeName | None = None, precision: float = 0.0, over_bark: bool = True, fn=None)

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.primitives.area_aggregates.Stems(value: float, species: TreeName | None = None, precision: float = 0.0)

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

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)

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)

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

pyforestry.base.helpers.primitives.diameter_cm module

Module for handling diameter measurements and conversions.

This module provides functions and classes to represent tree stem diameters in centimeters and to perform unit conversions, calculations of basal area per tree, and validation of inputs.

Classes:

Diameter: Represents a diameter measurement in cm with optional unit conversion.

Functions:

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

class pyforestry.base.helpers.primitives.diameter_cm.Diameter_cm(value: float, over_bark: bool = True, measurement_height_m: float = 1.3)

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

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)

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

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

pyforestry.base.helpers.primitives.sitebase module

class pyforestry.base.helpers.primitives.sitebase.SiteBase(latitude: float, longitude: float)

Bases: ABC

abstract compute_attributes() → None

Compute site-specific derived attributes. Subclasses must implement this method.

latitude: float

longitude: float

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)

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

pyforestry.base.helpers.primitives.topheight module

class pyforestry.base.helpers.primitives.topheight.TopHeightDefinition(nominal_n: int = 100, nominal_area_ha: float = 1.0)

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)

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

pyforestry.base.helpers.primitives.volume module

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

Bases: object

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

TYPE_REGIONS: ClassVar[Dict[str, List[str]]] = {'m3sk': ['Sweden', 'Finland', 'Norway']}

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

classmethod from_unit(value: float, unit: str, **kwargs) → AtomicVolume

region: str = 'Sweden'

species: str = 'unknown'

to(unit: str) → float

type: str = 'm3sk'

value: float

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

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.

Module contents

Expose typed primitive data structures used throughout the package.