Model

Graph

Contains the hierarchical graph representation of the root system.

This module defines the hierarchical graph representation of the root system. This includes integration with NetworkX and PyTorch Geometric.

class deeprootgen.model.hgraph.RootEdge(G: RootSystemGraph, edge_data: RootEdgeModel)

An edge within the hierarchical graph representation of the root system.

as_dict() → dict

Return the graph edge as a dictionary.

Returns:

dict:

The edge as a dictionary.

class deeprootgen.model.hgraph.RootNode(G: RootSystemGraph, node_data: RootNodeModel)

A node within the hierarchical graph representation of the root system.

add_child_node(child_data: RootNodeModel, new_organ: bool = False) → RootNode

Add a child node to the hierarchical graph.

Args:

child_data (RootNodeModel):

The node data for the child node.

new_organ (bool):

Whether the new child node belongs to a new plant organ.

Returns:

RootNode:

The child node.

as_dict() → dict

Return the graph node as a dictionary.

Returns:

dict:

The node as a dictionary.

class deeprootgen.model.hgraph.RootSystemGraph

The hierarchical graph representation of the root system.

add_edge(edge_data: RootEdgeModel) → RootEdge

Construct a new RootEdge.

Args:

node_data (RootEdgeModel):

The root edge data model.

Returns:

RootEdge:

The new RootEdge.

add_node(node_data: RootNodeModel) → RootNode

Construct a new RootNode.

Args:

node_data (RootNodeModel):

The root node data model.

Returns:

RootNode:

The new RootNode.

as_df() → tuple

Return the graph as a tuple of node and edge dataframes.

Returns:

tuple:

The graph as a tuple of node and edge dataframes.

as_dict() → tuple

Return the graph as a tuple of node and edge lists.

Returns:

tuple:

The graph as a tuple of node and edge lists.

as_networkx(node_df: DataFrame | None = None, edge_df: DataFrame | None = None, drop: bool = False) → Graph

Return the graph as a NetworkX graph.

Args:

node_df (pd.DataFrame, optional):

The node dataframe. Defaults to None.

edge_df (pd.DataFrame, optional):

The edge dataframe. Defaults to None.

drop (bool, optional):

Whether to drop the node ID index. Defaults to False.

Returns:

tuple:

The graph in NetworkX format.

as_torch(node_df: DataFrame | None = None, edge_df: DataFrame | None = None, drop: bool = False) → Data

Return the graph as a PyTorch Geometric graph dataset.

Args:

node_df (pd.DataFrame, optional):

The node dataframe. Defaults to None.

edge_df (pd.DataFrame, optional):

The edge dataframe. Defaults to None.

drop (bool, optional):

Whether to drop the node ID index. Defaults to False.

Returns:

tuple:

The graph as a PyTorch Geometric graph dataset.

from_content_string(observed_data_content: str, raw_edge_content: str) → tuple

Contruct the node and edge dataframes from raw content strings.

Args:

observed_data_content (str):

The node content.

raw_edge_content (str):

The edge content.

Returns:

tuple:

The node and edge dataframes.

increment_node_id() → int

Increment the node ID.

Returns:

int:

The node ID prior to incrementation.

increment_organ_id() → int

Increment the organ ID.

Returns:

int:

The organ ID prior to incrementation.

deeprootgen.model.hgraph.process_graph(G: Graph, organ_keys: str, transform: Compose) → tuple[Tensor, Tensor]

Process a new NetworkX graph.

Args:

G (nx.Graph):

The NetworkX graph.

organ_keys (str):

The list of organ keys within the graph data object.

transform (T.Compose)

The composition of graph transformations.

Returns:

tuple:

The node and edge features.

Root

Contains the underlying root system simulation model.

This module defines the root system architecture simulation model for constructing 3D root systems.

class deeprootgen.model.root.RootOrgan(parent_node: RootNode, input_parameters: RootSimulationModel, root_type: RootTypeModel, simulation_tag: str, rng: Generator)

A single root organ within the root system.

add_child_node(parent_node: RootNode, diameters: ndarray, lengths: ndarray, coordinates: ndarray, root_type: RootTypeModel, root_tissue_density: float, i: int, new_organ: bool = False) → RootNode

Add a new child node to the root organ.

Args:

parent_node (RootNode):

The parent node of the root organ.

diameters (np.ndarray):

The array of segment diameters.

lengths (np.ndarray):

The array of segment lengths.

coordinates (np.ndarray):

The 3D coordinates.

root_type (RootTypeModel):

The root type data model.

root_tissue_density (float):

The root tissue density (g/cm3)

i (int):

The current array index.

new_organ (bool, optional):

