Root System

Table of Contents

• Introduction
• Workflow
• Synthetic Data
• Library
• Performance Profiling
• Dependencies

Introduction

This directory contains a root system generator model. There are currently three main Python scripts:

• root_gen.py
• root_gen_optimise.py
• root_gen_bayesian.py

root_gen.py is the main script for generating new synthetic root systems. root_gen_optimise.py can be used to generate synthetic root systems with optimised parameters. root_gen_bayesian.py performs Bayesian inference, and models a joint probability distribution of parameters using Approximate Bayesian Computation (ABC).

Execute each script with the help flag (-h or --help) to view relevant documentation for the script arguments.

Workflow

Execute one of the three Python scripts above. Then view the data directory. You should see three subdirectories:

1. root_sim
2. optimise
3. bayesian

Each subdirectory will contain the outputs generated by the executed script. These outputs include

• Simulated root data, which are stored in a csv file.
• Model parameters, which are saved to a root_config.yaml file.
• Additional data, such as summary statistics, diagnostic plots, and saved models.

The root_config.yaml file is particularly useful for replicating, versioning, and sharing results. By adding --from_config 1 as a script argument, you may rerun the previously executed pipeline.

Synthetic Data

The primary purpose of the root generator is to output a synthetic root system into a tabular file. This file can be imported into GroIMP using the XEG reader. The file is composed of several columns:

Column	Type	Description
id	Discrete	A unique ID for each row.
plant_id	Discrete	A unique ID for each plant.
organ_id	Discrete	A unique ID for each root.
order	Discrete	The plant order. A first order root grows from the plant base, second order roots emerge from first order roots, third order roots emerge from second order roots, and so on.
root_type	Discrete	The root type classification. Can be one of 1 = Structural Root or 2 = Fine Root.
segment_rank	Discrete	The rank number for each root segment. A small rank refers to segments that are close to the root base, while a large rank refers to roots that are near the root apex.
parent	Discrete	The parent organ of the root segment. The parent node of the organ within the GroIMP graph. Used by the XEG reader to recursively import the synthetic root data.
coordinates	Continuous	The combined 3D coordinates (x, y, and z) of each root segment.
diameter	Continuous	The root segment diameter.
length	Continuous	The root segment length.
x	Continuous	The x coordinate of the root segment.
y	Continuous	The y coordinate of the root segment.
z	Continuous	The z coordinate of the root segment.

Library

Open root_system_lib to view the Root System library. This library contains reusable code for the aforementioned Python scripts. This ensures that each Python script is executing the same set of code for generating root systems.

A description is provided at the top of each library script.

Performance Profiling

The performance_profile.sh script can be used to profile the performance of the Python scripts using cProfile. This script will output two files in the root_sim directory:

1. root_gen.pstats: The profiling data.
2. root_gen.png: A visualisation of root_gen.pstats.

Note that gprof2dot must installed first using pip install gprof2dot --user.

Dependencies

A full list of dependencies is provided in requirements.txt.

Optuna, an optimisation library, is used to optimise the model parameters.

PyMC, a probabilistic programming language, is used to construct the ABC model.

For both the optimisation and Bayesian methods, we aim to minimise the dissimilarity between summary statistics calculated from synthetic root data and real data. This ensures that our simulation is realistic.