Skip to content

n_admissible_tree

phyllotaxis_analysis.n_admissible_tree Link

Nadmissibletree Link

Nadmissibletree()

Bases: PropertyTree

A class that adds some methods to PropertyTree to construct and explore an n-admissible tree.

This class extends PropertyTree with functionality specific to n-admissible trees, including methods for adding children with properties, retrieving leaves at specific levels, and traversing paths from leaves to the root.

Attributes:

Name Type Description
max_level int

The maximum level reached in the tree. Initialized to -1.

Initialize a new n-admissible tree with default properties.

This constructor initializes an empty n-admissible tree, setting the maximum level to -1 and delegating further initialization to the parent PropertyTree class.

Attributes:

Name Type Description
max_level int

The current maximum level of the tree. Initialized to -1.
data dict

The underlying data structure inherited from PropertyTree.
See Also

PropertyTree : Parent class providing core tree functionality.

Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(self):
    """
    Initialize a new n-admissible tree with default properties.

    This constructor initializes an empty n-admissible tree, setting the
    maximum level to -1 and delegating further initialization to the parent
    `PropertyTree` class.

    Attributes
    ----------
    max_level : int
        The current maximum level of the tree. Initialized to -1.
    data : dict
        The underlying data structure inherited from `PropertyTree`.

    See Also
    --------
    PropertyTree : Parent class providing core tree functionality.
    """
    self.max_level = -1
    PropertyTree.__init__(self)

root property writable Link

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__ Link

__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 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
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__ Link

__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 
221
222
223
224
225
226
227
228
229
230
231
232
233
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__ Link

__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 
147
148
149
150
151
152
153
154
155
156
157
158
159
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 Link

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

Add child with properties to the tree.

Add a child vertex to the tree with specified properties. If a child with the same value and level already exists under the given parent, its ID is returned. Otherwise, a new child is created with the provided properties.

Parameters:

Name Type Description Default
parent int

The ID of the parent vertex to which the child will be added.

 required
child int

The value of the child vertex.

 None
level int

The level (depth) of the child vertex in the tree.

 None

Other Parameters:

Name Type Description
pb_angle float

The probability angle for the child vertex. Default to None
log_pb_angle float

The log probability angle for the child vertex. Default to None
question_mark bool

Default to False
order_index int

The order index of the child vertex. Default to None

Returns:

Type Description
int

The ID of the child vertex (existing or newly created).
Notes

If the level of the new child exceeds the current max_level of the tree, max_level is updated to the new level.

Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def add_child(self, parent, child=None, level=None, **properties):
    """
    Add child with properties to the tree.

    Add a child vertex to the tree with specified properties. If a child with the same
    `value` and `level` already exists under the given `parent`, its ID is returned.
    Otherwise, a new child is created with the provided properties.

    Parameters
    ----------
    parent : int
        The ID of the parent vertex to which the child will be added.
    child : int
        The value of the child vertex.
    level : int
        The level (depth) of the child vertex in the tree.

    Other Parameters
    ----------------
    pb_angle : float
        The probability angle for the child vertex. Default to ``None``
    log_pb_angle : float
        The log probability angle for the child vertex. Default to ``None``
    question_mark : bool
        Default to ``False``
    order_index : int
        The order index of the child vertex. Default to ``None``

    Returns
    -------
    int
        The ID of the child vertex (existing or newly created).

    Notes
    -----
    If the `level` of the new child exceeds the current `max_level` of the tree,
    `max_level` is updated to the new level.
    """
    # Iterate over current children of the parent to check for duplicates
    for child_id in self.children(parent):
        # Retrieve stored properties of each child vertex
        prop = self.get_vertex_property(child_id)
        # If a child with the same value and level exists, return its ID
        if (prop["value"] == child) and (prop["level"] == level):
            # Already in the tree
            return child_id
    else:
        # Update the tree's maximum depth if this child goes deeper
        if level is not None and level > self.max_level:
            self.max_level = level
        # Prepare property dictionary for the new child vertex
        kwargs = {
            'value': child,
            'level': level,
            'node_prb': properties.get('pb_angle', None),
            'node_log_prob': properties.get('log_pb_angle', None),
            'question_mark': properties.get('question_mark', False),
            'order_index': properties.get('order_index', None)
        }
        # Recursively add the new child with the assembled properties
        return super().add_child(parent, child=None, **kwargs)

