tree

phyllotaxis_analysis.tree

Rooted Tree Implementation

This module provides an implementation of a rooted tree graph for phyllotaxis analysis.

Acknowledgements: This is a port of the original openalea.container.tree Python2 implementation by Christophe Pradal christophe.pradal@cirad.fr.

Key Features: - Tree class implementing basic tree operations - PropertyTree class extending Tree with property support - Support for tree traversal, manipulation, and property management - Methods to add, remove, and modify vertices and subtrees

Usage Examples:

>>> from phyllotaxis_analysis.tree import Tree

>>> # Create a simple tree
>>> tree = Tree()
>>> child1 = tree.add_child(tree.root)
>>> child2 = tree.add_child(tree.root)
>>> grandchild = tree.add_child(child1)

>>> # Check tree properties
>>> print(tree.nb_vertices())  # 4
4
>>> print(tree.is_leaf(grandchild))  # True
True
>>> print(tree.parent(child1))  # 0 (root)
0

GraphError

Bases: Exception

Base class for graph exceptions.

This exception is raised when a general graph operation fails.

Notes

All specific graph exceptions inherit from this class.

InvalidEdge

Bases: GraphError, KeyError

Exception raised when an edge is invalid.

This exception is raised when an operation is attempted on an edge that does not exist in the graph.

Examples:

>>> try:
...     graph.edge_property(1, 2, 'weight')  # Edge (1, 2) doesn't exist
... except InvalidEdge:
...     print("Edge doesn't exist")
Edge doesn't exist

InvalidVertex

Bases: GraphError, KeyError

Exception raised when a vertex is invalid.

This exception is raised when an operation is attempted on a vertex that does not exist in the graph.

Examples:

>>> from phyllotaxis_analysis.tree import InvalidVertex
>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
>>> try:
...     tree.children(999)  # Vertex 999 doesn't exist
... except InvalidVertex:
...     print("Vertex doesn't exist")
Vertex doesn't exist

PropertyTree

PropertyTree(*args, **kwargs)

Bases: Tree

A tree with properties associated with vertices.

This class extends the Tree class by adding the ability to associate arbitrary properties (key-value pairs) with vertices in the tree.

Attributes:

Name	Type	Description
root	int	The identifier of the root vertex.

Notes

Properties are stored in dictionaries mapping vertex identifiers to values. Each property has its own dictionary.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> child = tree.add_child(tree.root,child="child_value",properties=)
>>> tree.get_vertex_property(child)
>>> tree.property('color')[child]

Initialize a new PropertyTree instance.

Parameters:

Name	Type	Description	Default
*args		Variable length argument list passed to the parent class constructor.	()
**kwargs		Arbitrary keyword arguments passed to the parent class constructor.	{}

Returns:

Type	Description
PropertyTree	A new property tree with a single vertex (the root).

Source code in src/phyllotaxis_analysis/tree.py

def __init__(self, *args, **kwargs):
    """
    Initialize a new PropertyTree instance.

    Parameters
    ----------
    *args
        Variable length argument list passed to the parent class constructor.
    **kwargs
        Arbitrary keyword arguments passed to the parent class constructor.

    Returns
    -------
    PropertyTree
        A new property tree with a single vertex (the root).
    """
    super(PropertyTree, self).__init__(*args, **kwargs)
    self._properties = {}

root property writable

root

Get the root vertex of the tree.

Returns:

Type	Description
int	The id of the root vertex of the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.root
0

__contains__

__contains__(vid)

Check whether a vertex is present in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier to check for membership.	required

Returns:

Type	Description
bool	True if the vertex exists in the tree, False otherwise.

Source code in src/phyllotaxis_analysis/tree.py

def __contains__(self, vid):
    """
    Check whether a vertex is present in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier to check for membership.

    Returns
    -------
    bool
        ``True`` if the vertex exists in the tree, ``False`` otherwise.
    """
    return self.has_vertex(vid)

__iter__

__iter__()

Iterate over the vertices of the tree.

This method returns an iterator over the vertices of the tree, allowing for easy traversal of the tree structure.

Yields:

Type	Description
Vertex	The next vertex in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def __iter__(self):
    """
    Iterate over the vertices of the tree.

    This method returns an iterator over the vertices of the tree, allowing
    for easy traversal of the tree structure.

    Yields
    ------
    Vertex
        The next vertex in the tree.
    """
    return iter(self.vertices())

__len__

__len__()

Return the number of vertices in the tree.

This method returns the number of vertices in the tree by delegating to the internal nb_vertices() method.

Returns:

Type	Description
int	The number of vertices in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def __len__(self):
    """
    Return the number of vertices in the tree.

    This method returns the number of vertices in the tree by
    delegating to the internal ``nb_vertices()`` method.

    Returns
    -------
    int
        The number of vertices in the tree.
    """
    return self.nb_vertices()

add_child

add_child(parent, child=None, **properties)

Add a child vertex to the tree under the specified parent.

The child is appended to the end of the parent's children list. Additional properties can be assigned to the new vertex via keyword arguments.

Parameters:

Name	Type	Description	Default
parent	int	The identifier of the parent vertex to which the child will be attached.	required
child	int	The identifier of the child vertex to be added. If not provided, a new vertex identifier is generated automatically.	None
**properties	dict[Any]	Keyword arguments representing additional properties to assign to the new vertex. Each key-value pair will be stored as a property of the vertex.	{}

Returns:

Type	Description
int	The identifier of the newly added child vertex.

Notes

This method extends the base class's add_child by automatically applying any provided properties to the new vertex using _add_vertex_properties.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0, ppty='value')
>>> tree.property_names()
ppty
>>> tree.property('ppty')
{1: 'value'}

Source code in src/phyllotaxis_analysis/tree.py

def add_child(self, parent, child=None, **properties):
    """
    Add a child vertex to the tree under the specified parent.

    The child is appended to the end of the parent's children list. Additional
    properties can be assigned to the new vertex via keyword arguments.

    Parameters
    ----------
    parent : int
        The identifier of the parent vertex to which the child will be attached.
    child : int, optional
        The identifier of the child vertex to be added. If not provided, a new
        vertex identifier is generated automatically.
    **properties : dict[Any], optional
        Keyword arguments representing additional properties to assign to the new vertex.
        Each key-value pair will be stored as a property of the vertex.

    Returns
    -------
    int
        The identifier of the newly added child vertex.

    Notes
    -----
    This method extends the base class's ``add_child`` by automatically
    applying any provided properties to the new vertex using ``_add_vertex_properties``.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0, ppty='value')
    >>> tree.property_names()
    ppty
    >>> tree.property('ppty')
    {1: 'value'}
    """
    child = super(PropertyTree, self).add_child(parent, child)
    # Update the properties
    self._add_vertex_properties(child, properties)

    return child

add_child_tree

add_child_tree(parent, tree)

Add a tree after the children of the parent vertex.

The tree is inserted as a child of the specified parent vertex. If the tree being added is a subtree of the current tree, the operation has O(1) complexity.

Parameters:

Name	Type	Description	Default
parent	int	The vertex identifier where the tree will be attached.	required
tree	PropertyTree	The rooted tree to be added as a child.	required

Returns:

Type	Description
dict	A mapping from tree IDs in the added tree to the corresponding vertex IDs in the parent tree.

Notes

This method ensures that properties from the added tree are properly propagated to the new vertices in the parent tree. The operation is optimized for subtree insertion (O(1) complexity).

Source code in src/phyllotaxis_analysis/tree.py

def add_child_tree(self, parent, tree):
    """
    Add a tree after the children of the parent vertex.

    The tree is inserted as a child of the specified parent vertex.
    If the tree being added is a subtree of the current tree, the operation has O(1) complexity.

    Parameters
    ----------
    parent : int
        The vertex identifier where the tree will be attached.
    tree : phyllotaxis_analysis.tree.PropertyTree
        The rooted tree to be added as a child.

    Returns
    -------
    dict
        A mapping from tree IDs in the added tree to the corresponding
        vertex IDs in the parent tree.

    Notes
    -----
    This method ensures that properties from the added tree are properly
    propagated to the new vertices in the parent tree.
    The operation is optimized for subtree insertion (O(1) complexity).
    """
    treeid_id = super(PropertyTree, self).add_child_tree(parent, tree)
    for tid, vid in treeid_id.items():
        for name in tree.properties():
            v = tree.property(name).get(tid)
            if v is not None:
                self._properties[name][vid] = v

    return treeid_id

add_property

add_property(property_name)

Add a new map between vid and a data. Do not fill this property for any vertex.

Parameters:

Name	Type	Description	Default
property_name	str	Name of the property to add.	required

Notes

This method initializes an empty dictionary for the given property name in the _properties attribute. The property is not populated with any vertex data at this stage.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_property('ppty')
>>> tree.property_names()
ppty

Source code in src/phyllotaxis_analysis/tree.py

def add_property(self, property_name):
    """
    Add a new map between `vid` and a data. Do not fill this property for any vertex.

    Parameters
    ----------
    property_name : str
        Name of the property to add.

    Notes
    -----
    This method initializes an empty dictionary for the given property name in the `_properties` attribute.
    The property is not populated with any vertex data at this stage.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_property('ppty')
    >>> tree.property_names()
    ppty
    """
    self._properties[property_name] = {}

add_vertex

add_vertex(vid=None)

Add a vertex to the graph.

Adds a new vertex to the graph with the specified identifier or auto-increments the identifier if not provided.

Parameters:

Name	Type	Description	Default
vid	int	The identifier for the new vertex. If None, the identifier is auto-incremented. Default is None.	None

