Skip to content

interface

phyllotaxis_analysis.tree.interface Link

Tree Interfaces

This module provides interfaces for tree data structures used in the phyllotaxis analysis.

Acknowledgements: This is a port of the original openalea.container.interface.tree and openalea.container.interface.graph Python2 implementation by Jerome Chopard jerome.chopard@sophia.inria.fr and Christophe Pradal christophe.pradal@cirad.fr.

Key Features: - Defines base interfaces for tree operations - Provides error classes for tree manipulation - Supports rooted, mutable, and editable tree interfaces

Usage Examples: 

from phyllotaxis_analysis.tree import Tree, PropertyTree
from phyllotaxis_analysis.tree.interface import ITree, IMutableTree

# Create a tree that implements these interfaces
my_tree = Tree()

GraphError Link

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.

IEditableTree Link

Bases: object

Interface for an editable tree.

An editable tree is a tree where subtrees can be added or removed. This interface defines methods to manipulate subtrees.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> # Create a tree
>>> tree = Tree()
>>> child1 = tree.add_child(tree.root)
>>> child2 = tree.add_child(tree.root)
>>> grandchild = tree.add_child(child1)
>>> 
>>> # Create a subtree
>>> subtree = tree.sub_tree(child1, copy=True)
>>> 
>>> # Add the subtree as a child of child2
>>> tree.add_child_tree(child2, subtree)

add_child_tree Link

add_child_tree(parent, tree)

Add a tree after the children of the parent vertex.

Parameters:

Name Type Description Default
parent int

Vertex identifier.

 required
tree Tree

A rooted tree.

 required

Returns:

Type Description
dict

A dictionary mapping tree vertex identifiers to self vertex identifiers.

Raises:

Type Description
InvalidVertex

If parent does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
def add_child_tree(self, parent: int, tree: 'Tree') -> dict:
    """
    Add a tree after the children of the parent vertex.

    Parameters
    ----------
    parent : int
        Vertex identifier.
    tree : Tree
        A rooted tree.

    Returns
    -------
    dict
        A dictionary mapping tree vertex identifiers to self vertex identifiers.

    Raises
    ------
    InvalidVertex
        If parent does not exist in the tree.
    """
    raise NotImplementedError

insert_sibling_tree Link

insert_sibling_tree(vid, tree)

Insert a tree before the vid.

vid and the root of the tree are siblings.

Parameters:

Name Type Description Default
vid int

Vertex identifier.

 required
tree Tree

A rooted tree.

 required

Returns:

Type Description
dict

A dictionary mapping tree vertex identifiers to self vertex identifiers.

Raises:

Type Description
InvalidVertex

If vid does not exist in the tree or is the root.
Source code in src/phyllotaxis_analysis/tree/interface.py 
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
def insert_sibling_tree(self, vid: int, tree: 'Tree') -> dict:
    """
    Insert a tree before the vid.

    vid and the root of the tree are siblings.

    Parameters
    ----------
    vid : int
        Vertex identifier.
    tree : Tree
        A rooted tree.

    Returns
    -------
    dict
        A dictionary mapping tree vertex identifiers to self vertex identifiers.

    Raises
    ------
    InvalidVertex
        If vid does not exist in the tree or is the root.
    """
    raise NotImplementedError

remove_tree Link

remove_tree(vid)

Remove the sub tree rooted on vid.

Parameters:

Name Type Description Default
vid int

Vertex identifier.

 required

Returns:

Type Description
list

List of removed vertex identifiers.

Raises:

Type Description
InvalidVertex

If vid does not exist in the tree or is the root.
Source code in src/phyllotaxis_analysis/tree/interface.py 
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
def remove_tree(self, vid: int) -> list:
    """
    Remove the sub tree rooted on `vid`.

    Parameters
    ----------
    vid : int
        Vertex identifier.

    Returns
    -------
    list
        List of removed vertex identifiers.

    Raises
    ------
    InvalidVertex
        If vid does not exist in the tree or is the root.
    """
    raise NotImplementedError

