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)[source]

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

as_dict() → dict[source]

Return the graph edge as a dictionary.

Returns:
dict:

The edge as a dictionary.

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

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

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

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[source]

Return the graph node as a dictionary.

Returns:
dict:

The node as a dictionary.

class deeprootgen.model.hgraph.RootSystemGraph[source]

The hierarchical graph representation of the root system.

add_edge(edge_data: RootEdgeModel) → RootEdge[source]

Construct a new RootEdge.

Args:
node_data (RootEdgeModel):

The root edge data model.

Returns:
RootEdge:

The new RootEdge.

add_node(node_data: RootNodeModel) → RootNode[source]

Construct a new RootNode.

Args:
node_data (RootNodeModel):

The root node data model.

Returns:
RootNode:

The new RootNode.

as_df() → tuple[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Increment the node ID.

Returns:
int:

The node ID prior to incrementation.

increment_organ_id() → int[source]

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][source]

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)[source]

One root organ and its ordered segment nodes.

add_child_organ(floor_threshold: float = 0.4, ceiling_threshold: float = 0.9) → RootOrgan[source]

Create daughter organ at the next precomputed insertion node.

Threshold arguments remain for API compatibility. The thresholds were applied earlier by _prepare_branch_nodes.

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

Construct primary root, inserting daughter attachment nodes first.

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

Construct higher-order root, with additional attachment nodes if needed.

grow(simulation: RootSystemSimulation, input_parameters: RootSimulationModel) → None[source]

Grow this root organ (retained from original; not called by run()).

init_segment_coordinates(segments_per_root: int, lengths: ndarray) → ndarray[source]

Generate local centreline points with geometric segment lengths.

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

The root-system architecture simulation model.

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

Construct organs; daughters attach at sampled parent arc-length sites.

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[source]

The soil surrounding the root system.

create_soil_fig(soil_df: DataFrame) → Figure[source]

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[source]

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.