Returns:

Type	Description
int	The identifier of the added vertex.

Raises:

Type	Description
InvalidVertex	If the provided vid is less than or equal to the current maximum identifier, indicating the identifier is already in use.

Examples:

>>> from phyllotaxis_analysis.tree import InvalidVertex
>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_vertex()
1
>>> tree.add_vertex(vid=5)
5
>>> try:
>>>    tree.add_vertex(vid=3)
>>> except InvalidVertex as e:
>>>    print(f"ERROR: {e}")
ERROR: 'Vertex identifier already used: 3'

Source code in src/phyllotaxis_analysis/tree.py

def add_vertex(self, vid=None):
    """
    Add a vertex to the graph.

    Adds a new vertex to the graph with the specified identifier or auto-increments the identifier if not provided.

    Parameters
    ----------
    vid : int, optional
        The identifier for the new vertex. If ``None``, the identifier is auto-incremented.
        Default is ``None``.

    Returns
    -------
    int
        The identifier of the added vertex.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the provided ``vid`` is less than or equal to the current maximum identifier,
        indicating the identifier is already in use.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import InvalidVertex
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_vertex()
    1
    >>> tree.add_vertex(vid=5)
    5
    >>> try:
    >>>    tree.add_vertex(vid=3)
    >>> except InvalidVertex as e:
    >>>    print(f"ERROR: {e}")
    ERROR: 'Vertex identifier already used: 3'
    """
    if vid is None:
        vid = self._id + 1
        self._id = vid
    elif vid <= self._id:
        raise InvalidVertex(f'Vertex identifier already used: {vid}')
    else:
        self._id = vid

    self._parent[vid] = None
    return vid

children

children(vid)

Return the children of a vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose children are to be retrieved.	required

Returns:

Type	Description
list[int]	A list of vertex identifiers that are children of vid.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.children(0)
[5, 6]
>>> tree.children(5)
[]

Source code in src/phyllotaxis_analysis/tree.py

def children(self, vid):
    """
    Return the children of a vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose children are to be retrieved.

    Returns
    -------
    list[int]
        A list of vertex identifiers that are children of `vid`.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.children(0)
    [5, 6]
    >>> tree.children(5)
    []
    """
    if vid not in self:
        raise InvalidVertex(vid)

    return list(self._children.get(vid, []))

clear

clear()

Remove all vertices and edges from the graph.

This method clears the tree structure by removing all child and parent relationships.

Notes

This method does not delete the root vertex itself, only its relationships.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.nb_vertices()
3
>>> g.clear()
>>> g.nb_vertices()
1

Source code in src/phyllotaxis_analysis/tree.py

def clear(self):
    """
    Remove all vertices and edges from the graph.

    This method clears the tree structure by removing all child and parent relationships.

    Notes
    -----
    This method does not delete the root vertex itself, only its relationships.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.nb_vertices()
    3
    >>> g.clear()
    >>> g.nb_vertices()
    1
    """
    self._children.clear()
    self._parent.clear()
    self._parent[self._root] = None

copy

copy()

Deep copy of the tree.

Returns:

Type	Description
tree	A new instance of the tree with all attributes deeply copied.

Source code in src/phyllotaxis_analysis/tree.py

def copy(self):
    """
    Deep copy of the tree.

    Returns
    -------
    phyllotaxis_analysis.tree
        A new instance of the tree with all attributes deeply copied.
    """
    return deepcopy(self)

edges_iter

edges_iter()

Iterate over the edges of the tree.

Yields:

Type	Description
tuple[int, int]	A tuple of (parent, child) vertices representing each edge in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def edges_iter(self):
    """
    Iterate over the edges of the tree.

    Yields
    ------
    tuple[int, int]
        A tuple of (parent, child) vertices representing each edge in the tree.
    """
    return ((parent, child) for child, parent in self._parent.items())

get_vertex_property

get_vertex_property(vid)

Returns all the properties defined on a vertex.

Parameters:

Name	Type	Description	Default
vid	int	The vertex ID for which to retrieve properties.	required

Returns:

Type	Description
dict	A dictionary mapping property names to their values for the specified vertex.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0, ppty='A')
1
>>> tree.add_child(0, ppty='B')
2
>>> tree.get_vertex_property(2)
{'ppty': 'B'}

Source code in src/phyllotaxis_analysis/tree.py

def get_vertex_property(self, vid):
    """
    Returns all the properties defined on a vertex.

    Parameters
    ----------
    vid : int
        The vertex ID for which to retrieve properties.

    Returns
    -------
    dict
        A dictionary mapping property names to their values for the specified vertex.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0, ppty='A')
    1
    >>> tree.add_child(0, ppty='B')
    2
    >>> tree.get_vertex_property(2)
    {'ppty': 'B'}
    """
    ppty = self.properties()
    return {name: ppty[name][vid] for name in ppty if vid in ppty[name]}

has_vertex

has_vertex(vid)

Determines whether a given vertex is in the graph.

Parameters:

Name	Type	Description	Default
vid	int or str	The identifier of the vertex to be checked for existence in the graph.	required

Returns:

Type	Description
bool	Returns True if the vertex is present in the graph, False otherwise.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.has_vertex(1)
True
>>> g.has_vertex(2)
False
>>> g.has_vertex(6)
True

Source code in src/phyllotaxis_analysis/tree.py

def has_vertex(self, vid):
    """
    Determines whether a given vertex is in the graph.

    Parameters
    ----------
    vid : int or str
        The identifier of the vertex to be checked for existence in the graph.

    Returns
    -------
    bool
        Returns ``True`` if the vertex is present in the graph, ``False`` otherwise.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.has_vertex(1)
    True
    >>> g.has_vertex(2)
    False
    >>> g.has_vertex(6)
    True
    """
    return vid in self._parent

insert_parent

insert_parent(vid, parent_id=None, **properties)

Insert parent_id between vid and its actual parent. Inherit of the complex of the parent of vid.

Parameters:

Name	Type	Description	Default
vid	int	A vertex identifier.	required
parent_id	int	A vertex identifier. Defaults to None.	None
**properties	dict	Additional properties to assign to the new parent vertex.	{}

Returns:

Type	Description
int	The identifier of the newly inserted parent vertex.

Source code in src/phyllotaxis_analysis/tree.py

def insert_parent(self, vid, parent_id=None, **properties):
    """
    Insert parent_id between `vid` and its actual parent. Inherit of the complex of the parent of `vid`.

    Parameters
    ----------
    vid : int
        A vertex identifier.
    parent_id : int, optional
        A vertex identifier. Defaults to ``None``.
    **properties : dict, optional
        Additional properties to assign to the new parent vertex.

    Returns
    -------
    int
        The identifier of the newly inserted parent vertex.
    """

    parent_id = super(PropertyTree, self).insert_parent(vid, parent_id)
    self._add_vertex_properties(parent_id, properties)

    return parent_id

insert_sibling

insert_sibling(vid_1, vid_2=None, **properties)

Insert a new vertex as a sibling of an existing vertex in the tree.

The new vertex is inserted immediately before the specified vertex. Any additional properties provided are assigned to the new vertex.

Parameters:

Name	Type	Description	Default
vid_1	int	The vertex identifier of the existing vertex before which the new vertex will be inserted.	required
vid_2	int	The vertex identifier of the new vertex to insert. If not provided, a new vertex identifier is generated automatically.	None
**properties	dict	Additional properties to assign to the new vertex. Keys are property names and values are the corresponding values.	{}

Returns:

Type	Description
int	The vertex identifier of the newly inserted vertex.

Source code in src/phyllotaxis_analysis/tree.py

def insert_sibling(self, vid_1, vid_2=None, **properties):
    """
    Insert a new vertex as a sibling of an existing vertex in the tree.

    The new vertex is inserted immediately before the specified vertex.
    Any additional properties provided are assigned to the new vertex.

    Parameters
    ----------
    vid_1 : int
        The vertex identifier of the existing vertex before which the new
        vertex will be inserted.
    vid_2 : int, optional
        The vertex identifier of the new vertex to insert. If not provided,
        a new vertex identifier is generated automatically.
    **properties : dict, optional
        Additional properties to assign to the new vertex. Keys are property
        names and values are the corresponding values.

    Returns
    -------
    int
        The vertex identifier of the newly inserted vertex.
    """

    vid_2 = super(PropertyTree, self).insert_sibling(vid_1, vid_2)

    # Update the properties
    self._add_vertex_properties(vid_2, properties)

    return vid_2

insert_sibling_tree

insert_sibling_tree(vid, tree)

Insert a tree as a sibling to the vertex identified by vid.

The root of tree and the vertex vid become siblings. The operation has O(1) complexity when tree is obtained via self.subtree().

Parameters:

Name	Type	Description	Default
vid	int	Vertex identifier in the current tree.	required
tree	PropertyTree	A rooted tree to insert as a sibling of vid.	required

Returns:

Type	Description
dict[int, int]	Mapping from original tree vertex IDs to newly created vertex IDs.

Notes

If tree is a subtree of the current tree (obtained via self.subtree()), the operation is guaranteed to run in O(1) time. Otherwise, the complexity depends on the size of tree.

Source code in src/phyllotaxis_analysis/tree.py