sub_tree Link

sub_tree(vid, copy=True)

Return the subtree rooted on vid.

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. Default is True.

 True

Returns:

Type Description
Tree

A sub tree of the tree. If copy=True, a new Tree is returned. Else the subtree is created inplace by modifying the original tree.

Raises:

Type Description
InvalidVertex

If vid does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
def sub_tree(self, vid: int, copy: bool = True) -> 'Tree':
    """
    Return the subtree rooted on `vid`.

    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.
        Default is True.

    Returns
    -------
    Tree
        A sub tree of the tree. If copy=True, a new Tree is returned.
        Else the subtree is created inplace by modifying the original tree.

    Raises
    ------
    InvalidVertex
        If vid does not exist in the tree.
    """
    raise NotImplementedError

IMutableTree Link

Bases: object

Interface for a mutable tree.

A mutable tree is a tree where vertices can be added or removed. This interface defines methods to modify the tree structure.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree()
>>> child1 = tree.add_child(tree.root)
>>> child2 = tree.add_child(tree.root)
>>> sibling = tree.insert_sibling(child1)
>>> parent = tree.insert_parent(child2)
>>> tree.nb_children(tree.root) == 3  # root has 3 children now
True

add_child Link

add_child(parent, child=None)

Add a child to the parent.

Parameters:

Name Type Description Default
parent int

The parent identifier.

 required
child int

The child identifier. If None, a new vertex is created.

 None

Returns:

Type Description
int

The identifier of the added child vertex.

Raises:

Type Description
InvalidVertex

If the parent vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
def add_child(self, parent: int, child: int = None) -> int:
    """
    Add a child to the parent.

    Parameters
    ----------
    parent : int
        The parent identifier.
    child : int, optional
        The child identifier. If None, a new vertex is created.

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

    Raises
    ------
    InvalidVertex
        If the parent vertex does not exist in the tree.
    """
    raise NotImplementedError

insert_parent Link

insert_parent(vid, parent_id=None)

Insert parent_id between vid and its actual parent.

Parameters:

Name Type Description Default
vid int

A vertex identifier.

 required
parent_id int

A vertex identifier. If None, a new vertex is created.

 None

Returns:

Type Description
int

The identifier of the inserted parent vertex.

Raises:

Type Description
InvalidVertex

If vid does not exist in the tree or is the root.
Source code in src/phyllotaxis_analysis/tree/interface.py 
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
def insert_parent(self, vid: int, parent_id: int = None) -> int:
    """
    Insert parent_id between vid and its actual parent.

    Parameters
    ----------
    vid : int
        A vertex identifier.
    parent_id : int, optional
        A vertex identifier. If None, a new vertex is created.

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

    Raises
    ------
    InvalidVertex
        If vid does not exist in the tree or is the root.
    """
    raise NotImplementedError

insert_sibling Link

insert_sibling(vid_1, vid_2=None)

Insert vid2 before vid1.

Parameters:

Name Type Description Default
vid_1 int

A vertex identifier.

 required
vid_2 int

The vertex to insert. If None, a new vertex is created.

 None

Returns:

Type Description
int

The identifier of the inserted vertex.

Raises:

Type Description
InvalidVertex

If vid1 does not exist in the tree or is the root.
Source code in src/phyllotaxis_analysis/tree/interface.py 
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
def insert_sibling(self, vid_1: int, vid_2: int = None) -> int:
    """
    Insert vid2 before vid1.

    Parameters
    ----------
    vid_1 : int
        A vertex identifier.
    vid_2 : int, optional
        The vertex to insert. If None, a new vertex is created.

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

    Raises
    ------
    InvalidVertex
        If vid1 does not exist in the tree or is the root.
    """
    raise NotImplementedError

IRootedGraph Link

Bases: object

Interface for a rooted graph.

A rooted graph is a graph with a distinguished vertex called the root. This interface defines methods to get and set the root vertex.

Attributes:

Name Type Description
root int

The identifier of the root vertex. This is a property that can be get or set.

Examples:

>>> from phyllotaxis_analysis.tree import Tree
>>> tree = Tree(root=0)
>>> tree.root
0
>>> tree.root = 1  # Set a new root
>>> tree.root
1

get_root Link

get_root()

Return the root of the graph.

Returns:

Type Description
int

The identifier of the root vertex.
Source code in src/phyllotaxis_analysis/tree/interface.py 
113
114
115
116
117
118
119
120
121
def get_root(self) -> int:
    """Return the root of the graph.

    Returns
    -------
    int
        The identifier of the root vertex.
    """
    raise NotImplementedError

set_root Link

set_root(vid)

Set the root of the graph.

Parameters:

Name Type Description Default
vid int

The vertex identifier to use as root.

 required

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the graph.
Source code in src/phyllotaxis_analysis/tree/interface.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def set_root(self, vid: int) -> None:
    """Set the root of the graph.

    Parameters
    ----------
    vid : int
        The vertex identifier to use as root.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the graph.
    """
    raise NotImplementedError

ITree Link

Bases: object

Interface for a tree.

A tree is a directed graph with a distinguished vertex, called the root, such that there is a unique directed path from the root to any other vertex. This interface defines methods to navigate and query the tree structure.

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.parent(grandchild) == child1
True
>>> len(tree.children(tree.root)) == 2
True
>>> tree.is_leaf(grandchild)
True

children Link

children(vid)

Return the children of vid.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
list of int

The identifiers of the children vertices.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def children(self, vid: int) -> list:
    """
    Return the children of `vid`.

    Parameters
    ----------
    vid : int
        The vertex identifier.

    Returns
    -------
    list of int
        The identifiers of the children vertices.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

is_leaf Link

is_leaf(vid)

Test if vid is a leaf.

A leaf is a vertex with no children.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
bool

True if the vertex is a leaf, False otherwise.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
def is_leaf(self, vid: int) -> bool:
    """
    Test if `vid` is a leaf.

    A leaf is a vertex with no children.

    Parameters
    ----------
    vid : int
        The vertex identifier.

    Returns
    -------
    bool
        True if the vertex is a leaf, False otherwise.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

nb_children Link

nb_children(vid)

Return the number of children of vid.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
int

The number of children.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def nb_children(self, vid: int) -> int:
    """
    Return the number of children of `vid`.

    Parameters
    ----------
    vid : int
        The vertex identifier.

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

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

nb_siblings Link

nb_siblings(vid)

Return the number of siblings of vid.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
int

The number of siblings.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
def nb_siblings(self, vid: int) -> int:
    """
    Return the number of siblings of `vid`.

    Parameters
    ----------
    vid : int
        The vertex identifier.

    Returns
    -------
    int
        The number of siblings.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

parent Link

parent(vid)

Return the parent of vid.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
int or None

The identifier of the parent vertex, or None if vid is the root.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def parent(self, vid: int) -> int:
    """
    Return the parent of `vid`.

    Parameters
    ----------
    vid : int
        The vertex identifier.

    Returns
    -------
    int or None
        The identifier of the parent vertex, or None if `vid` is the root.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

siblings Link

siblings(vid)

Return the siblings of vid.

Parameters:

Name Type Description Default
vid int

The vertex identifier.

 required

Returns:

Type Description
list of int

The identifiers of the sibling vertices.

Raises:

Type Description
InvalidVertex

If the vertex does not exist in the tree.
Source code in src/phyllotaxis_analysis/tree/interface.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def siblings(self, vid: int) -> list:
    """
    Return the siblings of `vid`.

    Parameters
    ----------
    vid : int
        The vertex identifier.

    Returns
    -------
    list of int
        The identifiers of the sibling vertices.

    Raises
    ------
    InvalidVertex
        If the vertex does not exist in the tree.
    """
    raise NotImplementedError

InvalidEdge Link

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 Link

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:

>>> try:
...     graph.vertex_property(999)  # Vertex 999 doesn't exist
... except InvalidVertex:
...     print("Vertex doesn't exist")
Vertex doesn't exist