Whether the node belongs to a new root organ. Defaults to False.

Returns:

RootNode:

The child node.

calculate_mass() → float

Calculate the mass of the root organ.

Returns:

float:

The mass.

cascading_set_invalid_root() → None

Specify that the root and its children are invalid.

cascading_to_world_origin() → None

Translate all child nodes to the world origin.

cascading_transform() → None

Apply the transformation matrix for the organ and child organs.

cascading_update_transform(roll: float = 0, pitch: float = 0, yaw: float = 0, translation: List[float] = [0, 0, 0], reflect: List[float] = [1, 1, 1, 1], scale: List[float] = [1, 1, 1, 1]) → None

Update the transformation matrix for the organ and child organs.

Args:

roll (float, optional):

The roll transform in degrees. Defaults to 0.

pitch (float, optional):

The pitch transform in degrees. Defaults to 0.

yaw (float, optional):

The yaw transform in degrees. Defaults to 0.

translation (List[float], optional):

The translation transform in degrees. Defaults to [0, 0, 0].

reflect (List[float], optional):

The reflect transform in degrees. Defaults to [1, 1, 1, 1].

scale (List[float], optional):

The scale transform in degrees. Defaults to [1, 1, 1, 1].

construct_root(segments_per_root: int, apex_diameter: int, root_tissue_density: float) → List[RootNode]

Construct all root segments for the root organ.

Args:

segments_per_root (int):

The number of segments for a single root organ.

apex_diameter (int):

The diameter of the root apex.

root_tissue_density (float):

The root tissue density (g/cm3)

Returns:

List[RootNode]:

The root segments for the root organ.

construct_root_from_parent(segments_per_root: int, apex_diameter: int) → List[RootNode]

Construct root segments for the root organ, inheriting plant properties from the parent organ.

Args:

segments_per_root (int):

The number of segments for a single root organ.

apex_diameter (int):

The diameter of the root apex.

Returns:

List[RootNode]:

The root segments for the root organ.

get_apex_coordinates() → ndarray

Get the apex coordinates of the current root.

Returns:

np.ndarray:

The apex coordinates.

get_coordinates(as_array: bool = True) → ndarray

Get the coordinates of the root segments.

Args:

as_array (bool, optional):

Return the coordinates as a Numpy array. Defaults to True.

Returns:

np.ndarray:

The coordinates of the root segments

get_diameters(as_array: bool = True) → ndarray

Get the diameters of the root segments.

Args:

as_array (bool, optional):

Return the coordinates as a Numpy array. Defaults to True.

Returns:

np.ndarray:

The coordinates of the root segments

get_lengths(as_array: bool = True) → ndarray

Get the lengths of the root segments.

Args:

as_array (bool, optional):

Return the coordinates as a Numpy array. Defaults to True.

Returns:

np.ndarray:

The coordinates of the root segments

get_local_origin() → ndarray

Get the origin of the current root.

Returns:

np.ndarray:

The local origin.

get_parent_origin() → ndarray

Get the origin of the parent node.

Returns:

np.ndarray:

The origin.

grow(simulation: RootSystemSimulation, input_parameters: RootSimulationModel) → None

Grow the root organ.

Args:

simulation (RootSystemSimulation):

The root simulation model.

input_parameters (RootSimulationModel):

The root simulation parameters.

init_diameters(segments_per_root: int, apex_diameter: int) → ndarray

Initialise root diameters for the root organ.

Args:

segments_per_root (int):

The number of segments for a single root organ.

apex_diameter (int):

The diameter of the root apex.

init_lengths(segments_per_root: int) → ndarray

Initialise root lengths for the root organ.

Args:

segments_per_root (int):

The number of segments for a single root organ.

length_range (tuple[float]):

The minimum and maximum value for the segment lengths.

init_segment_coordinates(segments_per_root: int, lengths: ndarray) → ndarray

Initialise the coordinates of the root segments.

Args:

segments_per_root (int):

The number of segments for a single root organ.

lengths (np.ndarray):

The lengths of each root segment.

Returns:

np.ndarray:

The 3D root segment coordinates.

reset_transform() → ndarray

Reset the transformation matrix.

Returns:

np.ndarray:

The reset transformation matrix.

set_coordinates(coordinates: list[tuple]) → ndarray

Get the coordinates of the root segments.

Args:

as_array (bool, optional):

Return the coordinates as a Numpy array. Defaults to True.

Returns:

np.ndarray:

The coordinates of the root segments

set_invalid_root() → None

Specify that the root is invalid.

transform() → ndarray

Apply the transformation matrix to the root system coordinates.

Returns:

np.ndarray:

The transformation matrix.

update_transform(roll: float = 0, pitch: float = 0, yaw: float = 0, translation: List[float] = [0, 0, 0], reflect: List[float] = [1, 1, 1, 1], scale: List[float] = [1, 1, 1, 1]) → ndarray

Update the transformation matrix.

Args:

roll (float, optional):

The roll transform in degrees. Defaults to 0.

pitch (float, optional):

The pitch transform in degrees. Defaults to 0.

yaw (float, optional):

The yaw transform in degrees. Defaults to 0.

translation (List[float], optional):

The translation transform in degrees. Defaults to [0, 0, 0].

reflect (List[float], optional):

The reflect transform in degrees. Defaults to [1, 1, 1, 1].

scale (List[float], optional):

The scale transform in degrees. Defaults to [1, 1, 1, 1].

Returns:

np.ndarray:

The updated transformation matrix.

validate(no_root_zone: float, pitch: int = 90, max_attempts: int = 50) → None

Validate the plausibility of the root organ.

Args:

no_root_zone (float):

The minimum depth threshold for root growth.

pitch (int, optional):

Pitch in degrees to rotate roots. Defaults to 90.

max_attempts (int, optional):

Maximum number of validation attempts. Defaults to 50.

class deeprootgen.model.root.RootSystemSimulation(simulation_tag: str = 'default', random_seed: int | None = None)

The root system architecture simulation model.

get_yaw(number_of_roots: int) → tuple

Get the yaw for rotating the root organs.

Args:

number_of_roots (int):

The number of roots.

Returns:

tuple:

The yaw and base yaw.

grow(simulation: RootSimulationModel, input_parameters: RootSimulationModel) → None

Model the growth of root organs.

Args:

simulation (RootSimulationModel):

The root simulation model.

input_parameters (RootSimulationModel):

The simulation input parameters.

init_fig(input_parameters: RootSimulationModel) → Figure | None

Initialise the root system figure.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

Returns:

go.Figure | None:

The root system visualisation.

init_organs(input_parameters: RootSimulationModel) → Dict[str, List[RootOrgan]]

Initialise the root organs for the simulation.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

Returns:

Dict[str, List[RootOrgan]]:

The initialised root organs.

plot_hierarchical_graph(G: Graph, feature_key: str = 'x', x_key: str = 'x', y_key: str = 'y', z_key: str = 'z') → Figure

Create a visualisation of hierarchical graph representation of the root system.

Args:

G (nx.Graph):

The NetworkX graph.

feature_key (str, optional):

The node features key. Defaults to ‘x’.

x_key (str, optional):

The node features key. Defaults to ‘x’.

y_key (str, optional):

The node features key. Defaults to ‘y’.

z_key (str, optional):

The node features key. Defaults to ‘z’.

Returns:

go.Figure:

The visualisation of the hierarchical graph representation.

plot_root_system(fig: Figure, node_df: DataFrame) → Figure

Create a visualisation of the root system.

Args:

fig (int):

The base plotly figure.

node_df (pd.DataFrame):

The root node dataframe.

Returns:

go.Figure:

The visualisation of the root system.

position_primary_roots(input_parameters: RootSimulationModel) → None

Position primary roots about the origin.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

position_secondary_roots(input_parameters: RootSimulationModel) → None

Position secondary roots about the origin.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

run(input_parameters: RootSimulationModel) → None

Run a root system architecture simulation.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

Returns:

dict:

The simulation results.

validate(input_parameters: RootSimulationModel, pitch: int = 45) → None

Validate the plausibility of the root system.

Args:

input_parameters (RootSimulationModel):

The root simulation data model.

pitch (int, optional):

Pitch in degrees to rotate roots. Defaults to 90.

Soil

Contains the soil component of the root system simulation.

This module defines the soil component of the root system architecture simulation model for constructing 3D root systems.

class deeprootgen.model.soil.Soil

The soil surrounding the root system.

create_soil_fig(soil_df: DataFrame) → Figure

Create a figure from a soil grid.

Args:

soil_df (pd.DataFrame):

The soil voxel grid dataframe.

Returns:

go.Figure:

The soil grid figure.

create_soil_grid(soil_layer_height: float, soil_n_layers: int, soil_layer_width: float, soil_n_cols: int) → DataFrame

Create a soil voxel grid.

Args:

soil_layer_height (float):

The height per vertical soil layer.

soil_n_layers (int):

The number of vertical soil layers.

soil_layer_width (float):

The width per horizontal soil layers/columns.

soil_n_cols (int): _description_

The number of horizontal soil layers/columns.

Returns:

pd.DataFrame:

The soil voxel grid dataframe.