def insert_sibling_tree(self, vid, tree):
    """
    Insert a tree as a sibling to the vertex identified by `vid`.

    The root of `tree` and the vertex `vid` become siblings. The operation
    has O(1) complexity when `tree` is obtained via `self.subtree()`.

    Parameters
    ----------
    vid : int
        Vertex identifier in the current tree.
    tree : phyllotaxis_analysis.tree.PropertyTree
        A rooted tree to insert as a sibling of `vid`.

    Returns
    -------
    dict[int, int]
        Mapping from original tree vertex IDs to newly created vertex IDs.

    Notes
    -----
    If `tree` is a subtree of the current tree (obtained via `self.subtree()`),
    the operation is guaranteed to run in O(1) time.
    Otherwise, the complexity depends on the size of `tree`.
    """
    treeid_id = super(PropertyTree, self).insert_sibling_tree(vid, tree)
    for tid, vid in treeid_id.items():
        for name in tree.properties():
            v = tree.property(name).get(tid)
            if v is not None:
                self._properties[name][vid] = v

    return treeid_id

is_leaf

is_leaf(vid)

Test if a vertex is a leaf in the tree.

A leaf vertex is defined as a vertex with no children.

Parameters:

Name	Type	Description	Default
vid	int	The ID of the vertex to test.	required

Returns:

Type	Description
bool	True if the vertex is a leaf (has no children), False otherwise.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.is_leaf(5)
True
>>> tree.is_leaf(0)
False

Source code in src/phyllotaxis_analysis/tree.py

def is_leaf(self, vid):
    """
    Test if a vertex is a leaf in the tree.

    A leaf vertex is defined as a vertex with no children.

    Parameters
    ----------
    vid : int
        The ID of the vertex to test.

    Returns
    -------
    bool
        ``True`` if the vertex is a leaf (has no children), ``False`` otherwise.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.is_leaf(5)
    True
    >>> tree.is_leaf(0)
    False
    """
    return self.nb_children(vid) == 0

nb_children

nb_children(vid)

Return the number of children of a given vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose children count is requested.	required

Returns:

Type	Description
int	The number of children of the vertex.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.nb_children(0)
2

Source code in src/phyllotaxis_analysis/tree.py

def nb_children(self, vid):
    """
    Return the number of children of a given vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose children count is requested.

    Returns
    -------
    int
        The number of children of the vertex.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.nb_children(0)
    2
    """
    if vid not in self:
        raise InvalidVertex(vid)

    return len(self._children.get(vid, []))

nb_siblings

nb_siblings(vid)

Return the number of siblings of a given vertex identifier.

Parameters:

Name	Type	Description	Default
vid	int	The identifier of the vertex whose siblings are to be counted.	required

Returns:

Type	Description
int	The number of siblings of the vertex with the identifier vid.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.nb_siblings(5)
1

Source code in src/phyllotaxis_analysis/tree.py

def nb_siblings(self, vid):
    """
    Return the number of siblings of a given vertex identifier.

    Parameters
    ----------
    vid : int
        The identifier of the vertex whose siblings are to be counted.

    Returns
    -------
    int
        The number of siblings of the vertex with the identifier ` vid `.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.nb_siblings(5)
    1
    """
    return len(self.siblings(vid))

nb_vertices

nb_vertices()

Returns the number of vertices in the graph.

Returns:

Type	Description
int	The number of vertices in the graph.

See Also

nb_edges : Returns the number of edges in the graph.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex()  # add a second vertices
>>> g.nb_vertices()
3

Source code in src/phyllotaxis_analysis/tree.py

def nb_vertices(self):
    """
    Returns the number of vertices in the graph.

    Returns
    -------
    int
        The number of vertices in the graph.

    See Also
    --------
    nb_edges : Returns the number of edges in the graph.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex()  # add a second vertices
    >>> g.nb_vertices()
    3
    """
    return len(self._parent)

parent

parent(vid)

Return the parent of a vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose parent is to be retrieved.	required

Returns:

Type	Description
int | None	The parent vertex identifier. Returns None if the vertex is the root.

Raises:

Type	Description
InvalidVertex	If the vertex identifier vid is not found in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.parent(5)
0

Source code in src/phyllotaxis_analysis/tree.py

def parent(self, vid):
    """
    Return the parent of a vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose parent is to be retrieved.

    Returns
    -------
    int | None
        The parent vertex identifier. Returns ``None`` if the vertex is the root.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the vertex identifier `vid` is not found in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.parent(5)
    0
    """
    try:
        return self._parent[vid]
    except KeyError:
        raise InvalidVertex(vid)

properties

properties()

Returns all the property maps contained in the graph.

Returns:

Type	Description
dict	A dictionary where keys are property names and values are the corresponding property maps.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0,ppty='A')
1
>>> tree.add_child(0,ppty='B')
2
>>> tree.properties()
{'ppty': {1: 'A', 2: 'B'}}

Source code in src/phyllotaxis_analysis/tree.py

def properties(self):
    """
    Returns all the property maps contained in the graph.

    Returns
    -------
    dict
        A dictionary where keys are property names and values are the corresponding property maps.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0,ppty='A')
    1
    >>> tree.add_child(0,ppty='B')
    2
    >>> tree.properties()
    {'ppty': {1: 'A', 2: 'B'}}
    """
    return self._properties

property

property(name)

Returns the property map between the vid and the data.

Parameters:

Name	Type	Description	Default
name	str	The name of the property to retrieve.	required

Returns:

Type	Description
dict	A dictionary mapping vertex IDs (vid) to their corresponding data values. If the property does not exist, an empty dictionary is returned.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0,ppty='value')
>>> tree.property('ppty')
{1: 'value'}

Source code in src/phyllotaxis_analysis/tree.py

def property(self, name):
    """
    Returns the property map between the vid and the data.

    Parameters
    ----------
    name : str
        The name of the property to retrieve.

    Returns
    -------
    dict
        A dictionary mapping vertex IDs (vid) to their corresponding data values.
        If the property does not exist, an empty dictionary is returned.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0,ppty='value')
    >>> tree.property('ppty')
    {1: 'value'}
    """
    return self._properties.get(name, {})

property_names

property_names()

Return the property names of all property maps.

Returns:

Type	Description
list	The list of the property names of all property maps.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0,ppty='value')
>>> tree.property_names()
ppty

Source code in src/phyllotaxis_analysis/tree.py

def property_names(self):
    """
    Return the property names of all property maps.

    Returns
    -------
    list
        The list of the property names of all property maps.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0,ppty='value')
    >>> tree.property_names()
    ppty
    """
    return list(self._properties.keys())

property_names_iter

property_names_iter()

Iterate over the names of all property maps.

Properties are defined only on vertices, even edge properties. This method returns an iterator over the property names stored in the tree.

Returns:

Type	Description
iter	An iterator over the names of all property maps in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def property_names_iter(self):
    """
    Iterate over the names of all property maps.

    Properties are defined only on vertices, even edge properties.
    This method returns an iterator over the property names stored in the tree.

    Returns
    -------
    iter
        An iterator over the names of all property maps in the tree.
    """
    return iter(self._properties.keys())

remove_leaf

remove_leaf(vid)

Remove a leaf vertex from the tree.

The vertex identified by vid is removed only if it is a leaf (has no children) and it is not the root of the tree. The parent–child relationships stored in _children and _parent are updated accordingly.

Parameters:

Name	Type	Description	Default
vid	int	Identifier of the vertex to be removed.	required

Raises:

Type	Description
InvalidVertex	If vid is the root vertex. If vid has one or more children (i.e., is not a leaf).

Notes

• The method mutates the internal _children and _parent mappings of the tree instance.
• Attempting to remove a vertex that does not exist in the internal structures has no effect.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0)
1
>>> tree.is_leaf(1)
True
>>> tree.remove_leaf(1)        # removes leaf vertex 1
>>> tree.is_leaf(0)
True
>>> tree.remove_leaf(0)        # cannot remove the root
phyllotaxis_analysis.tree.InvalidVertex: 'The root node 0 can not be removed.'

Source code in src/phyllotaxis_analysis/tree.py

def remove_leaf(self, vid):
    """Remove a leaf vertex from the tree.

    The vertex identified by ``vid`` is removed only if it is a leaf (has no
    children) and it is not the root of the tree.  The parent–child
    relationships stored in ``_children`` and ``_parent`` are updated
    accordingly.

    Parameters
    ----------
    vid : int
        Identifier of the vertex to be removed.

    Raises
    ------
    InvalidVertex
        If ``vid`` is the root vertex.
        If ``vid`` has one or more children (i.e., is not a leaf).

    Notes
    -----
    * The method mutates the internal ``_children`` and ``_parent`` mappings
      of the tree instance.
    * Attempting to remove a vertex that does not exist in the internal
      structures has no effect.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0)
    1
    >>> tree.is_leaf(1)
    True
    >>> tree.remove_leaf(1)        # removes leaf vertex 1
    >>> tree.is_leaf(0)
    True
    >>> tree.remove_leaf(0)        # cannot remove the root
    phyllotaxis_analysis.tree.InvalidVertex: 'The root node 0 can not be removed.'
    """
    if vid == self.root:
        raise InvalidVertex("The root node %d can not be removed." % vid)

    if self.is_leaf(vid):
        pid = self.parent(vid)
        if pid is not None:
            self._children[pid].remove(vid)
            del self._parent[vid]
        if vid in self._children:
            del self._children[vid]
    else:
        raise InvalidVertex(
            "Can not remove vertex %d with children. Only leaves can be removed. You need to remove the children first." % vid)

remove_property

remove_property(property_name)

Remove the property map called property_name from the graph.

Parameters:

Name	Type	Description	Default
property_name	str	The name of the property map to remove.	required

Raises:

Type	Description
KeyError	If property_name does not exist in the graph's properties.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_property('ppty')
>>> tree.property_names()
ppty
>>> tree.remove_property('ppty')
>>> tree.property_names()
[]

Source code in src/phyllotaxis_analysis/tree.py

def remove_property(self, property_name):
    """
    Remove the property map called `property_name` from the graph.

    Parameters
    ----------
    property_name : str
        The name of the property map to remove.

    Raises
    ------
    KeyError
        If `property_name` does not exist in the graph's properties.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_property('ppty')
    >>> tree.property_names()
    ppty
    >>> tree.remove_property('ppty')
    >>> tree.property_names()
    []
    """
    del self._properties[property_name]

remove_tree

remove_tree(vid)

Remove the subtree rooted on vid.

Remove the subtree rooted at the vertex with the given ID.

Parameters:

Name	Type	Description	Default
vid	int	The vertex ID of the root of the subtree to remove.	required

Returns:

Type	Description
list	The list of vertex IDs that were removed from the tree.

Source code in src/phyllotaxis_analysis/tree.py

def remove_tree(self, vid):
    """
    Remove the subtree rooted on `vid`.

    Remove the subtree rooted at the vertex with the given ID.

    Parameters
    ----------
    vid : int
        The vertex ID of the root of the subtree to remove.

    Returns
    -------
    list
        The list of vertex IDs that were removed from the tree.
    """
    vids = super(PropertyTree, self).remove_tree(vid)
    for vid in vids:
        self._remove_vertex_properties(vid)
    return vids

remove_vertex

remove_vertex(vid, reparent_child=False)

Remove a specified vertex from the graph and all its attached edges.

Remove all edges connected to the vertex and clean up associated properties.

Parameters:

Name	Type	Description	Default
vid	int	The ID of the vertex to remove.	required
reparent_child	bool	If True, reparent the child of the removed vertex to its parent. Default is False.	False

Notes

This method also removes any properties associated with the vertex via _remove_vertex_properties.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_vertex(1)
>>> tree.add_vertex(2)
>>> tree.vertices()
[0, 1, 2]
>>> tree.remove_vertex(1)
>>> tree.vertices()
[0, 2]

Source code in src/phyllotaxis_analysis/tree.py

def remove_vertex(self, vid, reparent_child=False):
    """
    Remove a specified vertex from the graph and all its attached edges.

    Remove all edges connected to the vertex and clean up associated properties.

    Parameters
    ----------
    vid : int
        The ID of the vertex to remove.
    reparent_child : bool, optional
        If ``True``, reparent the child of the removed vertex to its parent.
        Default is ``False``.

    Notes
    -----
    This method also removes any properties associated with the vertex via ``_remove_vertex_properties``.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_vertex(1)
    >>> tree.add_vertex(2)
    >>> tree.vertices()
    [0, 1, 2]
    >>> tree.remove_vertex(1)
    >>> tree.vertices()
    [0, 2]
    """
    vid = super(PropertyTree, self).remove_vertex(vid, reparent_child=reparent_child)
    self._remove_vertex_properties(vid)

replace_parent

replace_parent(vid, new_parent_id)

Change the parent of a vertex to a new parent vertex.

Parameters:

Name	Type	Description	Default
vid	int	The vertex ID whose parent will be changed.	required
new_parent_id	int	The new parent vertex ID.	required

Raises:

Type	Description
InvalidVertex	If vid or new_parent_id does not exist in the tree. If attempting to change the parent of the root vertex (which has no parent).

Notes

The old parent relationship is removed when the new parent is assigned.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.children(0)
[5]
>>> tree.insert_parent(5, 6)
6
>>> tree.add_vertex(7)
7
>>> tree.replace_parent(5, 7)
>>> tree.parent(5)
7
>>> tree.children(0)
[6]
>>> tree.parent(7)
None

Source code in src/phyllotaxis_analysis/tree.py

def replace_parent(self, vid, new_parent_id):
    """
    Change the parent of a vertex to a new parent vertex.

    Parameters
    ----------
    vid : int
        The vertex ID whose parent will be changed.
    new_parent_id : int
        The new parent vertex ID.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` or `new_parent_id` does not exist in the tree.
        If attempting to change the parent of the root vertex (which has no parent).

    Notes
    -----
    The old parent relationship is removed when the new parent is assigned.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.children(0)
    [5]
    >>> tree.insert_parent(5, 6)
    6
    >>> tree.add_vertex(7)
    7
    >>> tree.replace_parent(5, 7)
    >>> tree.parent(5)
    7
    >>> tree.children(0)
    [6]
    >>> tree.parent(7)
    None
    """
    if vid not in self:
        raise InvalidVertex(vid)
    if new_parent_id not in self:
        raise InvalidVertex(new_parent_id)

    old_parent = self.parent(vid)
    if old_parent is None:
        raise InvalidVertex("Cannot replace parent of the root")

    # Update parent
    self._parent[vid] = new_parent_id

    # Update children
    self._children[old_parent].remove(vid)
    if new_parent_id in self._children:
        self._children[new_parent_id].append(vid)
    else:
        self._children[new_parent_id] = [vid]

siblings

siblings(vid)

Return the siblings of a given vertex identifier in the tree.

Given a vertex identifier vid, this method returns a list of all sibling vertices (i.e., vertices sharing the same parent). If the vertex has no parent (i.e., it is the root), an empty list is returned.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose siblings are to be retrieved.	required

Returns:

Type	Description
list	The list of vertex identifiers that are siblings of vid. Empty if vid is the root or does not exist.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.siblings(0)
[]
>>> tree.siblings(5)
[6]

Source code in src/phyllotaxis_analysis/tree.py

def siblings(self, vid):
    """
    Return the siblings of a given vertex identifier in the tree.

    Given a vertex identifier `vid`, this method returns a list of all sibling
    vertices (i.e., vertices sharing the same parent). If the vertex has no
    parent (i.e., it is the root), an empty list is returned.

    Parameters
    ----------
    vid : int
        The vertex identifier whose siblings are to be retrieved.

    Returns
    -------
    list
        The list of vertex identifiers that are siblings of `vid`. Empty if `vid`
        is the root or does not exist.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.siblings(0)
    []
    >>> tree.siblings(5)
    [6]
    """
    if vid not in self:
        raise InvalidVertex(vid)

    parent = self.parent(vid)
    if parent is None:
        return []
    else:
        sibs = list(self.children(parent))
        sibs.remove(vid)
        return sibs

subtree

subtree(vid, copy=True)

Return the subtree containing all descendants of vid.

The induced subtree of the tree has the vertices in the subtree rooted at vid. This creates a new tree that includes all vertices from vid and all its descendants.

Parameters:

Name	Type	Description	Default
vid	int	A vertex of the original tree.	required
copy	bool	If True, return a new tree holding the subtree. If False, the subtree is created using the original tree by deleting all vertices not in the subtree. Default is True.	True

Returns:

Type	Description
PropertyTree	A subtree of the tree. If copy is True, a new Tree is returned. Else the subtree is created in-place by modifying the original tree.

Examples:

>>> from phyllotaxis_analysis.tree import PropertyTree
>>> tree = PropertyTree()
>>> tree.add_child(0)
1
>>> tree.insert_parent(1)
2
>>> tree.insert_sibling(1)
3
>>> subtree = tree.subtree(2, copy=True)
>>> subtree.vertices()
[0, 1, 2]
>>> subtree.root
0

Source code in src/phyllotaxis_analysis/tree.py

def subtree(self, vid, copy=True):
    """
    Return the subtree containing all descendants of `vid`.

    The induced subtree of the tree has the vertices in the subtree rooted at `vid`.
    This creates a new tree that includes all vertices from `vid` and all its descendants.

    Parameters
    ----------
    vid : int
        A vertex of the original tree.
    copy : bool, optional
        If ``True``, return a new tree holding the subtree. If ``False``, the subtree is
        created using the original tree by deleting all vertices not in the subtree.
        Default is ``True``.

    Returns
    ------- 
    phyllotaxis_analysis.tree.PropertyTree
        A subtree of the tree. If `copy` is ``True``, a new Tree is returned.
        Else the subtree is created in-place by modifying the original tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import PropertyTree
    >>> tree = PropertyTree()
    >>> tree.add_child(0)
    1
    >>> tree.insert_parent(1)
    2
    >>> tree.insert_sibling(1)
    3
    >>> subtree = tree.subtree(2, copy=True)
    >>> subtree.vertices()
    [0, 1, 2]
    >>> subtree.root
    0
    """
    if not copy:
        # remove all vertices not in the subtree
        bunch = set(pre_order(self, vid))
        remove_bunch = set(self) - bunch

        for vid in remove_bunch:
            self._remove_vertex_properties(vid)

            # remove parent edge
            pid = self.parent(vid)
            if pid is not None:
                self._children[pid].remove(vid)
                del self._parent[vid]
            # remove children edges
            for cid in self.children(vid):
                self._parent[cid] = None
            if vid in self._children:
                del self._children[vid]

        self.root = vid
        return self
    else:
        treeid_id = {}
        tree = self.__class__()
        tree.root = 0

        for name in self.properties():
            tree.add_property(name)

        treeid_id[vid] = tree.root
        tree._add_vertex_properties(tree.root, self.get_vertex_property(vid))
        subtree = pre_order(self, vid)
        next(subtree)
        for vid in subtree:
            pid = self.parent(vid)
            if pid is not None:
                parent = treeid_id[pid]
                v = tree.add_child(parent)
                treeid_id[vid] = v

            tree._add_vertex_properties(v, self.get_vertex_property(vid))

        return tree

