User guide

This tutorial provides an introduction to the Phyllotaxis Analysis package, which contains the algorithms and models previously published in A Combinatorial Model of Phyllotaxis Perturbations in Arabidopsis thaliana.

The Phyllotaxis Analysis package offers tools to study phyllotaxis perturbations, specifically to determine whether these perturbations are due to permutations of botanical elements on the stem. Before diving into the tutorial, you may want to read the referenced paper. During the tutorial, we will explain the main ideas and concepts of the model and algorithms.

Analysis of sequences

Phyllotaxis is the arrangement of botanical elements, such as leaves, on a stem. This arrangement can be characterized by the angle between two successive leaves, known as the divergence angle. The divergence angle is typically constant, with canonical angles such as 137.5 degrees, 99.5 degrees, etc.

Divergence angles can be measured along the stem, generating a sequence of angles. Ideally, a measured sequence would consist of canonical angles. However, perturbations can occur. The Phyllotaxis Analysis package provides tools to test whether these perturbations are due to permutations of leaves or other botanical elements on the stem.

Reading Measured Divergence Angles from a File

Measured sequences of divergence angles can be saved in a file for analysis. The read_file module provides functions to read these sequences from a file.

If your sequences are saved in a CSV file where each column corresponds to the measured divergence angles of a plant, you can use the read_csv_file function to extract these sequences:

>>> from phyllotaxis_analysis.read_file import read_csv_file
>>> measured_seq = read_csv_file("./fileName.csv")

The measured_seq variable will now contain a list of sequences of measured angles. If you have a single sequence to analyze, you can use a Python list:

>>> measured_seq = [120, 145, 280, 220, 270, 150, 145, 115, 135, 280, 225, 70, 240, 260, 145, 125, 285, 225, 260, 285, 235, 260, 145]

For the remainder of this tutorial, we will assume that the measured sequence is stored in the list measured_seq.

To analyze your data, you need to import the functions provided in the analysis_functions module.

If the measured sequence is in clockwise or counterclockwise orientation and you need to convert it to the opposite orientation, you can use the counter_clock_wise function:

>>> from phyllotaxis_analysis.analysis_functions import counter_clock_wise
ccw_sequence = counter_clock_wise(measured_seq)

Analyzing Sequences of Theoretical Angles

In this section, we assume that the sequences are multiples of canonical divergence angles (e.g., 137.5, 99.5). Given the maximum number of organs involved in permutations and the canonical angle, you can calculate all possible theoretical angles, both in degrees and as integers representing coefficients of canonical angles.

In Python, use the theoretical_divergence_angles function:

>>> from phyllotaxis_analysis.analysis_functions import theoretical_divergence_angles
>>> permutation_block_max_size, canonical_angle = 3, 137.5
>>> theoretical_divergence_angles(permutation_block_max_size, canonical_angle)
([85.0, 222.5, 137.5, 275.0, 52.5, 190.0, 327.5], [-2, -1, 1, 2, 3, 4, 5])

You need to define intervals around these theoretical angles. For example, for permutation_block_max_size == 3, you can define a dictionary where each theoretical angle is associated with an interval:

>>> theoretical_angles_intervals = {137.5: [104, 170], 222.5: [195, 255], 52.5: [5, 79], 275: [241, 308], 85: [57, 118], 190: [156, 217], 327.5: [294, 14]}

Given this dictionary of intervals and a measured angle, you can find the theoretical angles that correspond to the measured angle using the candidate_angles function:

>>> from phyllotaxis_analysis.analysis_functions import candidate_angles
>>> measured_angle = 10
>>> candidate_angles(measured_angle, theoretical_angles_intervals)
[52.5, 327.5]

A sequence of divergence angles is called n-admissible if the non-canonical angles can be explained by permutations involving at most n successive organs. Given a sequence of theoretical angles, you can use the is_n_admissible function to determine whether the sequence is n-admissible. This function takes the sequence and the canonical angle as arguments and returns the maximum number of organs involved in a permutation, a list of permuted organs, and the order index series of the sequence. If the input is not n-admissible, it returns 0 and two empty lists.

The order index series indicates the order of appearance of organs, starting with 0:

>>> from phyllotaxis_analysis.analysis_functions import is_n_admissible
>>> # Sequence of theoretical angles
>>> seq_ta = [137.5, 137.5, 275, 222.5, 275, 137.5]
>>> is_n_admissible(seq_ta, 137.5)
(2, ([[4, 3]], [0, 1, 2, 4, 3, 5, 6]))

You can also specify the maximum number of organs involved in permutations and use the is_n_admissible function to check whether the sequence is n-admissible for a given number of permuted organs:

>>> is_n_admissible(seq_ta, 137.5, 2)
(2, ([[4, 3]], [0, 1, 2, 4, 3, 5, 6]))

If you have a list of integers and want to determine whether it is the order index series of any n-admissible sequence, you can use the is_n_admissible_integers function. This function also returns a list of permuted organs:

>>> order_index_series = [0, 1, 2, 4, 3, 5, 6]
>>> is_n_admissible_integers(order_index_series, 2)
(True, [[4, 3]])

Analyzing Sequences of Measured Angles

