Statistics

Distance Metrics

Contains utilities for calculating distance values.

This module defines utility functions for distance metrics that can be used to compare simulated and observational data.

class deeprootgen.statistics.distance_metrics.DistanceMetricBase(**_)[source]

The distance metric abstract class.

abstract calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

Raises:
NotImplementedError:

Error raised for the unimplemented abstract method.

class deeprootgen.statistics.distance_metrics.L1Norm(**_)[source]

The L1 norm distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.MeanAbsoluteError(**_)[source]

The mean absolute error distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.MeanAbsolutePercentageError(**_)[source]

The mean absolute percentage error distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.MeanPinballLoss(**_)[source]

The mean pinball loss distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.MeanSquaredError(**_)[source]

The mean squared error distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.MedianAbsoluteError(**_)[source]

The median absolute error distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

class deeprootgen.statistics.distance_metrics.RootMeanSquaredError(**_)[source]

The root mean squared error distance.

calculate(observed: ndarray, simulated: ndarray) → float | ndarray[source]

Calculate the distance between observed and simulated data.

Args:
observed (np.ndarray):

The observed data.

simulated (np.ndarray):

The simulated data.

deeprootgen.statistics.distance_metrics.get_distance_metric_func(distance_metric: str) → Callable[source]

Get the distance metric function by name.

Args:
distance_metric (str):

The distance metric name.

Returns:
Callable:

The distance metric function.

deeprootgen.statistics.distance_metrics.get_distance_metrics() → list[dict][source]

Get a list of available distance metrics and labels.

Returns:
list[dict]:

A list of available distance metrics and labels.

Root Grid Aggregation

Aggregate DeepRootGen root length and dry biomass within soil grid voxels.

The soil DataFrame must contain voxel boundary points with x and y horizontal and z vertical (negative downward). Root coordinates and lengths are in cm; root tissue density is in g/cm3.

deeprootgen.statistics.root_grid_aggregation.aggregate_root_grid(node_df: DataFrame, soil_df: DataFrame, length_source: str = 'recorded') → tuple[DataFrame, DataFrame][source]

Return (per-voxel metrics, per-plant in-grid biomass totals).

Root segments are the edges from a parent node to each non-base child node. Each segment’s length is clipped and split between the soil voxels it crosses. Dry mass for a segment is pi*(diameter/2)^2*length*RTD.

length_source=’recorded’ allocates each stored segment length in proportion to the geometric fraction inside each voxel. ‘geometric’ uses endpoint distances instead. All lengths and dimensions are assumed to be cm.

Spatial RLD

Spatial matching of simulated roots to field soil cores.

deeprootgen.statistics.spatial_rld.calculate_core_rld(node_df: DataFrame, *, x: float, y: float, z_lower_bound: float, z_upper_bound: float, core_radius: float, diameter_max_mm: float | None = None, plant_id: int | None = None, length_source: str = 'recorded') → float[source]

Calculate RLD inside a cylindrical field sampling volume.

Coordinates and lengths are in cm. z=0 is ground level; negative z represents depth.

Args:

node_df: Simulated root node dataframe. x, y: Horizontal soil core centre, relative to the plant. z_lower_bound: Bottom of the sampled depth interval. z_upper_bound: Top of the sampled depth interval. core_radius: Soil core radius (cm). diameter_max_mm: Optional maximum root diameter (mm). plant_id: Optional plant identifier. length_source: ‘recorded’ or ‘geometric’.

Returns:

Root length density (cm/cm3).

Summary Statistics

Summary statistics for hierarchical DeepRootGen root-system architectures.

Input is the node DataFrame returned by simulation.G.as_df(). A root segment is the edge from a node’s parent to that node; its attributes belong to the child node. Only valid child segments of order > 0 are measured.

Lengths default to 3D geometric lengths. Pass length_source=’recorded’ to use the stored node length instead. In particular, voxel statistics include only the part of a segment lying inside the supplied soil grid.

class deeprootgen.statistics.summary_statistics.AverageDiameter(**kwargs)[source]

Length-weighted mean root-segment diameter.

