DeepRootGen
This page describes how to install DeepRootGen, run a root system simulation, work with its exported graph data, and contribute to the project. For the scientific background and an overview of the modelling framework, see the Introduction page.
Installation
Requirements
DeepRootGen targets Python >=3.10,<3.11 and uses Poetry to manage its
project dependencies. For reproducible installations, use the committed
poetry.lock file.
Install with Poetry
Clone the repository:
git clone https://github.com/Plant-Food-Research-Open/deep-root-gen.git
cd deep-root-gen
Install Poetry if necessary and then install the project:
python -m pip install poetry
poetry install
Run commands inside the Poetry environment:
poetry run python
For more detailed setup instructions, refer to the development and setup guide.
Quickstart
The following example creates a stochastic three-dimensional root system and exports its hierarchical graph as separate node and edge tables.
from deeprootgen.data_model import RootSimulationModel
from deeprootgen.model import RootSystemSimulation
parameters = RootSimulationModel(
random_seed=42,
max_order=3,
root_ratio=0.5,
fine_root_threshold=0.15,
outer_root_num=4,
inner_root_num=2,
min_primary_length=15.0,
max_primary_length=40.0,
base_diameter=0.5,
diameter_reduction=0.2,
apex_diameter=0.05,
min_sec_root_num=1,
max_sec_root_num=3,
growth_sec_root=0.1,
min_sec_root_length=3.0,
max_sec_root_length=15.0,
segments_per_root=6,
length_reduction=0.7,
root_vary=10.0,
interbranch_distance=2.0,
mechanical_constraints=0.0,
root_tissue_density=0.15,
gravitropism=0.1,
t=1,
enable_soil=False,
soil_layer_height=10.0,
soil_n_layers=10,
soil_layer_width=10.0,
soil_n_cols=10,
)
simulation = RootSystemSimulation(random_seed=42)
simulation.run(parameters)
node_df, edge_df = simulation.G.as_df()
node_df.to_csv("root_nodes.csv", index=False)
edge_df.to_csv("root_edges.csv", index=False)
print(f"Nodes: {len(node_df)}; edges: {len(edge_df)}")
A fixed random seed makes it possible to reproduce an individual stochastic realisation, subject to the software environment and model implementation. Different seeds can produce different root architectures under the same parameter configuration.
Working with Root Graph Data
The RootSystemGraph.as_df() method exports a node table and an edge table.
The node schema is defined by RootNodeModel in
deeprootgen/data_model/simulation_data_models.py. The tables can be used
for plotting, architectural statistics, or external analysis.
Node table
Column |
Meaning |
|---|---|
|
Unique graph node identifier. |
|
Identifier of the parent node; the base node uses |
|
Plant identifier. |
|
Root organ identifier. |
|
Root branching order; base node is order zero. |
|
Segment position within a root organ. |
|
Spatial coordinates (cm). |
|
Recorded segment dimensions (cm). |
|
Root tissue density (g/cm³). |
|
Classification such as |
|
Additional classifications. |
|
Simulation grouping tag. |
|
Flag identifying segments retained in the export but marked invalid. |
Edge table
Column |
Meaning |
|---|---|
|
Parent node identifier. |
|
Child node identifier. |
The node and edge tables jointly preserve the explicit parent-child connectivity of the simulated root system. Reconstruct segment geometry from the coordinates of each child and its parent rather than assuming the rows are already ordered into root paths.
Note
The export can retain segments marked invalid_root=True. Apply a
consistent validity filter when calculating summary statistics. Some
statistics use recorded segment lengths; geometric analyses may instead
use the distance between parent and child coordinates. Whole-root totals
may also differ from lengths clipped to a finite soil voxel grid.
The current export should not be assumed to use older field conventions such
as id, parent, a combined coordinates field, or numeric root types.
Check downstream data consumers before translating or renaming identifiers.
Development
Repository resources
Useful starting points for contributors include:
Testing
Run the project’s existing test suite with:
poetry run pytest
Passing the existing automated tests does not, by itself, establish the scientific validity of generated root systems. Changes to the simulator or statistics should also be checked for geometric consistency, graph integrity, root branching behaviour, and agreement between summary calculations.
Pre-commit hooks
Install and run the configured hooks using:
poetry run pre-commit install
poetry run pre-commit run --all-files
Building the documentation
The online documentation is available from the DeepRootGen website. The documentation uses Sphinx and the Read the Docs theme.
From the repository root, build the HTML pages using:
cd docs
make html
Open docs/build/html/index.html to view the generated documentation.
Community and Support
For questions, bug reports, and feature requests, use the repository’s GitHub Issues. For proposed code changes, see GitHub Pull Requests.
When reporting a simulation issue, include the input parameters, random seed, Python environment, relevant errors, and steps to reproduce the behaviour.
Contributions are welcome. Review the project’s contribution guidelines and code of conduct before contributing.
License
DeepRootGen is distributed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the full licence terms.