add_child_tree Link

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 
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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_list_value_level_prob Link

add_list_value_level_prob(current_id, list_value_level)

Add vertices given their IDs and values to a parent vertex and update its probability and order index.

This method iterates over a list of child vertex specifications and adds each as a child to the specified parent vertex. Each child is defined by its value, level, probability, log probability, and order index.

Parameters:

Name Type Description Default
current_id int

The ID of the parent vertex to which new child vertices will be added.

 required
list_value_level list[tuple]

A list of tuples where each tuple contains: - child : float The child vertex id. - level : int The level (depth) of the child vertex in the tree. - pb_angle : float The probability angle for the child vertex. - log_pb_angle : float The log probability angle for the child vertex. - order_index : int The order index of the child vertex.

 required

Returns:

Type Description
int

The ID of the last added child vertex.
Notes

This method modifies the tree structure by adding new vertices and updating the parent's probability and order index. The exact update logic is handled by the internal addChild method.

Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def add_list_value_level_prob(self, current_id, list_value_level):
    """
    Add vertices given their IDs and values to a parent vertex and update its probability and order index.

    This method iterates over a list of child vertex specifications and adds each as a child
    to the specified parent vertex. Each child is defined by its value, level, probability,
    log probability, and order index.

    Parameters
    ----------
    current_id : int
        The ID of the parent vertex to which new child vertices will be added.
    list_value_level : list[tuple]
        A list of tuples where each tuple contains:
        - child : float
            The child vertex id.
        - level : int
            The level (depth) of the child vertex in the tree.
        - pb_angle : float
            The probability angle for the child vertex.
        - log_pb_angle : float
            The log probability angle for the child vertex.
        - order_index : int
            The order index of the child vertex.

    Returns
    -------
    int
        The ID of the last added child vertex.

    Notes
    -----
    This method modifies the tree structure by adding new vertices and updating the parent's
    probability and order index. The exact update logic is handled by the internal `addChild` method.
    """
    for vtx in list_value_level:
        kwargs = dict(zip(["child", "level", "pb_angle", "log_pb_angle", "order_index"], vtx))
        current_id = self.add_child(parent=current_id, **kwargs)

add_property Link

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 
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
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_property_from_leaves Link

add_property_from_leaves(n)

Add a permutation_length vertex property and compute its values from leaf to root paths.

Parameters:

Name Type Description Default
n int

The size parameter passed to is_n_admissible_integers. It determines the admissible integer sequences that are examined for each leaf‑to‑root path.

 required

Returns:

Type Description
list[list[tuple]]

A list where each element corresponds to a leaf vertex. Each inner list contains tuples (vertex_id, order_index) representing the vertices on the path from that leaf to the root (ordered from root to leaf). The returned structure can be used to inspect the paths that were processed.
Notes
  • The method mutates the graph by adding a new vertex property; the property is always present after the call, regardless of the returned value.
  • The printed output is intended for debugging and can be redirected or silenced by adjusting the caller’s logging configuration.
  • order_index_to_vid maps each order_index encountered on a path to its vertex identifier, enabling the assignment of the permutation length to the correct vertex.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