class deeprootgen.statistics.summary_statistics.AverageLength(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.AverageSpecificRootLength(root_tissue_density: float, **kwargs)[source]

Arithmetic mean of organ-specific length/mass ratios (cm/g).

class deeprootgen.statistics.summary_statistics.AverageVolume(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.AverageWeight(root_tissue_density: float, **kwargs)[source]
class deeprootgen.statistics.summary_statistics.ConvexHullArea(**kwargs)[source]

Surface area of the 3D convex hull, not projected horizontal area.

class deeprootgen.statistics.summary_statistics.ConvexHullVolume(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.DepthDistribution(origin=None, bins=10, **kwargs)[source]

Cumulative root length fraction versus depth below planting origin.

class deeprootgen.statistics.summary_statistics.HorizontalRootLengthDistribution(**kwargs)[source]

Root length (cm) allocated to concentric horizontal radial rings.

class deeprootgen.statistics.summary_statistics.RadialDistribution(origin=None, bins=10, **kwargs)[source]

Cumulative root length fraction versus actual horizontal radius.

class deeprootgen.statistics.summary_statistics.RootBranchingAngleDistribution(**kwargs)[source]

Angle (degrees) between parent incoming tangent and daughter start.

Excludes primary roots attached to the origin and junctions where the incoming parent segment is not valid/available.

class deeprootgen.statistics.summary_statistics.RootBranchingFrequency(max_order: int | None = None, **kwargs)[source]

Lateral-root emergence events per cm of eligible parent-root length.

Eligible parent orders are < max_order. If max_order is not supplied, the highest observed order (at least 2) is used. Supply the model’s max_order for comparable results even if higher orders happen to be absent.

class deeprootgen.statistics.summary_statistics.RootBranchingOrderDistribution(max_order: int | None = None, **kwargs)[source]

Counts and root lengths by topological order.

class deeprootgen.statistics.summary_statistics.RootDiameterDistribution(diameter_bins_mm=None, **kwargs)[source]

Length-weighted distribution by segment diameter (mm).

class deeprootgen.statistics.summary_statistics.RootDryMassByDiameter(diameter_bins_mm: list[float], root_tissue_density: float | None = None, **kwargs)[source]

Segment dry mass (g) per diameter class (mm).

class deeprootgen.statistics.summary_statistics.RootLengthDensity(soil_df: DataFrame, length_source='geometric', root_types=None, **kwargs)[source]

Root length density within a 3D soil-voxel grid.

Exact intersection of straight graph segments with every voxel crossed; only lengths inside the supplied grid are included.

calculate_statistic_per_layer(df, layer_decrement=10)[source]

Midpoint-assigned approximation for scalar statistics.

Exact length-by-depth allocation is in DepthDistribution, and exact grid-layer RLD is in RootLengthDensity. Parent nodes are retained for graph geometry while non-layer child segments are masked out.

class deeprootgen.statistics.summary_statistics.RootLengthDistribution(length_bins_cm=None, bins: int = 10, **kwargs)[source]

Histogram of complete valid-root lengths, one observation per organ.

class deeprootgen.statistics.summary_statistics.RootNumber(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.RootOrientationDistribution(**kwargs)[source]

Segment inclination and azimuth, plus net base-to-tip root direction.

Inclination 0° = vertically downward, 90° = horizontal, 180° = upward. Azimuth is measured counterclockwise from +x in the horizontal plane.

class deeprootgen.statistics.summary_statistics.RootingExtent(origin: tuple[float, float, float] | None = None, **kwargs)[source]

Maximum vertical depth, maximum radius and x/y spreads (cm).

class deeprootgen.statistics.summary_statistics.SummaryStatisticBase(length_source: str = 'geometric', **_)[source]

Base for root architecture statistics; accepts full node DataFrames.

calculate_statistic_per_layer(df: DataFrame, layer_decrement: int = 10)[source]

Midpoint-assigned approximation for scalar statistics.

Exact length-by-depth allocation is in DepthDistribution, and exact grid-layer RLD is in RootLengthDensity. Parent nodes are retained for graph geometry while non-layer child segments are masked out.

class deeprootgen.statistics.summary_statistics.TotalDiameter(**kwargs)[source]

Legacy sum of segment diameters (sensitive to graph subdivision).

class deeprootgen.statistics.summary_statistics.TotalLength(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.TotalSpecificRootLength(root_tissue_density: float, **kwargs)[source]

Whole-RSA length per dry mass (cm/g), not sum of segment SRLs.

class deeprootgen.statistics.summary_statistics.TotalVolume(**kwargs)[source]
class deeprootgen.statistics.summary_statistics.TotalWeight(root_tissue_density: float, **kwargs)[source]
class deeprootgen.statistics.summary_statistics.VerticalRootLengthDistribution(**kwargs)[source]

Root length (cm) allocated to vertical depth slabs.