vertices

vertices()

Returns the list of vertices in the graph.

Returns:

Type	Description
list	The list of the vertices in the graph.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.vertices()
[0, 1, 6]

Source code in src/phyllotaxis_analysis/tree.py

def vertices(self):
    """
    Returns the list of vertices in the graph.

    Returns
    -------
    list
        The list of the vertices in the graph.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.vertices()
    [0, 1, 6]
    """
    return list(self.vertices_iter())

vertices_iter

vertices_iter()

Generates an iterator for the vertices in the graph.

This method is a generator that yields each vertex in the graph as a string, which corresponds to the key of the vertex in the internal dictionary representation of the graph. The order in which vertices are returned by this iterator is not guaranteed to be consistent between different calls or even different yields.

Yields:

Type	Description
str	A string representing the vertex in the graph.

Source code in src/phyllotaxis_analysis/tree.py

def vertices_iter(self):
    """
    Generates an iterator for the vertices in the graph.

    This method is a generator that yields each vertex in the graph as a string,
    which corresponds to the key of the vertex in the internal dictionary representation
    of the graph. The order in which vertices are returned by this iterator is not
    guaranteed to be consistent between different calls or even different yields.

    Yields
    ------
    str
        A string representing the vertex in the graph.
    """
    return iter(self._parent.keys())

Tree

Tree(root=0, tree=None)

Bases: object

Implementation of a rooted tree with vertex manipulation methods.

This class implements a tree data structure where each vertex has a unique identifier and can have multiple children but only one parent. The tree has a distinguished vertex called the root.

Attributes:

Name	Type	Description
_root	int	The identifier of the root vertex.
_id	int	The value of the latest id used to register a vertex.
_parent	dict[int, int | None]	The dictionary of vertex id (key) and their parent vertex id (value).
_children	dict[int, int | list[int]]	The dictionary of vertex id (key) and their child(ren) vertex id(s) (value).

Notes

The tree is implemented using dictionaries for efficient vertex lookup and parent-child relationship management.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> child1 = tree.add_child(tree.root)
>>> child2 = tree.add_child(tree.root)
>>> grandchild = tree.add_child(child1)
>>> tree.nb_vertices()
>>> tree.is_leaf(grandchild)
>>> tree.parent(child1) == tree.root

Initialize a new Tree instance.

Parameters:

Name	Type	Description	Default
root	int	The identifier for the root vertex. Default is 0.	0
tree	tree	Not used in this implementation, kept for compatibility.	None

Source code in src/phyllotaxis_analysis/tree.py

def __init__(self, root: int = 0, tree=None):
    """
    Initialize a new Tree instance.

    Parameters
    ----------
    root : int, optional
        The identifier for the root vertex. Default is ``0``.
    tree : phyllotaxis_analysis.tree, optional
        Not used in this implementation, kept for compatibility.
    """
    self._root: int = root
    self._id: int = root
    # Tree structure
    # Parent is a dict for DAG implementation
    self._parent: dict[int, int | None] = {root: None}
    self._children: dict[int, int | list[int]] = {}

root property writable

root

Get the root vertex of the tree.

Returns:

Type	Description
int	The id of the root vertex of the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.root
0

__contains__

__contains__(vid)

Check whether a vertex is present in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier to check for membership.	required

Returns:

Type	Description
bool	True if the vertex exists in the tree, False otherwise.

Source code in src/phyllotaxis_analysis/tree.py

def __contains__(self, vid):
    """
    Check whether a vertex is present in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier to check for membership.

    Returns
    -------
    bool
        ``True`` if the vertex exists in the tree, ``False`` otherwise.
    """
    return self.has_vertex(vid)

__iter__

__iter__()

Iterate over the vertices of the tree.

This method returns an iterator over the vertices of the tree, allowing for easy traversal of the tree structure.

Yields:

Type	Description
Vertex	The next vertex in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def __iter__(self):
    """
    Iterate over the vertices of the tree.

    This method returns an iterator over the vertices of the tree, allowing
    for easy traversal of the tree structure.

    Yields
    ------
    Vertex
        The next vertex in the tree.
    """
    return iter(self.vertices())

__len__

__len__()

Return the number of vertices in the tree.

This method returns the number of vertices in the tree by delegating to the internal nb_vertices() method.

Returns:

Type	Description
int	The number of vertices in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def __len__(self):
    """
    Return the number of vertices in the tree.

    This method returns the number of vertices in the tree by
    delegating to the internal ``nb_vertices()`` method.

    Returns
    -------
    int
        The number of vertices in the tree.
    """
    return self.nb_vertices()

add_child

add_child(parent, child=None, **kwargs)

Add a child vertex to the tree under the specified parent.

Adds a new child vertex to the tree structure. If no child identifier is provided, a new vertex is automatically created. The child is appended to the parent's list of children.

Parameters:

Name	Type	Description	Default
parent	int	The identifier of the parent vertex to which the child will be attached.	required
child	int	The identifier of the child vertex to attach. If None (default), a new vertex is created automatically.	None

Returns:

Type	Description
int	The identifier of the child vertex that was added.

Raises:

Type	Description
InvalidVertex	If the specified parent does not exist in the tree.

Notes

• If the child identifier already exists in the tree, it is reused.
• If the child identifier does not exist, a new vertex is created and added to the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5

Source code in src/phyllotaxis_analysis/tree.py

def add_child(self, parent, child=None, **kwargs):
    """
    Add a child vertex to the tree under the specified parent.

    Adds a new child vertex to the tree structure. If no child identifier is provided,
    a new vertex is automatically created. The child is appended to the parent's
    list of children.

    Parameters
    ----------
    parent : int
        The identifier of the parent vertex to which the child will be attached.
    child : int, optional
        The identifier of the child vertex to attach. If ``None`` (default), a new
        vertex is created automatically.

    Returns
    -------
    int
        The identifier of the child vertex that was added.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the specified ``parent`` does not exist in the tree.

    Notes
    -----
    - If the ``child`` identifier already exists in the tree, it is reused.
    - If the ``child`` identifier does not exist, a new vertex is created and added
      to the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    """
    if parent not in self:
        raise InvalidVertex(parent)

    if child is None:
        child = self.add_vertex()
    elif child not in self:
        self.add_vertex(child)

    self._parent[child] = parent
    if parent in self._children:
        self._children[parent].append(child)
    else:
        self._children[parent] = [child]

    return child

add_child_tree

add_child_tree(parent, tree)

Add a tree after the children of the parent vertex.

The tree is inserted such that its root becomes a child of the parent vertex, and all other vertices are recursively added as children of their corresponding parent vertices in the new tree. The operation has O(1) complexity when the input tree is a subtree of the current tree.

Parameters:

Name	Type	Description	Default
parent	int	Vertex identifier in the current tree where the new tree will be attached.	required
tree	tree	A rooted tree to be inserted as a subtree under the parent vertex.	required

Returns:

Type	Description
dict	A mapping from vertex identifiers in the input tree to their corresponding vertex identifiers in the current tree after insertion.

Raises:

Type	Description
InvalidVertex	If parent is not a valid vertex in the current tree.

Source code in src/phyllotaxis_analysis/tree.py

def add_child_tree(self, parent, tree):
    """
    Add a tree after the children of the parent vertex.

    The tree is inserted such that its root becomes a child of the parent vertex,
    and all other vertices are recursively added as children of their corresponding
    parent vertices in the new tree. The operation has O(1) complexity when the
    input tree is a subtree of the current tree.

    Parameters
    ----------
    parent : int
        Vertex identifier in the current tree where the new tree will be attached.
    tree : phyllotaxis_analysis.tree
        A rooted tree to be inserted as a subtree under the parent vertex.

    Returns
    -------
    dict
        A mapping from vertex identifiers in the input tree to their corresponding
        vertex identifiers in the current tree after insertion.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `parent` is not a valid vertex in the current tree.
    """
    if parent not in self:
        raise InvalidVertex(parent)

    treeid_id = {}
    root = tree.root
    treeid_id[root] = self.add_child(parent)

    subtree = pre_order(tree, root)
    next(subtree)
    for tid in subtree:
        pid = tree.parent(tid)
        parent = treeid_id[pid]
        v = self.add_child(parent)
        treeid_id[tid] = v

    return treeid_id

add_vertex

add_vertex(vid=None)

Add a vertex to the graph.

Adds a new vertex to the graph with the specified identifier or auto-increments the identifier if not provided.

Parameters:

Name	Type	Description	Default
vid	int	The identifier for the new vertex. If None, the identifier is auto-incremented. Default is None.	None

Returns:

Type	Description
int	The identifier of the added vertex.

Raises:

Type	Description
InvalidVertex	If the provided vid is less than or equal to the current maximum identifier, indicating the identifier is already in use.

Examples:

>>> from phyllotaxis_analysis.tree import InvalidVertex
>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_vertex()
1
>>> tree.add_vertex(vid=5)
5
>>> try:
>>>    tree.add_vertex(vid=3)
>>> except InvalidVertex as e:
>>>    print(f"ERROR: {e}")
ERROR: 'Vertex identifier already used: 3'

Source code in src/phyllotaxis_analysis/tree.py

