Source code for deeprootgen.utils.branching

"""Utilities for sampling lateral-root branching locations."""

import numpy as np


[docs] def sample_branch_sites( parent_xyz: np.ndarray, interbranch_distance: float, rng: np.random.Generator, floor_threshold: float = 0.4, ceiling_threshold: float = 0.9, max_branches: int | None = None, log_sd: float = 0.2, ) -> list[float]: """ Sample lateral-root insertion positions along a parent root. Parameters ---------- parent_xyz : np.ndarray Ordered 3D coordinates of the parent root, including its basal origin and apex, in centimetres. interbranch_distance : float Mean distance between successive lateral-root insertion positions, in centimetres. rng : np.random.Generator Random number generator. floor_threshold : float Fraction of parent-root length where branching begins. ceiling_threshold : float Fraction of parent-root length where branching ends. max_branches : int or None Maximum number of lateral branches. None means no explicit upper limit. log_sd : float Log-scale standard deviation of interbranch spacing. Returns ------- list[float] Insertion positions measured in centimetres along the parent root's cumulative arc length. """ xyz = np.asarray(parent_xyz, dtype=float) # -------------------------------------------------- # Validate inputs # -------------------------------------------------- if xyz.ndim != 2 or xyz.shape[1] != 3 or len(xyz) < 2: raise ValueError("parent_xyz must have shape (n_points >= 2, 3).") if not np.isfinite(xyz).all(): raise ValueError("Parent coordinates must be finite.") if not np.isfinite(interbranch_distance) or interbranch_distance <= 0: raise ValueError("interbranch_distance must be positive and finite.") if not 0 <= floor_threshold < ceiling_threshold <= 1: raise ValueError("Expected 0 <= floor_threshold < ceiling_threshold <= 1.") if not np.isfinite(log_sd) or log_sd < 0: raise ValueError("log_sd must be finite and nonnegative.") if max_branches is not None: if not isinstance(max_branches, (int, np.integer)): raise TypeError("max_branches must be an integer.") if max_branches < 0: raise ValueError("max_branches must be nonnegative.") if max_branches == 0: return [] # -------------------------------------------------- # Calculate parent-root arc length # -------------------------------------------------- segment_lengths = np.linalg.norm( np.diff(xyz, axis=0), axis=1, ) if np.any(segment_lengths <= 1e-12): raise ValueError("Parent root contains zero-length segments.") total_length = float(segment_lengths.sum()) # Eligible branching region. start = floor_threshold * total_length end = ceiling_threshold * total_length # -------------------------------------------------- # Sample stochastic insertion positions # -------------------------------------------------- sites = [] # Randomise the initial branching position. position = start + rng.uniform(0.0, interbranch_distance) while position < end: sites.append(float(position)) # Stop after reaching the branch-count cap. if max_branches is not None and len(sites) >= max_branches: break # Lognormal distribution with arithmetic mean # equal to interbranch_distance. spacing = interbranch_distance * rng.lognormal( mean=-0.5 * log_sd**2, sigma=log_sd, ) position += spacing return sites