Munin.Helpers package¶

Submodules¶

Munin.Helpers.Base module¶

Munin.Helpers.Primitives module¶

Munin.Helpers.TreeSpecies module¶

class Munin.Helpers.TreeSpecies.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 Munin.Helpers.TreeSpecies.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 Munin.Helpers.TreeSpecies.TreeGenus(name: str, code: str)[source]¶

Bases: object

code: str¶

name: str¶

class Munin.Helpers.TreeSpecies.TreeName(genus: Munin.Helpers.TreeSpecies.TreeGenus, species_name: str, code: str)[source]¶

Bases: object

code: str¶

property full_name: str¶

genus: TreeGenus¶

species_name: str¶

property tree_type: str¶

class Munin.Helpers.TreeSpecies.TreeSpecies[source]¶

Bases: object

Sweden = <Munin.Helpers.TreeSpecies.RegionalTreeSpecies object>¶

Munin.Helpers.TreeSpecies.get_tree_type_by_genus(genus: str) → str[source]¶

Munin.Helpers.TreeSpecies.parse_tree_species(species_str: str | TreeName) → TreeName[source]¶

Try to find and return a TreeName object matching the given species string.

The function normalizes the input string (e.g. “pinus sylvestris”) and compares it to the lower-case full_name property of the defined species in the chosen region, e.g. TreeSpecies.Sweden.

Module contents¶

class Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.Helpers.SiteIndexValue(value: float, reference_age: AgeMeasurement, species: set[TreeName], fn: Callable)[source]¶

Bases: float

fn¶

reference_age¶

species¶

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.

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.

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

class Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.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 Munin.Helpers.TreeGenus(name: str, code: str)[source]¶

Bases: object

code: str¶

name: str¶

class Munin.Helpers.TreeName(genus: Munin.Helpers.TreeSpecies.TreeGenus, species_name: str, code: str)[source]¶

Bases: object

code: str¶

property full_name: str¶

genus: TreeGenus¶

species_name: str¶

property tree_type: str¶

class Munin.Helpers.TreeSpecies[source]¶

Bases: object

Sweden = <Munin.Helpers.TreeSpecies.RegionalTreeSpecies object>¶

Munin.Helpers.parse_tree_species(species_str: str | TreeName) → TreeName[source]¶

Try to find and return a TreeName object matching the given species string.

The function normalizes the input string (e.g. “pinus sylvestris”) and compares it to the lower-case full_name property of the defined species in the chosen region, e.g. TreeSpecies.Sweden.