def add_vertex(self, vid=None):
    """
    Add a vertex to the graph.

    Adds a new vertex to the graph with the specified identifier or auto-increments the identifier if not provided.

    Parameters
    ----------
    vid : int, optional
        The identifier for the new vertex. If ``None``, the identifier is auto-incremented.
        Default is ``None``.

    Returns
    -------
    int
        The identifier of the added vertex.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the provided ``vid`` is less than or equal to the current maximum identifier,
        indicating the identifier is already in use.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import InvalidVertex
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_vertex()
    1
    >>> tree.add_vertex(vid=5)
    5
    >>> try:
    >>>    tree.add_vertex(vid=3)
    >>> except InvalidVertex as e:
    >>>    print(f"ERROR: {e}")
    ERROR: 'Vertex identifier already used: 3'
    """
    if vid is None:
        vid = self._id + 1
        self._id = vid
    elif vid <= self._id:
        raise InvalidVertex(f'Vertex identifier already used: {vid}')
    else:
        self._id = vid

    self._parent[vid] = None
    return vid

children

children(vid)

Return the children of a vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose children are to be retrieved.	required

Returns:

Type	Description
list[int]	A list of vertex identifiers that are children of vid.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.children(0)
[5, 6]
>>> tree.children(5)
[]

Source code in src/phyllotaxis_analysis/tree.py

def children(self, vid):
    """
    Return the children of a vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose children are to be retrieved.

    Returns
    -------
    list[int]
        A list of vertex identifiers that are children of `vid`.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.children(0)
    [5, 6]
    >>> tree.children(5)
    []
    """
    if vid not in self:
        raise InvalidVertex(vid)

    return list(self._children.get(vid, []))

clear

clear()

Remove all vertices and edges from the graph.

This method clears the tree structure by removing all child and parent relationships.

Notes

This method does not delete the root vertex itself, only its relationships.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.nb_vertices()
3
>>> g.clear()
>>> g.nb_vertices()
1

Source code in src/phyllotaxis_analysis/tree.py

def clear(self):
    """
    Remove all vertices and edges from the graph.

    This method clears the tree structure by removing all child and parent relationships.

    Notes
    -----
    This method does not delete the root vertex itself, only its relationships.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.nb_vertices()
    3
    >>> g.clear()
    >>> g.nb_vertices()
    1
    """
    self._children.clear()
    self._parent.clear()
    self._parent[self._root] = None

copy

copy()

Deep copy of the tree.

Returns:

Type	Description
tree	A new instance of the tree with all attributes deeply copied.

Source code in src/phyllotaxis_analysis/tree.py

def copy(self):
    """
    Deep copy of the tree.

    Returns
    -------
    phyllotaxis_analysis.tree
        A new instance of the tree with all attributes deeply copied.
    """
    return deepcopy(self)

edges_iter

edges_iter()

Iterate over the edges of the tree.

Yields:

Type	Description
tuple[int, int]	A tuple of (parent, child) vertices representing each edge in the tree.

Source code in src/phyllotaxis_analysis/tree.py

def edges_iter(self):
    """
    Iterate over the edges of the tree.

    Yields
    ------
    tuple[int, int]
        A tuple of (parent, child) vertices representing each edge in the tree.
    """
    return ((parent, child) for child, parent in self._parent.items())

has_vertex

has_vertex(vid)

Determines whether a given vertex is in the graph.

Parameters:

Name	Type	Description	Default
vid	int or str	The identifier of the vertex to be checked for existence in the graph.	required

Returns:

Type	Description
bool	Returns True if the vertex is present in the graph, False otherwise.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.has_vertex(1)
True
>>> g.has_vertex(2)
False
>>> g.has_vertex(6)
True

Source code in src/phyllotaxis_analysis/tree.py

def has_vertex(self, vid):
    """
    Determines whether a given vertex is in the graph.

    Parameters
    ----------
    vid : int or str
        The identifier of the vertex to be checked for existence in the graph.

    Returns
    -------
    bool
        Returns ``True`` if the vertex is present in the graph, ``False`` otherwise.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.has_vertex(1)
    True
    >>> g.has_vertex(2)
    False
    >>> g.has_vertex(6)
    True
    """
    return vid in self._parent

insert_parent

insert_parent(vid, parent_id=None)

Insert a new vertex between an existing vertex and its parent.

This method modifies the tree structure by inserting parent_id as the new parent of vid, effectively making parent_id a child of vid's original parent and vid a child of parent_id.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose parent will be modified.	required
parent_id	int	The vertex identifier to insert as the new parent. If None, a new vertex is automatically created and used as the parent. Default is None.	None

Returns:

Type	Description
int	The vertex identifier of the newly inserted parent (either the provided parent_id or the automatically created one).

Raises:

Type	Description
InvalidVertex	If vid does not exist in the tree or if vid is the root (has no parent). If parent_id is provided but does not exist in the tree (it will be automatically added in this case).

Notes

• This operation changes the tree structure by reparenting vid and adjusting the children lists of the affected vertices.
• If parent_id is not provided, a new vertex is created and used as the parent.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.children(0)
[5]
>>> tree.insert_parent(5, 6)
6
>>> tree.children(0)
[6]
>>> tree.children(6)
[5]

Source code in src/phyllotaxis_analysis/tree.py

def insert_parent(self, vid, parent_id=None):
    """
    Insert a new vertex between an existing vertex and its parent.

    This method modifies the tree structure by inserting `parent_id` as the new parent
    of `vid`, effectively making `parent_id` a child of `vid`'s original parent and
    `vid` a child of `parent_id`.

    Parameters
    ----------
    vid : int
        The vertex identifier whose parent will be modified.
    parent_id : int, optional
        The vertex identifier to insert as the new parent.
        If ``None``, a new vertex is automatically created and used as the parent.
        Default is ``None``.

    Returns
    -------
    int
        The vertex identifier of the newly inserted parent (either the provided
        `parent_id` or the automatically created one).

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` does not exist in the tree or if `vid` is the root (has no parent).
        If `parent_id` is provided but does not exist in the tree (it will be automatically added in this case).

    Notes
    -----
    - This operation changes the tree structure by reparenting `vid` and adjusting
      the children lists of the affected vertices.
    - If `parent_id` is not provided, a new vertex is created and used as the parent.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.children(0)
    [5]
    >>> tree.insert_parent(5, 6)
    6
    >>> tree.children(0)
    [6]
    >>> tree.children(6)
    [5]
    """
    if vid not in self:
        raise InvalidVertex(vid)

    old_parent = self.parent(vid)
    if old_parent is None:
        raise InvalidVertex("Cannot insert a parent to the root")

    if parent_id is None:
        parent_id = self.add_vertex()
    elif parent_id not in self:
        self.add_vertex(parent_id)

    # Update parent
    self._parent[parent_id] = old_parent
    self._parent[vid] = parent_id

    # Update children
    index = self._children[old_parent].index(vid)
    self._children[old_parent][index] = parent_id

    self._children[parent_id] = [vid]

    return parent_id

insert_sibling

insert_sibling(vid_1, vid_2=None)

Insert a new vertex as a sibling of an existing vertex in the tree.

The new vertex is inserted immediately before the specified vertex in the parent's children list. If no vertex identifier is provided for the new vertex, a new one is automatically generated.

Parameters:

Name	Type	Description	Default
vid_1	int	The vertex identifier of the existing vertex before which the new vertex will be inserted.	required
vid_2	int	The vertex identifier for the new vertex. If None (default), a new vertex identifier is automatically generated.	None

Returns:

Type	Description
int	The vertex identifier of the newly inserted vertex.

Raises:

Type	Description
InvalidVertex	If vid_1 does not exist in the tree or if vid_1 is the root vertex (which cannot have siblings).

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.insert_sibling(5, 6)
6
>>> tree.children(0)
[6, 5]

Source code in src/phyllotaxis_analysis/tree.py

def insert_sibling(self, vid_1, vid_2=None):
    """
    Insert a new vertex as a sibling of an existing vertex in the tree.

    The new vertex is inserted immediately before the specified vertex in the
    parent's children list. If no vertex identifier is provided for the new
    vertex, a new one is automatically generated.

    Parameters
    ----------
    vid_1 : int
        The vertex identifier of the existing vertex before which the new
        vertex will be inserted.
    vid_2 : int, optional
        The vertex identifier for the new vertex. If ``None`` (default),
        a new vertex identifier is automatically generated.

    Returns
    -------
    int
        The vertex identifier of the newly inserted vertex.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If ``vid_1`` does not exist in the tree or if ``vid_1`` is the root
        vertex (which cannot have siblings).

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.insert_sibling(5, 6)
    6
    >>> tree.children(0)
    [6, 5]
    """
    if vid_1 not in self:
        raise InvalidVertex(vid_1)

    parent = self.parent(vid_1)
    if parent is None:
        raise InvalidVertex("Cannot insert a sibling to the root")

    if vid_2 is None:
        vid_2 = self.add_vertex()
    elif vid_2 not in self:
        self.add_vertex(vid_2)

    self._parent[vid_2] = parent

    index = self._children[parent].index(vid_1)
    self._children[parent].insert(index, vid_2)

    return vid_2

insert_sibling_tree

insert_sibling_tree(vid, tree)

Insert a tree as a sibling to the specified vertex.

Inserts a rooted tree as a sibling to the vertex identified by vid. The root of the inserted tree and the vertex vid share the same parent. The operation has O(1) complexity when the tree is obtained via self.subtree().

Parameters:

Name	Type	Description	Default
vid	int	Vertex identifier of the sibling vertex.	required
tree	Tree	A rooted tree to be inserted as a sibling.	required

Returns:

Type	Description
dict	A mapping from vertex identifiers in the original tree to their new identifiers in the modified tree.

Raises:

Type	Description
InvalidVertex	If vid does not exist in the tree. If vid is the root of the tree (cannot insert a sibling to the root).

