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.MeanAbsoluteError(**_)[source]
The mean absolute error distance.
- class deeprootgen.statistics.distance_metrics.MeanAbsolutePercentageError(**_)[source]
The mean absolute percentage error distance.
- class deeprootgen.statistics.distance_metrics.MeanPinballLoss(**_)[source]
The mean pinball loss distance.
- class deeprootgen.statistics.distance_metrics.MeanSquaredError(**_)[source]
The mean squared error distance.
- class deeprootgen.statistics.distance_metrics.MedianAbsoluteError(**_)[source]
The median absolute error distance.
- class deeprootgen.statistics.distance_metrics.RootMeanSquaredError(**_)[source]
The root mean squared error distance.
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.AverageSpecificRootLength(root_tissue_density: float, **kwargs)[source]
Arithmetic mean of organ-specific length/mass ratios (cm/g).
- 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.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.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.TotalSpecificRootLength(root_tissue_density: float, **kwargs)[source]
Whole-RSA length per dry mass (cm/g), not sum of segment SRLs.