def add_property_from_leaves(self, n):
    """
    Add a ``permutation_length`` vertex property and compute its values from leaf to root paths.

    Parameters
    ----------
    n : int
        The size parameter passed to `is_n_admissible_integers`.
        It determines the admissible integer sequences that are examined for each leaf‑to‑root path.

    Returns
    -------
    list[list[tuple]]
        A list where each element corresponds to a leaf vertex.  Each inner
        list contains tuples ``(vertex_id, order_index)`` representing the
        vertices on the path from that leaf to the root (ordered from root to
        leaf).  The returned structure can be used to inspect the paths that
        were processed.

    Notes
    -----
    * The method mutates the graph by adding a new vertex property; the
      property is always present after the call, regardless of the returned value.
    * The printed output is intended for debugging and can be redirected or
      silenced by adjusting the caller’s logging configuration.
    * ``order_index_to_vid`` maps each ``order_index`` encountered on a path
      to its vertex identifier, enabling the assignment of the permutation
      length to the correct vertex.
    """
    from phyllotaxis_analysis.theoretical_sequences import is_n_admissible_integers

    self.add_property("permutation_length")  # Initialize the new vertex property.

    props = self.properties()
    for vid in self.vertices():
        props["permutation_length"][vid] = 0  # Default length is 0 for all vertices.

    vertexes_from_leaves_to_root = []
    for lid in self.leaves():
        to_root_vids = []
        vid = lid
        while not (vid == self.root):
            # Record vertex id and its order index while climbing toward the root.
            to_root_vids.append((vid, self.get_vertex_property(vid)["order_index"]))
            vid = self.parent(vid)
        to_root_vids.reverse()  # Order from root to leaf.
        logger.debug("leaf", lid, to_root_vids)
        vertexes_from_leaves_to_root.append(to_root_vids)

    for leaf_to_root in vertexes_from_leaves_to_root:
        logger.debug("leaf_to_root", leaf_to_root)
        order_indexes_values = [0]  # Initialize with root index.
        # Append order indexes from the current leaf-to-root path.
        order_indexes_values.extend([item[1] for item in leaf_to_root])
        # Map each order index to its corresponding vertex id.
        order_index_to_vid = dict((item[1], item[0]) for item in leaf_to_root)

        logger.debug("order_index_to_vid", order_index_to_vid)
        # Determine admissible integer sequences for the path.
        order_indexes_values = is_n_admissible_integers(order_indexes_values, n)
        logger.debug(order_indexes_values)
        for p in order_indexes_values[1]:
            for o_idx in p:
                # Assign permutation length (size of the admissible sequence) to each vertex.
                logger.debug("order_index :", o_idx, "order_index_to_vid", order_index_to_vid[o_idx], p, len(p))
                props["permutation_length"][order_index_to_vid[o_idx]] = len(p)

    logger.debug(props["permutation_length"])
    return vertexes_from_leaves_to_root

add_vertex Link

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 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
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 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

all_paths_all Link

all_paths_all()

Returns a generator yielding path data from leaves to the root for all leaves in the tree.

For each leaf, the generator yields a list containing: - values along the path - probabilities at each vertex - question marks (value and level) if present - total logarithmic probability of the path

Yields:

Type Description
list

The list containing four elements: - list: Values along the path from leaf to root. - list: Probabilities at each vertex in the path. - list: Question marks as [value, level] pairs (empty if none). - float: Total logarithmic probability of the path.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
def all_paths_all(self):
    """
    Returns a generator yielding path data from leaves to the root for all leaves in the tree.

    For each leaf, the generator yields a list containing:
    - values along the path
    - probabilities at each vertex
    - question marks (value and level) if present
    - total logarithmic probability of the path

    Yields
    ------
    list
        The list containing four elements:
        - list: Values along the path from leaf to root.
        - list: Probabilities at each vertex in the path.
        - list: Question marks as [value, level] pairs (empty if none).
        - float: Total logarithmic probability of the path.
    """
    # Iterate over every vertex identifier in the tree
    for vid in self.vertices():
        # Consider only leaf vertices as starting points for paths
        if self.is_leaf(vid):
            # Containers for collected path data
            value_list = list()  # values along the path
            prob_list = list()  # probabilities at each vertex
            question_list = list()  # (value, level) pairs for question marks
            log_prob = 0.0  # cumulative log‑probability of the path
            # Walk upward from the leaf to the root
            while not (vid == self.root):
                # Append the current vertex's value
                value_list.append(self.get_vertex_property(vid)["value"])
                # Append the current vertex's probability
                prob_list.append(self.get_vertex_property(vid)["node_prb"])
                # Add the vertex's log‑probability to the total
                log_prob += self.get_vertex_property(vid)["node_log_prob"]
                # Record question‑mark information if present
                if self.get_vertex_property(vid)["question_mark"]:
                    question_list.append(
                        [self.get_vertex_property(vid)["value"], self.get_vertex_property(vid)["level"]])
                # Move to the parent vertex for the next iteration
                vid = self.parent(vid)
            # Reverse collected lists to order from root to leaf
            value_list.reverse()
            prob_list.reverse()
            question_list.reverse()
            # Yield the assembled path data for this leaf
            yield [value_list, prob_list, question_list, log_prob]