Source code in src/phyllotaxis_analysis/tree.py

def insert_sibling_tree(self, vid, tree):
    """
    Insert a tree as a sibling to the specified vertex.

    Inserts a rooted tree as a sibling to the vertex identified by `vid`.
    The root of the inserted tree and the vertex `vid` share the same parent.
    The operation has O(1) complexity when the tree is obtained via `self.subtree()`.

    Parameters
    ----------
    vid : int
        Vertex identifier of the sibling vertex.
    tree : phyllotaxis_analysis.tree.Tree
        A rooted tree to be inserted as a sibling.

    Returns
    -------
    dict
        A mapping from vertex identifiers in the original `tree` to their new
        identifiers in the modified tree.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` does not exist in the tree.
        If `vid` is the root of the tree (cannot insert a sibling to the root).
    """
    if vid not in self:
        raise InvalidVertex(vid)

    parent = self.parent(vid)
    if parent is None:
        raise InvalidVertex("Cannot insert a sibling to the root")

    treeid_id = {}
    root = tree.root
    treeid_id[root] = self.add_vertex()

    self._parent[treeid_id[root]] = parent
    index = self._children[parent].index(vid)
    self._children[parent].insert(index, treeid_id[root])

    subtree = pre_order(tree, root)
    next(subtree)
    for tid in subtree:
        pid = tree.parent(tid)
        parent = treeid_id[pid]
        v = self.add_child(parent)
        treeid_id[tid] = v

    return treeid_id

is_leaf

is_leaf(vid)

Test if a vertex is a leaf in the tree.

A leaf vertex is defined as a vertex with no children.

Parameters:

Name	Type	Description	Default
vid	int	The ID of the vertex to test.	required

Returns:

Type	Description
bool	True if the vertex is a leaf (has no children), False otherwise.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.is_leaf(5)
True
>>> tree.is_leaf(0)
False

Source code in src/phyllotaxis_analysis/tree.py

def is_leaf(self, vid):
    """
    Test if a vertex is a leaf in the tree.

    A leaf vertex is defined as a vertex with no children.

    Parameters
    ----------
    vid : int
        The ID of the vertex to test.

    Returns
    -------
    bool
        ``True`` if the vertex is a leaf (has no children), ``False`` otherwise.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.is_leaf(5)
    True
    >>> tree.is_leaf(0)
    False
    """
    return self.nb_children(vid) == 0

nb_children

nb_children(vid)

Return the number of children of a given vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose children count is requested.	required

Returns:

Type	Description
int	The number of children of the vertex.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.nb_children(0)
2

Source code in src/phyllotaxis_analysis/tree.py

def nb_children(self, vid):
    """
    Return the number of children of a given vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose children count is requested.

    Returns
    -------
    int
        The number of children of the vertex.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.nb_children(0)
    2
    """
    if vid not in self:
        raise InvalidVertex(vid)

    return len(self._children.get(vid, []))

nb_siblings

nb_siblings(vid)

Return the number of siblings of a given vertex identifier.

Parameters:

Name	Type	Description	Default
vid	int	The identifier of the vertex whose siblings are to be counted.	required

Returns:

Type	Description
int	The number of siblings of the vertex with the identifier vid.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.nb_siblings(5)
1

Source code in src/phyllotaxis_analysis/tree.py

def nb_siblings(self, vid):
    """
    Return the number of siblings of a given vertex identifier.

    Parameters
    ----------
    vid : int
        The identifier of the vertex whose siblings are to be counted.

    Returns
    -------
    int
        The number of siblings of the vertex with the identifier ` vid `.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.nb_siblings(5)
    1
    """
    return len(self.siblings(vid))

nb_vertices

nb_vertices()

Returns the number of vertices in the graph.

Returns:

Type	Description
int	The number of vertices in the graph.

See Also

nb_edges : Returns the number of edges in the graph.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex()  # add a second vertices
>>> g.nb_vertices()
3

Source code in src/phyllotaxis_analysis/tree.py

def nb_vertices(self):
    """
    Returns the number of vertices in the graph.

    Returns
    -------
    int
        The number of vertices in the graph.

    See Also
    --------
    nb_edges : Returns the number of edges in the graph.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex()  # add a second vertices
    >>> g.nb_vertices()
    3
    """
    return len(self._parent)

parent

parent(vid)

Return the parent of a vertex in the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose parent is to be retrieved.	required

Returns:

Type	Description
int | None	The parent vertex identifier. Returns None if the vertex is the root.

Raises:

Type	Description
InvalidVertex	If the vertex identifier vid is not found in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.parent(5)
0

Source code in src/phyllotaxis_analysis/tree.py

def parent(self, vid):
    """
    Return the parent of a vertex in the tree.

    Parameters
    ----------
    vid : int
        The vertex identifier whose parent is to be retrieved.

    Returns
    -------
    int | None
        The parent vertex identifier. Returns ``None`` if the vertex is the root.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the vertex identifier `vid` is not found in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.parent(5)
    0
    """
    try:
        return self._parent[vid]
    except KeyError:
        raise InvalidVertex(vid)

remove_leaf

remove_leaf(vid)

Remove a leaf vertex from the tree.

The vertex identified by vid is removed only if it is a leaf (has no children) and it is not the root of the tree. The parent–child relationships stored in _children and _parent are updated accordingly.

Parameters:

Name	Type	Description	Default
vid	int	Identifier of the vertex to be removed.	required

Raises:

Type	Description
InvalidVertex	If vid is the root vertex. If vid has one or more children (i.e., is not a leaf).

Notes

• The method mutates the internal _children and _parent mappings of the tree instance.
• Attempting to remove a vertex that does not exist in the internal structures has no effect.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0)
1
>>> tree.is_leaf(1)
True
>>> tree.remove_leaf(1)        # removes leaf vertex 1
>>> tree.is_leaf(0)
True
>>> tree.remove_leaf(0)        # cannot remove the root
phyllotaxis_analysis.tree.InvalidVertex: 'The root node 0 can not be removed.'

Source code in src/phyllotaxis_analysis/tree.py

def remove_leaf(self, vid):
    """Remove a leaf vertex from the tree.

    The vertex identified by ``vid`` is removed only if it is a leaf (has no
    children) and it is not the root of the tree.  The parent–child
    relationships stored in ``_children`` and ``_parent`` are updated
    accordingly.

    Parameters
    ----------
    vid : int
        Identifier of the vertex to be removed.

    Raises
    ------
    InvalidVertex
        If ``vid`` is the root vertex.
        If ``vid`` has one or more children (i.e., is not a leaf).

    Notes
    -----
    * The method mutates the internal ``_children`` and ``_parent`` mappings
      of the tree instance.
    * Attempting to remove a vertex that does not exist in the internal
      structures has no effect.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0)
    1
    >>> tree.is_leaf(1)
    True
    >>> tree.remove_leaf(1)        # removes leaf vertex 1
    >>> tree.is_leaf(0)
    True
    >>> tree.remove_leaf(0)        # cannot remove the root
    phyllotaxis_analysis.tree.InvalidVertex: 'The root node 0 can not be removed.'
    """
    if vid == self.root:
        raise InvalidVertex("The root node %d can not be removed." % vid)

    if self.is_leaf(vid):
        pid = self.parent(vid)
        if pid is not None:
            self._children[pid].remove(vid)
            del self._parent[vid]
        if vid in self._children:
            del self._children[vid]
    else:
        raise InvalidVertex(
            "Can not remove vertex %d with children. Only leaves can be removed. You need to remove the children first." % vid)

remove_tree

remove_tree(vid)

Remove the subtree rooted on vid.

Remove the subtree rooted at the vertex with ID vid from the tree.

Parameters:

Name	Type	Description	Default
vid	int	The vertex ID of the root of the subtree to remove.	required

Returns:

Type	Description
list	The list of vertex IDs that were removed from the tree.

Raises:

Type	Description
InvalidVertex	If vid is not a valid vertex in the tree or if vid is the root of the tree.
TypeError	If vid is not an integer.

Source code in src/phyllotaxis_analysis/tree.py

def remove_tree(self, vid):
    """
    Remove the subtree rooted on `vid`.

    Remove the subtree rooted at the vertex with ID `vid` from the tree.

    Parameters
    ----------
    vid : int
        The vertex ID of the root of the subtree to remove.

    Returns
    -------
    list
        The list of vertex IDs that were removed from the tree.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not a valid vertex in the tree or if `vid` is the root of the tree.
    TypeError
        If `vid` is not an integer.
    """
    if vid not in self:
        raise InvalidVertex(vid)
    if vid == self.root:
        raise InvalidVertex("Cannot remove the root of the tree")

    # Get all vertices to remove
    vertices = list(pre_order(self, vid))
    # Remove the subtree
    parent = self.parent(vid)
    self._children[parent].remove(vid)

    for vid in vertices:
        if vid in self._children:
            del self._children[vid]
        del self._parent[vid]

    return vertices

remove_vertex

remove_vertex(vid, reparent_child=False)

Remove a vertex from the tree.

Parameters:

Name	Type	Description	Default
vid	int	The id of the vertex to remove.	required
reparent_child	bool	If True, reparents all children of the removed vertex to its parent. Default is False.	False

Returns:

Type	Description
int	The id of the removed vertex if it had no children, otherwise raises InvalidVertex.

Raises:

Type	Description
InvalidVertex	If the vertex to be removed is the root vertex or if it has children.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.remove_vertex(1)
1
>>> g.remove_vertex(2)
phyllotaxis_analysis.tree.interface.InvalidVertex: 2