In this section, we will explore how to analyze a sequence of measured angles. To analyze a sequence of measured angles, use the code_sequence function. This function takes as input a sequence of measured angles, the maximum number of organs involved in permutations, the canonical angle, a dictionary of intervals, a concentration parameter, and a threshold value. The concentration parameter is used to calculate the probability of assigning a theoretical angle to a measured angle. If this probability is below the threshold, the theoretical angle cannot be assigned to the measured angle. The function returns a list of n-admissible trees and the depth of leaves.

An n-admissible tree is a tree whose paths from the root to its leaves are n-admissible:

>>> from phyllotaxis_analysis.analysis_functions import code_sequence
>>> code_sequence(measured_seq, permutation_block_max_size, canonical_angle, theoretical_angles_intervals, kappa, threshold)

Example:

>>> list_of_trees_index = code_sequence(measured_seq, 3, 137.5, theoretical_angles_intervals, kappa = 10.4, threshold = 0.05 )

To extract the prediction from the n-admissible tree, use the extract_sequences function. This function also returns the angles for which code_sequence could not assign a theoretical angle, known as not-explained angles. We consider all chained permutations preceding a not-explained angle as invalid permutations. More precisely, if an angle is not explained, we invalidate all preceding permutations down to the leftmost angle before the not-explained angle not involved in a permutation.

These chained permutations are marked by extract_sequences as invalidated angles:

>>> extract_sequences(list_of_trees_index, measured_seq, permutation_block_max_size, canonical_angle)

Specifically, it returns the most probable prediction (sequence of theoretical angles), a list of not-explained angles, a list of valid permutations, and invalidated organ indexes.

Example:

>>> best_sequence, not_explained_angles, valid_permutations, invalids = extract_sequences(list_of_trees_index, measured_seq, 3, 137.5)
>>> print(best_sequence)
[137.5, 137.5, 275, 222.5, 275, 137.5, 137.5, 137.5, 137.5, 275, 222.5, 52.5, 222.5, 275, 137.5, 137.5, 275, 222.5, 275, 275, 222.5, 275, 137.5]

You can use the invalidate_seq function, which takes a sequence of theoretical angles, a list of not-explained angles, and the maximum size of permutation blocks, and returns a list of invalidated angles:

>>> from phyllotaxis_analysis.analysis_functions import invalidate_seq
>>> invalidate_seq(seq_ta, not_explained_angles, permutation_block_max_size)

Tutorial Code

from phyllotaxis_analysis.analysis_functions import theoretical_divergence_angles
from phyllotaxis_analysis.analysis_functions import code_sequence
from phyllotaxis_analysis.analysis_functions import extract_sequences
from phyllotaxis_analysis.analysis_functions import is_n_admissible
from phyllotaxis_analysis.analysis_functions import is_n_admissible_integers

measured_seq = [120, 145, 280, 220, 270, 150, 145, 115, 135, 280, 225, 70, 240, 260, 145, 125, 285, 225, 260, 285, 235, 260, 145]

# Variables for the analysis
permutation_block_max_size, canonical_angle = 3, 137.5

# Calculate theoretical divergence angles based on permutation_block_max_size and canonical_angle
theoretical_divergence_angles(permutation_block_max_size, canonical_angle)

# Define the theoretical angles intervals
theoretical_angles_intervals = {
    137.5: [104, 170],
    222.5: [195, 255],
    52.5: [5, 79],
    275: [241, 308],
    85: [57, 118],
    190: [156, 217],
    327.5: [294, 14]
}

# Sequence of theoretical angles to be analyzed
seq_ta = [137.5, 137.5, 275, 222.5, 275, 137.5]

# Check if the sequence of theoretical angles is n-admissible for a given canonical angle
is_n_admissible(seq_ta, 137.5)
# Check if the sequence of theoretical angles is n-admissible for a given canonical angle and n
is_n_admissible(seq_ta, 137.5, 2)

# Define the order index series
order_index_series = [0, 1, 2, 4, 3, 5, 6]
# Check if the order index series is n-admissible for a given n
is_n_admissible_integers(order_index_series, 2)

# Generate the list of tree indices using the code_sequence function
list_of_trees_index = code_sequence(measured_seq, 3, 137.5, theoretical_angles_intervals, kappa=10.4, threshold=0.05)

# Extract sequences using the list of tree indices and measured sequence
best_sequence, not_explained_angles, valid_permutations, invalids = extract_sequences(list_of_trees_index, measured_seq, 3, 137.5)

Graphical User Interface

A graphical user interface (GUI) has been developed to provide access to all the aforementioned functionalities. To use the GUI, launch the application by executing phy.

You can open either a CSV file or a text file containing the measured angles. To analyze a sequence, select the plant number and configure the parameters. Then, click the "Analyze" button. To analyze the entire file, click the "Analyze File" button. Alternatively, you can manually enter a sequence.

Each button in the GUI includes a tooltip that provides information about its function. You can set the canonical divergence to test different phyllotactic modes. Additionally, you have the option to change the orientation of a sequence and analyze the reversed sequence.

The default parameter values are stored in a Python module named parameters.py, which also includes a dictionary of intervals. You can modify these settings by replacing the intervals dictionary with your own.

To view predictions and plot the results, click the "Plot" button.