children Link

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 
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
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 Link

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 
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
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 Link

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 
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
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 Link

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 
280
281
282
283
284
285
286
287
288
289
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_max_level Link

get_max_level()

Get the maximum level of leaves in the tree.

Returns:

Type Description
int

The maximum level of leaves in the tree.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
195
196
197
198
199
200
201
202
203
204
def get_max_level(self):
    """
    Get the maximum level of leaves in the tree.

    Returns
    -------
    int
        The maximum level of leaves in the tree.
    """
    return self.max_level

get_vertex_property Link

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 
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
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 Link

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 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
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 Link

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 
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
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 Link

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 
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
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 Link

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 
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
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 Link

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 
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
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

leaves Link

leaves()

Return the list of leaves of the n-admissible tree.

Returns:

Type Description
list

The list of vertex IDs representing the leaves of the tree.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
147
148
149
150
151
152
153
154
155
156
def leaves(self):
    """
    Return the list of leaves of the n-admissible tree.

    Returns
    -------
    list
        The list of vertex IDs representing the leaves of the tree.
    """
    return [vid for vid in self.vertices() if self.is_leaf(vid)]

leaves_last Link

leaves_last(seq_len)

Return the leaves of the tree whose level is equal to a given value.

Parameters:

Name Type Description Default
seq_len int

The level at which to retrieve leaves.

 required

Returns:

Type Description
list

The list of leaves whose level is equal to seq_len.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def leaves_last(self, seq_len):
    """
    Return the leaves of the tree whose level is equal to a given value.

    Parameters
    ----------
    seq_len : int
        The level at which to retrieve leaves.

    Returns
    -------
    list
        The list of leaves whose level is equal to `seq_len`.
    """
    return [vid for vid in self.vertices() if
            (vid != self.root) and (self.get_vertex_property(vid)["level"] == seq_len)]

leaves_not_last Link

leaves_not_last(seq_len)

Return leaves of the tree whose level differs from a given value.

Given a sequence length, this function filters the tree's leaves and returns those whose level property does not match the specified sequence length.

Parameters:

Name Type Description Default
seq_len int

The sequence length used to filter leaves by their level property.

 required

Returns:

Type Description
list

The list of vertex IDs representing leaves whose level is not equal to seq_len.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def leaves_not_last(self, seq_len):
    """
    Return leaves of the tree whose level differs from a given value.

    Given a sequence length, this function filters the tree's leaves and returns
    those whose level property does not match the specified sequence length.

    Parameters
    ----------
    seq_len : int
        The sequence length used to filter leaves by their level property.

    Returns
    -------
    list
        The list of vertex IDs representing leaves whose level is not equal to `seq_len`.
    """
    return [vid for vid in self.vertices() if
            (self.is_leaf(vid) and (self.get_vertex_property(vid)["level"] != seq_len))]

nb_children Link

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 
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
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 Link

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 
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
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 Link

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 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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 Link

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 
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
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)

path_to_root Link

path_to_root(vid)

Return the list of values of vertices on the path from a given vertex to the root.

Parameters:

Name Type Description Default
vid int

The vertex id.

 required

Returns:

Type Description
list

The list of values of vertices on the path from the vertex to the root.
Source code in src/phyllotaxis_analysis/n_admissible_tree.py 
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def path_to_root(self, vid):
    """
    Return the list of values of vertices on the path from a given vertex to the root.

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

    Returns
    -------
    list
        The list of values of vertices on the path from the vertex to the root.
    """
    # Build list of vertex values from given node up to (but not including) root
    value_list = list()
    # Traverse upward until reaching the root vertex
    while not (vid == self.root):
        # Append current vertex's stored value
        value_list.append(self.get_vertex_property(vid)["value"])
        # Move to parent vertex for next iteration
        vid = self.parent(vid)
    # Reverse to obtain path order from root to the original vertex
    value_list.reverse()
    return value_list

properties Link

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 
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
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 Link

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 
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
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 Link

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 
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
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 Link

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 
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
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 Link

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 
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
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 Link

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 
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
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 Link

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 
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
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 Link

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 
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
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 Link

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 
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
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 Link

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 
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
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 Link

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 
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
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 Link

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 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
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 Link

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 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
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())