Source code in src/phyllotaxis_analysis/tree.py

def remove_vertex(self, vid, reparent_child=False):
    """
    Remove a vertex from the tree.

    Parameters
    ----------
    vid : int
        The id of the vertex to remove.
    reparent_child : bool, optional
        If ``True``, reparents all children of the removed vertex to its parent.
        Default is ``False``.

    Returns
    -------
    int
        The id of the removed vertex if it had no children, otherwise raises ``InvalidVertex``.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If the vertex to be removed is the root vertex or if it has children.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.remove_vertex(1)
    1
    >>> g.remove_vertex(2)
    phyllotaxis_analysis.tree.interface.InvalidVertex: 2
    """
    if vid == self._root:
        raise InvalidVertex(f'Removing the root vertex {vid} is forbidden.')

    if reparent_child:
        new_parent_id = self.parent(vid)
        for cid in self.children(vid):
            self.replace_parent(cid, new_parent_id)

    if self.nb_children(vid) == 0:
        p = self.parent(vid)
        if p is not None:
            self._children[p].remove(vid)
        del self._parent[vid]
        return vid
    else:
        raise InvalidVertex(f'Can not remove vertex {vid} with children.')

replace_parent

replace_parent(vid, new_parent_id)

Change the parent of a vertex to a new parent vertex.

Parameters:

Name	Type	Description	Default
vid	int	The vertex ID whose parent will be changed.	required
new_parent_id	int	The new parent vertex ID.	required

Raises:

Type	Description
InvalidVertex	If vid or new_parent_id does not exist in the tree. If attempting to change the parent of the root vertex (which has no parent).

Notes

The old parent relationship is removed when the new parent is assigned.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.children(0)
[5]
>>> tree.insert_parent(5, 6)
6
>>> tree.add_vertex(7)
7
>>> tree.replace_parent(5, 7)
>>> tree.parent(5)
7
>>> tree.children(0)
[6]
>>> tree.parent(7)
None

Source code in src/phyllotaxis_analysis/tree.py

def replace_parent(self, vid, new_parent_id):
    """
    Change the parent of a vertex to a new parent vertex.

    Parameters
    ----------
    vid : int
        The vertex ID whose parent will be changed.
    new_parent_id : int
        The new parent vertex ID.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` or `new_parent_id` does not exist in the tree.
        If attempting to change the parent of the root vertex (which has no parent).

    Notes
    -----
    The old parent relationship is removed when the new parent is assigned.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.children(0)
    [5]
    >>> tree.insert_parent(5, 6)
    6
    >>> tree.add_vertex(7)
    7
    >>> tree.replace_parent(5, 7)
    >>> tree.parent(5)
    7
    >>> tree.children(0)
    [6]
    >>> tree.parent(7)
    None
    """
    if vid not in self:
        raise InvalidVertex(vid)
    if new_parent_id not in self:
        raise InvalidVertex(new_parent_id)

    old_parent = self.parent(vid)
    if old_parent is None:
        raise InvalidVertex("Cannot replace parent of the root")

    # Update parent
    self._parent[vid] = new_parent_id

    # Update children
    self._children[old_parent].remove(vid)
    if new_parent_id in self._children:
        self._children[new_parent_id].append(vid)
    else:
        self._children[new_parent_id] = [vid]

siblings

siblings(vid)

Return the siblings of a given vertex identifier in the tree.

Given a vertex identifier vid, this method returns a list of all sibling vertices (i.e., vertices sharing the same parent). If the vertex has no parent (i.e., it is the root), an empty list is returned.

Parameters:

Name	Type	Description	Default
vid	int	The vertex identifier whose siblings are to be retrieved.	required

Returns:

Type	Description
list	The list of vertex identifiers that are siblings of vid. Empty if vid is the root or does not exist.

Raises:

Type	Description
InvalidVertex	If vid is not present in the tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0, 5)
5
>>> tree.add_child(0)
6
>>> tree.siblings(0)
[]
>>> tree.siblings(5)
[6]

Source code in src/phyllotaxis_analysis/tree.py

def siblings(self, vid):
    """
    Return the siblings of a given vertex identifier in the tree.

    Given a vertex identifier `vid`, this method returns a list of all sibling
    vertices (i.e., vertices sharing the same parent). If the vertex has no
    parent (i.e., it is the root), an empty list is returned.

    Parameters
    ----------
    vid : int
        The vertex identifier whose siblings are to be retrieved.

    Returns
    -------
    list
        The list of vertex identifiers that are siblings of `vid`. Empty if `vid`
        is the root or does not exist.

    Raises
    ------
    phyllotaxis_analysis.tree.InvalidVertex
        If `vid` is not present in the tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0, 5)
    5
    >>> tree.add_child(0)
    6
    >>> tree.siblings(0)
    []
    >>> tree.siblings(5)
    [6]
    """
    if vid not in self:
        raise InvalidVertex(vid)

    parent = self.parent(vid)
    if parent is None:
        return []
    else:
        sibs = list(self.children(parent))
        sibs.remove(vid)
        return sibs

subtree

subtree(vid, copy=True)

Return the subtree containing all descendants of vid.

The induced subtree of the tree has the vertices in the subtree rooted at vid. This creates a new tree that includes all vertices from vid and all its descendants.

Parameters:

Name	Type	Description	Default
vid	int	A vertex of the original tree.	required
copy	bool	If True, return a new tree holding the subtree. If False, the subtree is created using the original tree by deleting all vertices not in the subtree. Default is True.	True

Returns:

Type	Description
Tree	A subtree of the tree. If copy is True, a new Tree is returned. Else the subtree is created in-place by modifying the original tree.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> tree.add_child(0)
1
>>> tree.insert_parent(1)
2
>>> tree.insert_sibling(1)
3
>>> subtree = tree.subtree(2, copy=True)
>>> subtree.vertices()
[0, 1, 2]
>>> subtree.root
0
'leaf1'

Source code in src/phyllotaxis_analysis/tree.py

def subtree(self, vid, copy=True):
    """
    Return the subtree containing all descendants of `vid`.

    The induced subtree of the tree has the vertices in the subtree rooted at `vid`.
    This creates a new tree that includes all vertices from `vid` and all its descendants.

    Parameters
    ----------
    vid : int
        A vertex of the original tree.
    copy : bool, optional
        If ``True``, return a new tree holding the subtree. If ``False``, the subtree is
        created using the original tree by deleting all vertices not in the subtree.
        Default is ``True``.

    Returns
    ------- 
    phyllotaxis_analysis.tree.Tree
        A subtree of the tree. If `copy` is ``True``, a new ``Tree`` is returned.
        Else the subtree is created in-place by modifying the original tree.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> tree = Tree()
    >>> tree.add_child(0)
    1
    >>> tree.insert_parent(1)
    2
    >>> tree.insert_sibling(1)
    3
    >>> subtree = tree.subtree(2, copy=True)
    >>> subtree.vertices()
    [0, 1, 2]
    >>> subtree.root
    0
    'leaf1'
    """
    if not copy:
        # remove all vertices not in the subtree
        bunch = set(pre_order(self, vid))
        remove_bunch = set(self) - bunch

        for vid in remove_bunch:
            # remove parent edge
            pid = self.parent(vid)
            if pid is not None:
                self._children[pid].remove(vid)
                del self._parent[vid]
            # remove children edges
            for cid in self.children(vid):
                self._parent[cid] = None
            if vid in self._children:
                del self._children[vid]

        self.root = vid
        return self
    else:
        treeid_id = {}
        tree = self.__class__()
        tree.root = 0

        treeid_id[vid] = tree.root
        subtree = pre_order(self, vid)
        next(subtree)
        for vid in subtree:
            pid = self.parent(vid)
            if pid is not None:
                parent = treeid_id[pid]
                v = tree.add_child(parent)
                treeid_id[vid] = v

        return tree

vertices

vertices()

Returns the list of vertices in the graph.

Returns:

Type	Description
list	The list of the vertices in the graph.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> g = Tree()  # initialize a new tree with a single vertex (the root)
>>> g.add_vertex()  # add a first vertices
>>> g.add_vertex(6)  # add a second vertices
>>> g.vertices()
[0, 1, 6]

Source code in src/phyllotaxis_analysis/tree.py

def vertices(self):
    """
    Returns the list of vertices in the graph.

    Returns
    -------
    list
        The list of the vertices in the graph.

    Examples
    --------
    >>> from phyllotaxis_analysis.tree import Tree
    >>> g = Tree()  # initialize a new tree with a single vertex (the root)
    >>> g.add_vertex()  # add a first vertices
    >>> g.add_vertex(6)  # add a second vertices
    >>> g.vertices()
    [0, 1, 6]
    """
    return list(self.vertices_iter())

vertices_iter

vertices_iter()

Generates an iterator for the vertices in the graph.

This method is a generator that yields each vertex in the graph as a string, which corresponds to the key of the vertex in the internal dictionary representation of the graph. The order in which vertices are returned by this iterator is not guaranteed to be consistent between different calls or even different yields.

Yields:

Type	Description
str	A string representing the vertex in the graph.

Source code in src/phyllotaxis_analysis/tree.py

def vertices_iter(self):
    """
    Generates an iterator for the vertices in the graph.

    This method is a generator that yields each vertex in the graph as a string,
    which corresponds to the key of the vertex in the internal dictionary representation
    of the graph. The order in which vertices are returned by this iterator is not
    guaranteed to be consistent between different calls or even different yields.

    Yields
    ------
    str
        A string representing the vertex in the graph.
    """
    return iter(self._parent.keys())