"""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.
"""
# mypy: ignore-errors
from __future__ import annotations
from abc import ABC, abstractmethod
from pydoc import locate
from typing import Callable
import numpy as np
import pandas as pd
import plotly.express as px
import plotly.graph_objects as go
from scipy.spatial import ConvexHull, QhullError
px.defaults.template = "ggplot2"
_EPS = 1e-12
def _segments(
df: pd.DataFrame,
length_source: str = "geometric",
root_types: list[str] | None = None,
) -> pd.DataFrame:
"""Valid child segments, with their parent coordinates and geometry.
An invalid *parent point* is still retained as the start coordinate of a
valid child segment. The invalid flag is applied to the child segment,
as in the existing DeepRootGen voxel aggregation code.
"""
if length_source not in {"recorded", "geometric"}:
raise ValueError("length_source must be 'recorded' or 'geometric'.")
required = {
"node_id",
"parent_id",
"x",
"y",
"z",
"order",
"organ_id",
"segment_rank",
}
if length_source == "recorded":
required.add("length")
if root_types is not None:
required.add("root_type")
missing = required.difference(df.columns)
if missing:
raise ValueError(f"Missing root graph columns: {sorted(missing)}")
if df["node_id"].duplicated().any():
raise ValueError("node_id must be unique.")
out = df.loc[df["order"].gt(0) & df["parent_id"].isin(df["node_id"])].copy()
if "invalid_root" in out:
out = out.loc[~out["invalid_root"].fillna(False).astype(bool)].copy()
if root_types is not None:
out = out.loc[out["root_type"].isin(root_types)].copy()
parents = df[["node_id", "x", "y", "z", "organ_id", "order"]].rename(
columns={
"node_id": "parent_id",
"x": "parent_x",
"y": "parent_y",
"z": "parent_z",
"organ_id": "parent_organ_id",
"order": "parent_order",
}
)
out = out.merge(
parents, on="parent_id", how="left", validate="many_to_one", sort=False
)
for axis in "xyz":
out[f"d{axis}"] = out[axis].to_numpy(float) - out[f"parent_{axis}"].to_numpy(
float
)
out[f"mid_{axis}"] = (
out[axis].to_numpy(float) + out[f"parent_{axis}"].to_numpy(float)
) / 2
displacement = out[["dx", "dy", "dz"]].to_numpy(float)
geometric = np.linalg.norm(displacement, axis=1)
if not np.isfinite(geometric).all():
raise ValueError("Nonfinite root coordinates.")
if (geometric <= _EPS).any():
raise ValueError("Zero-length segment encountered in valid root graph.")
out["geometric_length_cm"] = geometric
if length_source == "geometric":
length = geometric
else:
length = out["length"].to_numpy(float)
if not np.isfinite(length).all() or (length < 0).any():
raise ValueError("Root segment lengths must be nonnegative and finite.")
out["segment_length_cm"] = length
for j, axis in enumerate("xyz"):
out[f"unit_{axis}"] = displacement[:, j] / geometric
return out
def _origin(
df: pd.DataFrame, origin: tuple[float, float, float] | None = None
) -> np.ndarray:
"""Use the supplied planting point or the first order-0 base node."""
if origin is not None:
arr = np.asarray(origin, dtype=float)
if arr.shape != (3,) or not np.isfinite(arr).all():
raise ValueError("origin must contain three finite coordinates.")
return arr
if "order" in df and "node_id" in df:
bases = df.loc[df["order"].eq(0)]
if len(bases):
if "parent_id" in df:
bases = pd.concat(
[bases.loc[~bases["parent_id"].isin(df["node_id"])], bases]
).drop_duplicates("node_id", keep="first")
return bases.iloc[0][["x", "y", "z"]].to_numpy(float)
return np.zeros(3)
def _bin_edges(bins, maximum: float) -> np.ndarray:
if isinstance(bins, (int, np.integer)):
if bins < 1:
raise ValueError("bins must be a positive integer.")
edges = np.linspace(0.0, max(float(maximum), 1.0), int(bins) + 1)
else:
edges = np.asarray(bins, dtype=float)
if (
edges.ndim != 1
or len(edges) < 2
or not np.all(np.diff(edges) > 0)
or edges[0] < 0
or not np.isfinite(edges[:-1]).all()
or np.isnan(edges[-1])
):
raise ValueError("Bin edges must be increasing, nonnegative and valid.")
return edges
def _length_distribution(
segments: pd.DataFrame,
edges: np.ndarray,
coordinate: str,
origin: np.ndarray,
) -> np.ndarray:
"""Allocate exact straight-segment length to depth slabs or radial rings.
Crossings with depth planes are linear. Crossings with radial cylinders
use quadratic intersections, so a segment can enter and leave one ring.
"""
result = np.zeros(len(edges) - 1, dtype=float)
for row in segments.itertuples(index=False):
a = np.array([row.parent_x, row.parent_y, row.parent_z], dtype=float)
delta = np.array([row.dx, row.dy, row.dz], dtype=float)
cuts = [0.0, 1.0]
if coordinate == "depth":
value0 = origin[2] - a[2]
dv = -delta[2]
if abs(dv) > _EPS:
cuts.extend((edges[np.isfinite(edges)] - value0) / dv)
def evaluate(t):
return value0 + dv * t
elif coordinate == "radius":
xy = a[:2] - origin[:2]
dxy = delta[:2]
A = float(np.dot(dxy, dxy))
B = 2.0 * float(np.dot(xy, dxy))
C0 = float(np.dot(xy, xy))
if A > _EPS:
for radius in edges[np.isfinite(edges)]:
C = C0 - radius**2
disc = B * B - 4 * A * C
if disc >= 0:
sq = np.sqrt(max(disc, 0.0))
cuts.extend([(-B - sq) / (2 * A), (-B + sq) / (2 * A)])
def evaluate(t):
return np.linalg.norm(xy + dxy * t)
else:
raise ValueError("coordinate must be 'depth' or 'radius'.")
cuts = np.unique(np.clip(np.asarray(cuts, dtype=float), 0, 1))
for lo, hi in zip(cuts[:-1], cuts[1:]):
if hi - lo <= _EPS:
continue
v = evaluate((lo + hi) / 2)
index = int(np.searchsorted(edges, v, side="right") - 1)
if 0 <= index < len(result):
result[index] += (hi - lo) * row.segment_length_cm
return result
def _distribution_table(edges: np.ndarray, lengths: np.ndarray, prefix: str):
total = lengths.sum()
fraction = lengths / total if total > 0 else np.zeros_like(lengths)
return pd.DataFrame(
{
f"{prefix}_min_cm": edges[:-1],
f"{prefix}_max_cm": edges[1:],
"root_length_cm": lengths,
"root_length_fraction": fraction,
"cumulative_root_length_fraction": np.cumsum(fraction),
}
)
def _root_count(segments: pd.DataFrame) -> int:
return int(segments["organ_id"].nunique())
def _mass(segments: pd.DataFrame, root_tissue_density: float | None) -> np.ndarray:
if "diameter" not in segments:
raise ValueError("Missing diameter column.")
diameter = segments["diameter"].to_numpy(float)
if not np.isfinite(diameter).all() or (diameter < 0).any():
raise ValueError("Diameters must be finite and nonnegative.")
if root_tissue_density is None:
if "root_tissue_density" not in segments:
raise ValueError(
"root_tissue_density must be supplied or present on nodes."
)
density = segments["root_tissue_density"].to_numpy(float)
else:
density = np.asarray(root_tissue_density, dtype=float)
if not np.isfinite(density).all() or (density <= 0).any():
raise ValueError("Root tissue density must be positive and finite.")
return (
np.pi
* (diameter / 2) ** 2
* segments["segment_length_cm"].to_numpy(float)
* density
)
[docs]
class SummaryStatisticBase(ABC):
"""Base for root architecture statistics; accepts full node DataFrames."""
def __init__(self, length_source: str = "geometric", **_) -> None:
self.statistic = ""
self.unit = ""
if length_source not in {"geometric", "recorded"}:
raise ValueError("Invalid length_source.")
self.length_source = length_source
def segments(self, df: pd.DataFrame) -> pd.DataFrame:
return _segments(df, self.length_source)
@abstractmethod
def calculate(self, df: pd.DataFrame):
raise NotImplementedError
def get_number_of_roots(self, df: pd.DataFrame) -> int:
return _root_count(self.segments(df))
[docs]
def calculate_statistic_per_layer(
self, df: pd.DataFrame, layer_decrement: int = 10
):
"""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.
"""
if layer_decrement <= 0:
raise ValueError("layer_decrement must be positive.")
segs = self.segments(df)
if segs.empty:
return [], np.array([])
n = int(
np.ceil(
max(0.0, -float(segs[["z", "parent_z"]].min().min())) / layer_decrement
)
)
tops = -np.arange(n) * layer_decrement
results = []
for top in tops:
selected = segs.loc[
(segs.mid_z <= top) & (segs.mid_z > top - layer_decrement), "node_id"
]
partial = df.copy()
invalid = (
partial["invalid_root"].fillna(False).astype(bool)
if "invalid_root" in partial
else False
)
partial["invalid_root"] = invalid | ~partial["node_id"].isin(selected)
results.append(self.calculate(partial))
return results, tops
def get_xy_comparison_data(
self, df: pd.DataFrame, n_elements: int = 10
) -> np.ndarray:
values, _ = self.calculate_statistic_per_layer(df)
return np.asarray(values[:n_elements])
def visualise(self, df: pd.DataFrame, layer_decrement: int = 10, **_) -> go.Figure:
values, tops = self.calculate_statistic_per_layer(df, layer_decrement)
fig = px.scatter(
x=values, y=-tops, title=f"{self.statistic} per soil layer (approximate)"
)
fig.update_layout(
xaxis_title=f"{self.statistic} ({self.unit})", yaxis_title="Depth (cm)"
)
fig.update_yaxes(autorange="reversed")
return fig
[docs]
class RootNumber(SummaryStatisticBase):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root number", "roots"
def calculate(self, df):
return self.get_number_of_roots(df)
[docs]
class TotalLength(SummaryStatisticBase):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Total root length", "cm"
def calculate(self, df):
return float(self.segments(df)["segment_length_cm"].sum())
[docs]
class AverageLength(SummaryStatisticBase):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Average length per root", "cm"
def calculate(self, df):
s = self.segments(df)
return (
float(s.segment_length_cm.sum() / len(s.organ_id.unique()))
if len(s)
else float("nan")
)
[docs]
class TotalVolume(SummaryStatisticBase):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Total root volume", "cm³"
def calculate(self, df):
s = self.segments(df)
return float((np.pi * (s.diameter / 2) ** 2 * s.segment_length_cm).sum())
[docs]
class AverageVolume(TotalVolume):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic = "Average volume per root"
def calculate(self, df):
n = self.get_number_of_roots(df)
return float(super().calculate(df) / n) if n else float("nan")
[docs]
class TotalDiameter(SummaryStatisticBase):
"""Legacy sum of segment diameters (sensitive to graph subdivision)."""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Total segment diameter (legacy)", "cm"
def calculate(self, df):
return float(self.segments(df)["diameter"].sum())
[docs]
class AverageDiameter(SummaryStatisticBase):
"""Length-weighted mean root-segment diameter."""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Length-weighted mean root diameter", "cm"
def calculate(self, df):
s = self.segments(df)
total = s.segment_length_cm.sum()
return (
float(np.dot(s.diameter, s.segment_length_cm) / total)
if total
else float("nan")
)
[docs]
class TotalSpecificRootLength(SummaryStatisticBase):
"""Whole-RSA length per dry mass (cm/g), not sum of segment SRLs."""
def __init__(self, root_tissue_density: float, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Specific root length", "cm/g"
self.root_tissue_density = root_tissue_density
def calculate(self, df):
s = self.segments(df)
m = _mass(s, self.root_tissue_density).sum()
return float(s.segment_length_cm.sum() / m) if m > 0 else float("nan")
[docs]
class AverageSpecificRootLength(TotalSpecificRootLength):
"""Arithmetic mean of organ-specific length/mass ratios (cm/g)."""
def __init__(self, root_tissue_density: float, **kwargs):
super().__init__(root_tissue_density, **kwargs)
self.statistic = "Average organ-specific root length"
def calculate(self, df):
s = self.segments(df).copy()
if s.empty:
return float("nan")
s["segment_mass_g"] = _mass(s, self.root_tissue_density)
roots = s.groupby("organ_id")[["segment_length_cm", "segment_mass_g"]].sum()
roots = roots.loc[roots.segment_mass_g > 0]
return (
float((roots.segment_length_cm / roots.segment_mass_g).mean())
if len(roots)
else float("nan")
)
[docs]
class TotalWeight(SummaryStatisticBase):
def __init__(self, root_tissue_density: float, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Total root dry mass", "g"
self.root_tissue_density = root_tissue_density
def calculate(self, df):
return float(_mass(self.segments(df), self.root_tissue_density).sum())
[docs]
class AverageWeight(TotalWeight):
def __init__(self, root_tissue_density: float, **kwargs):
super().__init__(root_tissue_density, **kwargs)
self.statistic = "Average root dry mass"
def calculate(self, df):
n = self.get_number_of_roots(df)
return float(super().calculate(df) / n) if n else float("nan")
[docs]
class ConvexHullArea(SummaryStatisticBase):
"""Surface area of the 3D convex hull, not projected horizontal area."""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "3D convex hull surface area", "cm²"
def calculate(self, df):
return _convex_measure(self.segments(df), "area")
[docs]
class ConvexHullVolume(SummaryStatisticBase):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "3D convex hull volume", "cm³"
def calculate(self, df):
return _convex_measure(self.segments(df), "volume")
def _convex_measure(s: pd.DataFrame, what: str) -> float:
if s.empty:
return float("nan")
points = np.unique(
np.vstack(
[
s[["x", "y", "z"]].to_numpy(float),
s[["parent_x", "parent_y", "parent_z"]].to_numpy(float),
]
),
axis=0,
)
if len(points) < 4:
return float("nan")
try:
return float(getattr(ConvexHull(points), what))
except QhullError:
return float("nan")
[docs]
class RootLengthDistribution(SummaryStatisticBase):
"""Histogram of complete valid-root lengths, one observation per organ."""
def __init__(self, length_bins_cm=None, bins: int = 10, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root length distribution", "roots"
self.length_bins_cm = length_bins_cm
self.bins = bins
def per_root(self, df):
s = self.segments(df)
if s.empty:
return pd.DataFrame(columns=["organ_id", "order", "root_length_cm"])
return s.groupby(["organ_id", "order"], as_index=False).agg(
root_length_cm=("segment_length_cm", "sum")
)
def calculate_df(self, df):
roots = self.per_root(df)
values = roots.root_length_cm.to_numpy(float)
edges = _bin_edges(
self.length_bins_cm if self.length_bins_cm is not None else self.bins,
float(values.max()) if len(values) else 0.0,
)
counts, _ = np.histogram(values, edges)
return pd.DataFrame(
{
"length_min_cm": edges[:-1],
"length_max_cm": edges[1:],
"root_count": counts,
}
)
def calculate(self, df):
return self.calculate_df(df)["root_count"].to_numpy()
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
table = self.calculate_df(df)
return px.bar(
table,
x="length_min_cm",
y="root_count",
title=self.statistic,
labels={"length_min_cm": "Root length bin start (cm)"},
)
[docs]
class RootDiameterDistribution(SummaryStatisticBase):
"""Length-weighted distribution by segment diameter (mm)."""
def __init__(self, diameter_bins_mm=None, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root length by diameter class", "cm"
if diameter_bins_mm is None:
diameter_bins_mm = [0, 0.5, 1, 2, 5, 10, 20, np.inf]
self.edges = _bin_edges(diameter_bins_mm, 0.0)
def calculate(self, df):
s = self.segments(df)
lengths, _ = np.histogram(
s.diameter.to_numpy(float) * 10,
bins=self.edges,
weights=s.segment_length_cm.to_numpy(float),
)
return lengths
def calculate_df(self, df):
lengths = self.calculate(df)
return pd.DataFrame(
{
"diameter_min_mm": self.edges[:-1],
"diameter_max_mm": self.edges[1:],
"root_length_cm": lengths,
"root_length_fraction": (
lengths / lengths.sum() if lengths.sum() else np.zeros_like(lengths)
),
}
)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
data = self.calculate_df(df)
return px.bar(
data, x="diameter_min_mm", y="root_length_cm", title=self.statistic
)
[docs]
class RootBranchingOrderDistribution(SummaryStatisticBase):
"""Counts and root lengths by topological order."""
def __init__(self, max_order: int | None = None, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root branching order distribution", "roots"
self.max_order = max_order
def calculate_df(self, df):
s = self.segments(df)
highest = self.max_order or (int(s.order.max()) if len(s) else 0)
orders = pd.DataFrame({"order": np.arange(1, highest + 1, dtype=int)})
if s.empty:
return orders.assign(root_count=0, root_length_cm=0.0)
counts = s.groupby("order").organ_id.nunique().rename("root_count")
lengths = s.groupby("order").segment_length_cm.sum().rename("root_length_cm")
return orders.join(counts, on="order").join(lengths, on="order").fillna(0)
def calculate(self, df):
return self.calculate_df(df).root_count.to_numpy()
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
return px.bar(
self.calculate_df(df), x="order", y="root_count", title=self.statistic
)
[docs]
class RootBranchingFrequency(SummaryStatisticBase):
"""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.
"""
def __init__(self, max_order: int | None = None, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root branching frequency", "branches/cm"
self.max_order = max_order
def calculate(self, df):
s = self.segments(df)
if s.empty:
return 0.0
highest = (
int(self.max_order)
if self.max_order is not None
else max(int(s.order.max()), 2)
)
# Only eligible parent-root orders contribute to the denominator.
parents = s.loc[s.order < highest]
# Count lateral roots originating from eligible parent orders.
bases = s.loc[
s.segment_rank.eq(1)
& s.order.gt(1)
& s.parent_order.eq(s.order - 1)
& s.parent_order.gt(0)
& s.parent_order.lt(highest)
& s.parent_organ_id.ne(s.organ_id)
]
denominator = float(parents.segment_length_cm.sum())
return (
float(bases.organ_id.nunique() / denominator)
if denominator > 0
else float("nan")
)
[docs]
class RootBranchingAngleDistribution(SummaryStatisticBase):
"""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.
"""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Lateral branching angles", "degrees"
def calculate_df(self, df):
s = self.segments(df)
bases = s.loc[s.segment_rank.eq(1) & s.order.gt(1)].copy()
parent_tangent = s[
["node_id", "organ_id", "order", "unit_x", "unit_y", "unit_z"]
].rename(
columns={
"node_id": "parent_id",
"organ_id": "incoming_organ_id",
"order": "incoming_order",
"unit_x": "parent_ux",
"unit_y": "parent_uy",
"unit_z": "parent_uz",
}
)
bases = bases.merge(
parent_tangent, on="parent_id", how="inner", validate="many_to_one"
)
bases = bases.loc[
bases.incoming_order.eq(bases.order - 1)
& bases.incoming_organ_id.ne(bases.organ_id)
].copy()
dot = (
bases.unit_x * bases.parent_ux
+ bases.unit_y * bases.parent_uy
+ bases.unit_z * bases.parent_uz
)
bases["branching_angle_deg"] = np.degrees(np.arccos(np.clip(dot, -1, 1)))
return (
bases[
[
"organ_id",
"order",
"parent_id",
"incoming_organ_id",
"branching_angle_deg",
]
]
.rename(columns={"incoming_organ_id": "parent_organ_id"})
.reset_index(drop=True)
)
def calculate(self, df):
return self.calculate_df(df).branching_angle_deg.to_numpy(float)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
return px.histogram(
self.calculate_df(df), x="branching_angle_deg", title=self.statistic
)
[docs]
class RootOrientationDistribution(SummaryStatisticBase):
"""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.
"""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Segment inclination distribution", "degrees"
def calculate_df(self, df):
s = self.segments(df).copy()
s["inclination_deg"] = np.degrees(np.arccos(np.clip(-s.unit_z, -1, 1)))
s["azimuth_deg"] = (np.degrees(np.arctan2(s.dy, s.dx)) + 360) % 360
s["vertical_downward_fraction"] = -s.unit_z
s["horizontal_fraction"] = np.hypot(s.unit_x, s.unit_y)
return s[
[
"node_id",
"organ_id",
"order",
"segment_length_cm",
"inclination_deg",
"azimuth_deg",
"vertical_downward_fraction",
"horizontal_fraction",
]
]
def per_root(self, df):
s = self.segments(df)
rows = []
for (organ_id, order), g in s.groupby(["organ_id", "order"]):
first = g.sort_values("segment_rank").iloc[0]
last = g.sort_values("segment_rank").iloc[-1]
# An invalid/missing segment can leave a discontinuous organ.
ranks = np.sort(g["segment_rank"].to_numpy(int))
if ranks[0] != 1 or not np.all(np.diff(ranks) == 1):
continue
v = last[["x", "y", "z"]].to_numpy(float) - first[
["parent_x", "parent_y", "parent_z"]
].to_numpy(float)
norm = np.linalg.norm(v)
if norm <= _EPS:
continue
v /= norm
rows.append(
{
"organ_id": organ_id,
"order": order,
"inclination_deg": float(
np.degrees(np.arccos(np.clip(-v[2], -1, 1)))
),
"azimuth_deg": float(
(np.degrees(np.arctan2(v[1], v[0])) + 360) % 360
),
"vertical_downward_fraction": float(-v[2]),
"net_displacement_cm": float(norm),
}
)
return pd.DataFrame(
rows,
columns=[
"organ_id",
"order",
"inclination_deg",
"azimuth_deg",
"vertical_downward_fraction",
"net_displacement_cm",
],
)
def calculate(self, df):
return self.calculate_df(df).inclination_deg.to_numpy(float)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
s = self.calculate_df(df)
return px.histogram(
s,
x="inclination_deg",
y="segment_length_cm",
histfunc="sum",
title="Root length by segment inclination",
)
[docs]
class RootingExtent(SummaryStatisticBase):
"""Maximum vertical depth, maximum radius and x/y spreads (cm)."""
def __init__(self, origin: tuple[float, float, float] | None = None, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Rooting extent", "cm"
self.origin = origin
def calculate_df(self, df):
s = self.segments(df)
if s.empty:
return pd.DataFrame(
[
dict(
max_depth_cm=0.0,
max_radius_cm=0.0,
x_spread_cm=0.0,
y_spread_cm=0.0,
bounding_circle_diameter_cm=0.0,
)
]
)
coords = np.vstack(
[
s[["x", "y", "z"]].to_numpy(float),
s[["parent_x", "parent_y", "parent_z"]].to_numpy(float),
]
)
origin = _origin(df, self.origin)
depth = np.maximum(origin[2] - coords[:, 2], 0)
radial = np.linalg.norm(coords[:, :2] - origin[:2], axis=1)
return pd.DataFrame(
[
{
"max_depth_cm": float(depth.max()),
"max_radius_cm": float(radial.max()),
"x_spread_cm": float(np.ptp(coords[:, 0])),
"y_spread_cm": float(np.ptp(coords[:, 1])),
# Diameter of a circle centred on the origin containing the RSA;
# not the maximum distance between any pair of roots.
"bounding_circle_diameter_cm": float(2 * radial.max()),
}
]
)
def calculate(self, df):
return self.calculate_df(df).iloc[0].to_numpy(float)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
vals = self.calculate_df(df).iloc[0]
return px.bar(
x=vals.index.tolist(), y=vals.to_numpy(float), title=self.statistic
)
[docs]
class DepthDistribution(SummaryStatisticBase):
"""Cumulative *root length* fraction versus depth below planting origin."""
def __init__(self, origin=None, bins=10, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Cumulative root length by depth", "fraction"
self.origin = origin
self.bins = bins
def calculate_df(self, df, bins=None):
s = self.segments(df)
o = _origin(df, self.origin)
maximum = (
max(0.0, float(o[2] - s[["z", "parent_z"]].min().min())) if len(s) else 0.0
)
edges = _bin_edges(self.bins if bins is None else bins, maximum)
lengths = _length_distribution(s, edges, "depth", o)
return _distribution_table(edges, lengths, "depth")
def calculate(self, df, bins=None):
result = self.calculate_df(df, bins)
return (
np.r_[0.0, result.cumulative_root_length_fraction.to_numpy()],
np.r_[result.depth_min_cm.iloc[0], result.depth_max_cm.to_numpy()],
)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df, bins=n_elements)[0][1:]
def visualise(self, df, bins=None):
cdf, edges = self.calculate(df, bins)
fig = px.line(x=cdf, y=edges, markers=True, title=self.statistic)
fig.update_layout(
xaxis_title="Cumulative root length fraction", yaxis_title="Depth (cm)"
)
fig.update_yaxes(autorange="reversed")
return fig
[docs]
class RadialDistribution(SummaryStatisticBase):
"""Cumulative *root length* fraction versus actual horizontal radius."""
def __init__(self, origin=None, bins=10, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Cumulative root length by radius", "fraction"
self.origin = origin
self.bins = bins
def calculate_df(self, df, bins=None):
s = self.segments(df)
o = _origin(df, self.origin)
coords = (
np.vstack(
[
s[["x", "y"]].to_numpy(float),
s[["parent_x", "parent_y"]].to_numpy(float),
]
)
if len(s)
else np.empty((0, 2))
)
maximum = (
float(np.linalg.norm(coords - o[:2], axis=1).max()) if len(coords) else 0.0
)
edges = _bin_edges(self.bins if bins is None else bins, maximum)
lengths = _length_distribution(s, edges, "radius", o)
return _distribution_table(edges, lengths, "radius")
def calculate(self, df, bins=None):
result = self.calculate_df(df, bins)
return (
np.r_[0.0, result.cumulative_root_length_fraction.to_numpy()],
np.r_[result.radius_min_cm.iloc[0], result.radius_max_cm.to_numpy()],
)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df, bins=n_elements)[0][1:]
def visualise(self, df, bins=None):
cdf, edges = self.calculate(df, bins)
fig = px.line(x=cdf, y=edges, markers=True, title=self.statistic)
fig.update_layout(
xaxis_title="Cumulative root length fraction", yaxis_title="Radius (cm)"
)
return fig
[docs]
class VerticalRootLengthDistribution(DepthDistribution):
"""Root length (cm) allocated to vertical depth slabs."""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root length by depth", "cm"
def calculate(self, df, bins=None):
return self.calculate_df(df, bins).root_length_cm.to_numpy(float)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df, bins=n_elements)
def visualise(self, df, bins=None):
data = self.calculate_df(df, bins)
fig = px.bar(
data,
x="root_length_cm",
y="depth_min_cm",
orientation="h",
title=self.statistic,
)
fig.update_yaxes(autorange="reversed")
return fig
[docs]
class HorizontalRootLengthDistribution(RadialDistribution):
"""Root length (cm) allocated to concentric horizontal radial rings."""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.statistic, self.unit = "Root length by horizontal radius", "cm"
def calculate(self, df, bins=None):
return self.calculate_df(df, bins).root_length_cm.to_numpy(float)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df, bins=n_elements)
def visualise(self, df, bins=None):
return px.bar(
self.calculate_df(df, bins),
x="radius_min_cm",
y="root_length_cm",
title=self.statistic,
)
[docs]
class RootLengthDensity(SummaryStatisticBase):
"""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.
"""
def __init__(
self,
soil_df: pd.DataFrame,
length_source="geometric",
root_types=None,
**kwargs,
):
super().__init__(length_source=length_source, **kwargs)
self.statistic, self.unit = "Root length density", "cm/cm³"
self.root_types = root_types
self.edges = [
np.sort(soil_df[axis].unique().astype(float)) for axis in ("x", "y", "z")
]
if any(
len(e) < 2 or not np.isfinite(e).all() or not (np.diff(e) > 0).all()
for e in self.edges
):
raise ValueError("Invalid soil grid boundaries.")
self.shape = tuple(len(e) - 1 for e in self.edges)
self.soil_volume = float(np.prod([e[-1] - e[0] for e in self.edges]))
def _voxel_lengths(self, df):
segs = _segments(df, self.length_source, self.root_types)
result = np.zeros(self.shape, dtype=float)
for row in segs.itertuples(index=False):
a = np.array([row.parent_x, row.parent_y, row.parent_z], dtype=float)
d = np.array([row.dx, row.dy, row.dz], dtype=float)
lo, hi = 0.0, 1.0
for j, edge in enumerate(self.edges):
if abs(d[j]) <= _EPS:
if a[j] < edge[0] or a[j] > edge[-1]:
hi = -1.0
break
else:
intersection = (edge[[0, -1]] - a[j]) / d[j]
lo = max(lo, float(np.min(intersection)))
hi = min(hi, float(np.max(intersection)))
if hi - lo <= _EPS:
continue
cuts = [lo, hi]
for j, edge in enumerate(self.edges):
if abs(d[j]) > _EPS:
t = (edge[1:-1] - a[j]) / d[j]
cuts.extend(t[(t > lo + _EPS) & (t < hi - _EPS)].tolist())
cuts = np.sort(cuts)
for start, end in zip(cuts[:-1], cuts[1:]):
if end - start <= _EPS:
continue
midpoint = a + d * ((start + end) / 2)
index = tuple(
int(
np.clip(
np.searchsorted(edge, midpoint[j], side="right") - 1,
0,
len(edge) - 2,
)
)
for j, edge in enumerate(self.edges)
)
result[index] += (end - start) * row.segment_length_cm
return result
def calculate(self, df):
return float(self._voxel_lengths(df).sum() / self.soil_volume)
def calculate_per_voxel(self, df):
length = self._voxel_lengths(df)
ix, iy, iz = np.indices(self.shape).reshape(3, -1)
x, y, z = self.edges
volume = np.diff(x)[ix] * np.diff(y)[iy] * np.diff(z)[iz]
return pd.DataFrame(
{
"column": ix,
"row": iy,
"layer": iz,
"x_min": x[ix],
"x_max": x[ix + 1],
"y_min": y[iy],
"y_max": y[iy + 1],
"z_min": z[iz],
"z_max": z[iz + 1],
"root_length_cm": length.ravel(),
"soil_volume_cm3": volume,
"rld_cm_cm3": length.ravel() / volume,
}
)
@staticmethod
def aggregate(voxels, by):
groups = {
"row": ["row", "y_min", "y_max"],
"column": ["column", "x_min", "x_max"],
"layer": ["layer", "z_min", "z_max"],
}
if by not in groups:
raise ValueError("by must be 'row', 'column', or 'layer'.")
result = voxels.groupby(groups[by], as_index=False)[
["root_length_cm", "soil_volume_cm3"]
].sum()
result["rld_cm_cm3"] = result.root_length_cm / result.soil_volume_cm3
if by == "layer":
result["depth_top_cm"] = -result.z_max
result["depth_bottom_cm"] = -result.z_min
result = result.sort_values("depth_top_cm").reset_index(drop=True)
return result
def calculate_per_row(self, df):
return self.aggregate(self.calculate_per_voxel(df), "row")
def calculate_per_column(self, df):
return self.aggregate(self.calculate_per_voxel(df), "column")
def calculate_per_layer(self, df):
return self.aggregate(self.calculate_per_voxel(df), "layer")
[docs]
def calculate_statistic_per_layer(self, df, layer_decrement=10):
layers = self.calculate_per_layer(df)
return layers.rld_cm_cm3.tolist(), layers.z_max.to_numpy()
def visualise(self, df, **_):
layers = self.calculate_per_layer(df)
fig = px.scatter(
layers,
x="rld_cm_cm3",
y="depth_top_cm",
title="Root length density by soil layer",
)
fig.update_layout(xaxis_title="RLD (cm/cm³)", yaxis_title="Soil depth (cm)")
fig.update_yaxes(autorange="reversed")
return fig
[docs]
class RootDryMassByDiameter(SummaryStatisticBase):
"""Segment dry mass (g) per diameter class (mm)."""
def __init__(
self,
diameter_bins_mm: list[float],
root_tissue_density: float | None = None,
**kwargs,
):
super().__init__(**kwargs)
self.statistic, self.unit = "Root dry mass by diameter", "g"
self.diameter_bins_mm = _bin_edges(diameter_bins_mm, 0.0)
self.root_tissue_density = root_tissue_density
def calculate(self, df):
s = self.segments(df)
mass = _mass(s, self.root_tissue_density)
return np.histogram(
s.diameter.to_numpy(float) * 10, bins=self.diameter_bins_mm, weights=mass
)[0]
def calculate_df(self, df):
return pd.DataFrame(
{
"diameter_min_mm": self.diameter_bins_mm[:-1],
"diameter_max_mm": self.diameter_bins_mm[1:],
"dry_mass_g": self.calculate(df),
}
)
def get_xy_comparison_data(self, df, n_elements=10):
return self.calculate(df)[:n_elements]
def visualise(self, df, **_):
data = self.calculate_df(df)
labels = [
f"{a:g}–{b:g}" if np.isfinite(b) else f"≥{a:g}"
for a, b in zip(data.diameter_min_mm, data.diameter_max_mm)
]
return px.bar(
x=labels,
y=data.dry_mass_g,
title=self.statistic,
labels={"x": "Root diameter (mm)", "y": "Root dry mass (g)"},
)
def get_summary_statistic_func(summary_statistic: str) -> Callable:
name = summary_statistic.replace("_", " ").title().replace(" ", "")
return locate(f"deeprootgen.statistics.summary_statistics.{name}")
def get_summary_statistics() -> list[dict]:
names = [
"root_number",
"total_volume",
"average_volume",
"total_length",
"average_length",
"total_diameter",
"average_diameter",
"root_length_distribution",
"root_diameter_distribution",
"root_branching_order_distribution",
"root_branching_frequency",
"root_branching_angle_distribution",
"root_orientation_distribution",
"rooting_extent",
"depth_distribution",
"radial_distribution",
"vertical_root_length_distribution",
"horizontal_root_length_distribution",
"root_length_density",
"root_dry_mass_by_diameter",
"total_specific_root_length",
"average_specific_root_length",
"total_weight",
"average_weight",
"convex_hull_area",
"convex_hull_volume",
]
return [
{"value": value, "label": value.replace("_", " ").title()} for value in names
]