MTG  Mutltiscale Tree Graph¶
Overview¶

openalea.mtg.mtg.
MTG
(filename='', has_date=False)[source]¶ A Multiscale Tree Graph (MTG) class.
MTGs describe tree structures at different levels of details, named scales. For example, a botanist can described plants at different scales :
 at scale 0, the whole scene.
 at scale 1, the individual plants.
 at scale 2, the axes of each plants.
 at scale 3, the growth units of each axis, and so on.
Each scale can have a label, e.g. :
 scale 1 : P(lant)
 scale 2 : A(xis)
 sclae 3 : U(nit of growth)
Compared to a classical tree,
complex()
can be seen asparent()
andcomponents()
aschildren()
. An element atscale()
N belongs to acomplex()
atscale()
N1 and hascomponents()
at scale N+1: /P/A/U (decomposition is noted using “/”)
Each scale is itself described as a tree or a forest (i.e. set of trees), e.g.:
 /P1/P2/P3
 A1+A2<A3
 …
Iterating over vertices¶
MTG.root 
Return the tree root. 
MTG.vertices ([scale]) 
Return a list of the vertices contained in an MTG. 
MTG.nb_vertices ([scale]) 
Returns the number of vertices. 
MTG.parent (vtx_id) 
Return the parent of vtx_id. 
MTG.children (vtx_id) 
returns a vertex iterator 
MTG.nb_children (vtx_id) 
returns the number of children 
MTG.siblings (vtx_id) 
returns an iterator of vtx_id siblings. 
MTG.nb_siblings (vtx_id) 
returns the number of siblings 
MTG.roots ([scale]) 
Returns a list of the roots of the tree graphs at a given scale. 
MTG.complex (vtx_id) 
Returns the complex of vtx_id. 
MTG.components (vid) 
returns the components of a vertex 
MTG.nb_components (vid) 
returns the number of components 
MTG.complex_at_scale (vtx_id, scale) 
Returns the complex of vtx_id at scale scale. 
MTG.components_at_scale (vid, scale) 
returns a vertex iterator 
Adding and removing vertices¶
MTG.__init__ ([filename, has_date]) 
Create a new MTG object. 
MTG.add_child (parent[, child]) 
Add a child to a parent. 
MTG.insert_parent (vtx_id[, parent_id]) 
Insert parent_id between vtx_id and its actual parent. 
MTG.insert_sibling (vtx_id1[, vtx_id2]) 
Insert a sibling of vtk_id1. 
MTG.add_component (complex_id[, component_id]) 
Add a component at the end of the components 
MTG.add_child_and_complex (parent[, child, …]) 
Add a child at the end of children that belong to an other complex. 
MTG.add_child_tree (parent, tree) 
Add a tree after the children of the parent vertex. 
MTG.clear () 
Remove all vertices and edges from the MTG. 
Some usefull functions¶
simple_tree (tree, vtx_id[, nb_children, …]) 
Generate and add a regular tree to an existing one at a given vertex. 
random_tree (mtg, root[, nb_children, …]) 
Generate and add a random tree to an existing one. 
random_mtg (tree, nb_scales) 
Convert a tree into an MTG of nb_scales. 
colored_tree (tree, colors) 
Compute a mtg from a tree and the list of vertices to be quotiented. 
display_tree (tree, vid[, tab, labels, edge_type]) 
Display a tree structure. 
display_mtg (mtg, vid) 
Display an MTG 
All¶

class
openalea.mtg.mtg.
MTG
(filename='', has_date=False)[source] Bases:
openalea.mtg.tree.PropertyTree
A Multiscale Tree Graph (MTG) class.
MTGs describe tree structures at different levels of details, named scales. For example, a botanist can described plants at different scales :
 at scale 0, the whole scene.
 at scale 1, the individual plants.
 at scale 2, the axes of each plants.
 at scale 3, the growth units of each axis, and so on.
Each scale can have a label, e.g. :
 scale 1 : P(lant)
 scale 2 : A(xis)
 sclae 3 : U(nit of growth)
Compared to a classical tree,
complex()
can be seen asparent()
andcomponents()
aschildren()
. An element atscale()
N belongs to acomplex()
atscale()
N1 and hascomponents()
at scale N+1: /P/A/U (decomposition is noted using “/”)
Each scale is itself described as a tree or a forest (i.e. set of trees), e.g.:
 /P1/P2/P3
 A1+A2<A3
 …

AlgHeight
(v1, v2)[source]¶ Algebraic value defining the number of components between two components.
This function is similar to function Height(v1, v2) : it returns the number of components between two components, at the same scale, but takes into account the order of vertices v1 and v2.
The result is positive if v1 is an ancestor of v2, and negative if v2 is an ancestor of v1.
Usage: AlgHeight(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG.
 v2 (int) : vertex of the active MTG.
Returns: int
If v1 is not an ancestor of v2 (or vise versa), or if v1 and v2 are not defined at the same scale, an error value None is returned.
See also
MTG()
,Rank()
,Order()
,Height()
,EdgeType()
,AlgOrder()
,AlgRank()
.

AlgOrder
(v1, v2)[source]¶ Algebraic value defining the relative order of one vertex with respect to another one.
This function is similar to function Order(v1, v2) : it returns the number of +type edges between two components, at the same scale, but takes into account the order of vertices v1 and v2.
The result is positive if v1 is an ancestor of v2, and negative if v2 is an ancestor of v1.
Usage: AlgOrder(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG.
 v2 (int) : vertex of the active MTG.
Returns: int
If v1 is not an ancestor of v2 (or vise versa), or if v1 and v2 are not defined at the same scale, an error value None is returned.
See also
MTG()
,Rank()
,Order()
,Height()
,EdgeType()
,AlgHeight()
,AlgRank()
.

AlgRank
(v1, v2)[source]¶ Algebraic value defining the relative rank of one vertex with respect to another one.
This function is similar to function Rank(v1, v2) : it returns the number of <type edges between two components, at the same scale, but takes into account the order of vertices v1 and v2.
The result is positive if v1 is an ancestor of v2, and negative if v2 is an ancestor of v1.
Usage: AlgRank(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG.
 v2 (int) : vertex of the active MTG.
Returns: int
If v1 is not an ancestor of v2 (or vise versa), or if v1 and v2 are not defined at the same scale, an error value None is returned.
See also
MTG()
,Rank()
,Order()
,Height()
,EdgeType()
,AlgHeight()
,AlgOrder()
.

Ancestors
(v, EdgeType='*', RestrictedTo='NoRestriction', ContainedIn=None)[source]¶ Array of all vertices which are ancestors of a given vertex
This function returns the array of vertices which are located before the vertex passed as an argument. These vertices are defined at the same scale as v. The array starts by v, then contains the vertices on the path from v back to the root (in this order) and finishes by the tree root.
Note
The anscestor array always contains at least the argument vertex v.
Usage: g.Ancestors(v)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  RestrictedTo (str): cf. Father
 ContainedIn (int): cf. Father
 EdgeType (str): cf. Father
Returns: list of vertices’s id (int)
Examples: >>> v # prints vertex v 78 >>> g.Ancestors(v) # set of ancestors of v at the same scale [78,45,32,10,4] >>> list(reversed(g.Ancestors(v))) # To get the vertices in the order from the root to the vertex v [4,10,32,45,78]
See also

Axis
(v, Scale=1)[source]¶ Array of vertices constituting a botanical axis
An axis is a maximal sequence of vertices connected by ‘<’type edges. Axis return the array of vertices representing the botanical axis which the argument v belongs to. The optional argument enables the user to choose the scale at which the axis decomposition is required.
Usage: Axis(v) Axis(v, Scale=s)
Parameters:  v (int) : Vertex of the active MTG
Optional Parameters:  Scale (str): scale at which the axis components are required.
Returns: list of vertices ids
See also

Class
(vid)¶ Class of a vertex.
The Class of a vertex are the first characters of the label. The label of a vertex is the string defined by the concatenation of the class and its index.
The label thus provides general information about a vertex and enable to encode the plant components.
The class_name may be not defined. Then, an empty string is returned.
Usage: >>> g.class_name(1)
Parameters:  vid (int)
Returns: The class name of the vertex (str).

ClassScale
(c)[source]¶ Scale at which appears a given class of vertex
Every vertex is associated with a unique class. Vertices from a given class only appear at a given scale which can be retrieved using this function.
Usage: ClassScale(c)
Parameters:  c (str) : symbol of the considered class
Returns: int

Complex
(v, Scale=1)[source]¶ Complex of a vertex.
Returns the complex of v. The complex of a vertex v has a scale lower than v : Scale(v)  1. In a MTG, every vertex except for the MTG root (cf. MTGRoot), has a uniq complex. None is returned if the argument is the MTG Root or if the vertex is undefined.
Usage: g.Complex(v) g.Complex(v, Scale=2)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  Scale (int) : scale of the complex
Returns: Returns vertex’s id (int)
Details: When a scale different form Scale(v)1 is specified using the optional parameter Scale, this scale must be lower than that of the vertex argument.
Todo
Complex(v, Scale=10) returns v why ? is this expected
See also

ComponentRoots
(v, Scale=1)[source]¶ Set of roots of the tree graphs that compose a vertex
In a MTG, a vertex may have be decomposed into components. Some of these components are connected to each other, while other are not. In the most general case, the components of a vertex are organized into several treegraphs. This is for example the case of a MTG containing the description of several plants: the MTG root vertex can be decomposed into tree graphs (not connected) that represent the different plants. This function returns the set of roots of these tree graphs at scale Scale(v)+1. The order of these roots is not significant.
When a scale different from Scale(v)+1 is specified using the optional argument
Scale()
, this scale must be greater than that of the vertex argument.Usage: g.ComponentRoots(v) g.ComponentRoots(v, Scale=s)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  Scale (str): scale of the component roots.
Returns: list of vertices’s id (int)
Examples: >>> v=g.MTGRoot() # global MTG root 0 >>> g.ComponentRoots(v) # set of first vertices at scale 1 [1,34,76,100,199,255] >>> g.ComponentRoots(v, Scale=2) # set of first vertices at scale 2 [2,35,77,101,200,256]
See also

Components
(v, Scale=1)[source]¶ Set of components of a vertex.
The set of components of a vertex is returned as a list of vertices. If s defines the scale of v, components are defined at scale s + 1. The array is empty if the vertex has no components. The order of the components in the array is not significant.
When a scale is specified using optional argument :arg:Scale, it must be necessarily greater than the scale of the argument.
Usage: Components(v) Components(v, Scale=2)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  Scale (int) : scale of the components.
Returns: list of int

Defined
(vid)[source]¶ Test whether a given vertex belongs to the active MTG.
Usage: Defined(v)
Parameters:  v (int) : vertex of the active MTG
Returns: True or False
See also

Descendants
(v, EdgeType='*', RestrictedTo='NoRestriction', ContainedIn=None)[source]¶ Set of vertices in the branching system borne by a vertex.
This function returns the set of descendants of its argument as an array of vertices. The array thus consists of all the vertices, at the same scale as v, that belong to the branching system starting at v. The order of the vertices in the array is not significant.
Note
The argument always belongs to the set of its descendants.
Usage: g.Descendants(v)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  RestrictedTo (str): cf. Father
 ContainedIn (int): cf. Father
 EdgeType (str): cf. Father
Returns: list of int.
Examples: >>> v 78 >>> g.Sons(v) # set of sons of v [78,99,101] >>> g.Descendants(v) # set of descendants of v [78,99,101,121,133,135,156,171,190]
See also

EdgeType
(v1, v2)[source]¶ Type of connection between two vertices.
Returns the symbol of the type of connection between two vertices (either < or +). If the vertices are not connected, None is returned.
Usage: EdgeType(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG
 v2 (int) : vertex of the active MTG
Returns: ‘<’ (successor), ‘+’ (branching) or None

Extremities
(v, RestrictedTo='NoRestriction', ContainedIn=None)[source]¶ Set of vertices that are the extremities of the branching system born by a given vertex.
This function returns the extremities of the branching system defined by the argument as a list of vertices. These vertices have the same scale as v and their order in the list is not signifiant. The result is always a non empty array.
Usage: Extremities(v)
Properties:  v (int) : vertex of the active MTG
Optional Parameters: Returns: list of vertices’s id (int)
Examples: >>> g.Descendants(v) [3, 45, 47, 78, 102] >>> g.Extremities(v) [47, 102]
See also
MTG()
,Descendants()
,Root()
,MTGRoot()
.

Father
(v, EdgeType='*', RestrictedTo='NoRestriction', ContainedIn=None, Scale=1)[source]¶ Topological father of a given vertex.
Returns the topological father of a given vertex. And None if the father does not exist. If the argument is not a valid vertex, None is returned.
Usage: g.Father(v) g.Father(v, EdgeType='<') g.Father(v, RestrictedTo='SameComplex') g.Father(v, ContainedIn=complex_id) g.Father(v, Scale=s)
Parameters: v (int) : vertex of the active MTG
Optional Parameters: If no optional argument is specified, the function returns the topological father of the argument (vertex that bears or precedes to the vertex passed as an argument).
It may be usefull in some cases to consider that the function only applies to a subpart of the MTG (e.g. an axis).
The following options enables us to specify such restrictions:
EdgeType (str) : filter on the type of edge that connect the vertex to its father.
Values can be ‘<’, ‘+’, and ‘*’. Values ‘*’ means both ‘<’ and ‘+’. Only the vertex connected with the specified type of edge will be considered.
RestrictedTo (str) : filter defining a subpart of the MTG where the father must be considered. If the father is actually outside this subpart, the result is None. Possible subparts are defined using keywords in [‘SameComplex’, ‘SameAxis’, ‘NoRestriction’].
For instance, if RestrictedTo is set to ‘SameComplex’,
Father(v)()
returns a defined vertex only if the father f of v existsin the MTG and if v and f have the same complex.ContainedIn (int) : filter defining a subpart of the MTG where the father must be considered. If the father is actually outside this subpart, the result is None.
In this case, the subpart of the MTG is made of the vertices that composed composite_id (at any scale).
Scale (int) : the scale of the considered father. Returns the vertex from scale s which either bears and precedes the argument.
The scale s can be lower than the argument’s (corresponding to a question such as ‘which axis bears the internode?’) or greater (e.g. ‘which internodes bears this annual shoot?’).
Returns: the vertex id of the Father (int)
See also
MTG()
,Defined()
,Sons()
,EdgeType()
,Complex()
,Components()
.

Height
(v1, v2=None)[source]¶ Number of components existing between two components in a tree graph.
The height of a vertex (v2) with respect to another vertex (v1) is the number of edges (of either type ‘+’ or ‘<’) that must be crossed when going from v1 to v2 in the graph.
This is a nonnegative integer. When the function has only one argument v1, the height of v1 correspond to the height of v1`with respect to the root of the branching system containing `v1.
Usage: Height(v1) Height(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG
 v2 (int) : vertex of the active MTG
Returns: int
Note
When the function takes two arguments, the order of the arguments is not important provided that one is an ancestor of the other. When the order is relevant, use function AlgHeight.
See also
MTG()
,Order()
,Rank()
,EdgeType()
,AlgHeight()
,AlgHeight()
,AlgOrder()
.

Index
(vid)¶ Index of a vertex
The Index of a vertex is a feature always defined and independent of time (like the index). It is represented by a non negative integer. The label of a vertex is the string defined by the concatenation of its class and its index. The label thus provides general information about a vertex and enables us to encode the plant components.

Label
(vid)¶ Label of a vertex.
Usage: >>> g.label(v)
Parameters:  vid (int) : vertex of the MTG
Returns: The class and Index of the vertex (str).
See also

Path
(v1, v2)[source]¶ List of vertices defining the path between two vertices
This function returns the list of vertices defining the path between two vertices that are in an ancestor relationship. The vertex v1 must be an ancestor of vertex v2. Otherwise, if both vertices are valid, then the empty array is returned and if at least one vertex is undefined, None is returned.
Usage: g.Path(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG
 v2 (int) : vertex of the active MTG
Returns: list of vertices’s id (int)
Examples: >>> v # print the value of v 78 >>> g.Ancestors(v) [78,45,32,10,4] >>> g.Path(10,v) [10,32,45,78] >>> g.Path(9,v) # 9 is not an ancestor of 78 []
Note
v1 can be equal to v2.
See also

Predecessor
(v, **kwds)[source]¶ Father of a vertex connected to it by a ‘<’ edge
This function is equivalent to Father(v, EdgeType> ‘<’). It thus returns the father (at the same scale) of the argument if it is located in the same botanical. If it does not exist, None is returned.
Usage: Predecessor(v)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  RestrictedTo (str): cf. Father
 ContainedIn (int): cf. Father
Returns: return the vertex id (int)
Examples: >>> Predecessor(v) 7 >>> Father(v, EdgeType='+') >>> Father(v, EdgeType> '<') 7
See also

Rank
(v1, v2=None)[source]¶ Rank of one vertex with respect to another one.
This function returns the number of consecutive ‘<’type edges between two components, at the same scale, and does not take into account the order of vertices v1 and v2. The result is a non negative integer.
Usage: Rank(v1) Rank(v1, v2)
Parameters:  v1 (int) : vertex of the active MTG
 v2 (int) : vertex of the active MTG
Returns: int
If v1 is not an ancestor of v2 (or vise versa) within the same botanical axis, or if v1 and v2 are not defined at the same scale, an error value Undef id returned.
See also
MTG()
,Order()
,Height()
,EdgeType()
,AlgRank()
,AlgHeight()
,AlgOrder()
.

Root
(v, RestrictedTo='*', ContainedIn=None)[source]¶ Root of the branching system containing a vertex
This function is equivalent to Ancestors(v, EdgeType=’<’)[1]. It thus returns the root of the branching system containing the argument. This function never returns None.
Usage: g.Root(v)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters:  RestrictedTo (str): cf. Father
 ContainedIn (int): cf. Father
Returns: return vertex’s id (int)
Examples: >>> g.Ancestors(v) # set of ancestors of v [102,78,35,33,24,12] >>> g.Root(v) # root of the branching system containing v 12
See also

Scale
(vid)¶ Returns the scale of a vertex.
All vertices should belong to a given scale.
Usage: g.scale(vid)
Parameters:  vid (int)  vertex identifier.
Returns: The scale of the vertex. It is a positive int in [0,g.max_scale()].

Sons
(v, RestrictedTo='NoRestriction', EdgeType='*', Scale=1, ContainedIn=None)[source]¶ Set of vertices born or preceded by a vertex
The set of sons of a given vertex is returned as an array of vertices. The order of the vertices in the array is not significant. The array can be empty if there are no son vertices.
Usage: g.Sons(v) g.Sons(v, EdgeType= '+') g.Sons(v, Scale= 3)
Parameters:  v (int) : vertex of the active MTG
Optional Parameters: Returns: list(vid)
Details: When the option EdgeType is applied, the function returns the set of sons that are connected to the argument with the specified type of relation.
Note
Sons(v, EdgeType= ‘<’) is not equivalent to Successor(v). The first function returns an array of vertices while the second function returns a vertex.
The returned vertices have the same scale as the argument. However, coarser or finer vertices can be obtained by specifying the optional argument Scale at which the sons are considered.
Examples: >>> g.Sons(v) [3,45,47,78,102] >>> g.Sons(v, EdgeType= '+') # set of vertices borne by v [3,45,47,102] >>> g.Sons(v, EdgeType= '<') # set of successors of v on the same axis [78]
See also

Successor
(v, RestrictedTo='NoRestriction', ContainedIn=None)[source]¶ Vertex that is connected to a given vertex by a ‘<’ edge type (i.e. in the same botanical axis).
This function is equivalent to Sons(v, EdgeType=’<’)[0]. It returns the vertex that is connected to a given vertex by a ‘<’ edge type (i.e. in the same botanical axis). If many such vertices exist, an arbitrary one is returned by the function. If no such vertex exists, None is returned.
Usage: g.Successor(v)
Parameters:  v1 (int) : vertex of the active MTG
Optional Parameters:  RestrictedTo (str): cf. Father
 ContainedIn (int): cf. Father
Returns: Returns vertex’s id (int)
Examples: >>> g.Sons(v) [3, 45, 47, 78, 102] >>> g.Sons(v, EdgeType='+') # set of vertices borne by v [3, 45, 47, 102] >>> g.Sons(v, EdgeType> '<') # set of successors of v [78] >>> g.Successor(v) 78
See also

Trunk
(v, Scale=1)[source]¶ List of vertices constituting the bearing botanical axis of a branching system.
Trunk returns the list of vertices representing the botanical axis defined as the bearing axis of the whole branching system defined by v. The optional argument enables the user to choose the scale at which the trunk should be detailed.
Usage: Trunk(v) Trunk(v, Scale= s)
Parameters:  v (int) : Vertex of the active MTG.
Optional Parameters:  Scale (str): scale at which the axis components are required.
Returns: list of vertices ids
Todo
check the usage of the optional argument Scale
See also
MTG()
,Path()
,Ancestors()
,Axis()
.

VtxList
(Scale=1)[source]¶ Array of vertices contained in a MTG
The set of all vertices in the
MTG()
is returned as an array. Vertices from all scales are returned if no option is used. The order of the elements in this array is not significant.Usage: >>> VtxList() >>> VtxList(Scale=2)
Optional Parameters:  Scale (int): used to select components at a particular scale.
Returns:  list of vid
Background: MTGs()

add_child
(parent, child=None, **properties)[source]¶ Add a child to a parent. Child is appended to the parent’s child list.
Parameters:  parent (int)  The parent identifier.
 child (int or None)  The child identifier. If None,
 an ID is generated.
Returns: Identifier of the inserted vertex (child)
Returns Type: int

add_child_and_complex
(parent, child=None, complex=None, **properties)[source]¶ Add a child at the end of children that belong to an other complex.
Parameters:  parent: The parent identifier.
 child: Set the child identifier to this value if defined.
 complex: Set the complex identifier to this value if defined.
Returns: (vid, vid): child and complex ids.

add_child_tree
(parent, tree)¶ Add a tree after the children of the parent vertex. Complexity have to be O(1) if tree == sub_tree()
Parameters:  parent – vertex identifier
 tree – a rooted tree

add_component
(complex_id, component_id=None, **properties)[source]¶ Add a component at the end of the components
Parameters:  complex_id: The complex identifier.
 component_id: Set the component identifier to this value if defined.
Returns: The id of the new component or the component_id if given.

add_element
(parent_id, edge_type='/', scale_id=None)[source]¶ Add an element to the graph, if vid is not provided create a new vid ??? .. warning: Not Implemented.
Parameters:  parent_id (int)  The id of the parent vertex
 edge_type (str)  The type of relation:
 “/” : component (default)
 “+” : branch
 “<” : successor.
 scale_id (int)  The id of the scale in which to
 add the vertex.
Returns: The vid of the created vertex

add_property
(property_name)¶ Add a new map between vid and a data Do not fill this property for any vertex

backward_rewriting_traversal
()¶

children
(vtx_id)¶ returns a vertex iterator
Parameters: vtx_id – The vertex identifier. Returns: iter of vertex identifier

children_iter
(vtx_id)¶ returns a vertex iterator
Parameters: vtx_id – The vertex identifier. Returns: iter of vertex identifier

class_name
(vid)[source]¶ Class of a vertex.
The Class of a vertex are the first characters of the label. The label of a vertex is the string defined by the concatenation of the class and its index.
The label thus provides general information about a vertex and enable to encode the plant components.
The class_name may be not defined. Then, an empty string is returned.
Usage: >>> g.class_name(1)
Parameters:  vid (int)
Returns: The class name of the vertex (str).

clear
()[source]¶ Remove all vertices and edges from the MTG.
This also removes all vertex properties. Don’t change references to object such as internal dictionaries.
Example: >>> g.clear() >>> g.nb_vertices() 0 >>> len(g) 0

clear_properties
(exclude=[])[source]¶ Remove all the properties of the MTG.
Example: >>> g.clear_properties()

complex
(vtx_id)[source]¶ Returns the complex of vtx_id.
Parameters:  vtx_id (int)  The vertex identifier.
Returns: complex identifier or None if vtx_id has no parent.
Return Type: int

complex_at_scale
(vtx_id, scale)[source]¶ Returns the complex of vtx_id at scale scale.
Parameters:  vtx_id: The vertex identifier.
 scale: The scale identifier.
Returns: vertex identifier
Returns Type: int

component_roots_at_scale
(vtx_id, scale)[source]¶ Return the list of roots of the tree graphs that compose a vertex.

component_roots_at_scale_iter
(vtx_id, scale)[source]¶ Return the set of roots of the tree graphs that compose a vertex.

component_roots_iter
(vtx_id)[source]¶ Return an iterator of the roots of the tree graphs that compose a vertex.

components
(vid)[source]¶ returns the components of a vertex
Parameters: vid – The vertex identifier. Returns: list of vertex identifier

components_at_scale
(vid, scale)[source]¶ returns a vertex iterator
Parameters:  vid: The vertex identifier.
Returns: iter of vertex identifier

components_at_scale_iter
(vid, scale)[source]¶ returns a vertex iterator
Parameters:  vid: The vertex identifier.
Returns: iter of vertex identifier

components_iter
(vid)[source]¶ returns a vertex iterator
Parameters: vid – The vertex identifier. Returns: iter of vertex identifier

display
(max_scale=0, display_id=True, display_scale=False, nb_tab=12, **kwds)[source]¶ Print an MTG on the console.
Optional Parameters:  max_scale: do not print vertices of scale greater than max_scale
 display_id: display the vid of the vertices
 display_scale: display the scale of the vertices
 nb_tab: display the MTG using nb_tab columns

edge_type
(vid)[source]¶ Type of the edge between a vertex and its parent.
The different values are ‘<’ for successor, and ‘+’ for ramification.

edges
(scale=1)[source]¶ Parameters:  scale (int)  Scale at which to iterate.
Returns: Iterator on the edges of the MTG at a given scale or on all edges if scale < 0.
Returns Type: iter

forward_rewriting_traversal
()¶

get_root
()¶ Return the tree root.
Returns: vertex identifier

get_vertex_property
(vid)¶ Returns all the properties defined on a vertex.

graph_properties
()¶ return a dict containing the graph properties/
Return type: dict of {property_name:data}

has_vertex
(vid)[source]¶ Tests whether a vertex belongs to the graph.
Parameters:  vid (int)  vertex id to test
Returns Type: bool

index
(vid)[source]¶ Index of a vertex
The Index of a vertex is a feature always defined and independent of time (like the index). It is represented by a non negative integer. The label of a vertex is the string defined by the concatenation of its class and its index. The label thus provides general information about a vertex and enables us to encode the plant components.

insert_parent
(vtx_id, parent_id=None, **properties)[source]¶ Insert parent_id between vtx_id and its actual parent. Inherit of the complex of the parent of vtx_id.
Parameters:  vtx_id (int): a vertex identifier
 parent_id (int): a vertex identifier
Returns: Identifier of the inserted vertex (parent_id).
Returns Type: int

insert_scale
(inf_scale=None, partition=None, default_label=None, preserve_order=True)[source]¶ Add a scale to MTG
Parameters:  inf_scale (int)  New scale is inserted between inf_scale and inf_scale1
 partition (lambda v: bool)  Function defining new scale by quotienting vertices at inf_scale
 default_label (str)  default label of inserted vertices
 preserve_order (bool)  True iif children at new scale are ordered consistently
 with children at inf_scale
Returns: MTG with inserted scale
Remark:  New scale is inserted in self as well.
 function partition should return True at roots of subtrees where partition changes
and False elsewhere.

insert_sibling
(vtx_id1, vtx_id2=None, **properties)[source]¶ Insert a sibling of vtk_id1. The vertex in inserted before vtx_id1.
Parameters:  vtx_id1 (int) : a vertex identifier
 vtx_id2 (int) : the vertex to insert
Returns: Identifier of the inserted vertex (vtx_id2)
Returns Type: int

insert_sibling_tree
(vid, tree)¶ Insert a tree before the vid. vid and the root of the tree are siblings. Complexity have to be O(1) if tree comes from the actual tree ( tree= self.sub_tree() )
Parameters:  vid – vertex identifier
 tree – a rooted tree

is_leaf
(vtx_id)¶ Test if vtx_id is a leaf.
Returns: bool

is_valid
()[source]¶ Tests the validity of the graph. Currently always returns True.
Returns Type: bool Todo: Implement this function.

iter_edges
(scale=1)[source]¶ Parameters:  scale (int)  Scale at which to iterate.
Returns: Iterator on the edges of the MTG at a given scale or on all edges if scale < 0.
Returns Type: iter

label
(vid)[source]¶ Label of a vertex.
Usage: >>> g.label(v)
Parameters:  vid (int) : vertex of the MTG
Returns: The class and Index of the vertex (str).
See also

max_scale
()[source]¶ Return the max scale identifier.
By convention, the mtg contains scales in \([0,max\_scale]\).
Usage: >>> print g.max_scale()
Returns: S, the maximum scale identifier.
Note
The complexity is \(O(n)\).

nb_children
(vtx_id)¶ returns the number of children
Parameters:  vtx_id: The vertex identifier.
Returns: int

nb_components
(vid)[source]¶ returns the number of components
Parameters:  vid: The vertex identifier.
Returns: int

nb_scales
()[source]¶ Returns: The number of scales defined in the mtg.. Returns Type: int Note
The complexity is \(O(n)\).

nb_siblings
(vtx_id)¶ returns the number of siblings
Returns: int

nb_vertices
(scale=1)[source]¶ Returns the number of vertices.
Usage: >>> g.nb_vertices() 100 >>> g.nb_vertices(scale=3) 68
Parameters:  scale (int)  Id of scale for which to count vertices.
Returns: Number of vertices at scale or total number of vertices if scale < 0.

node
(vid, klass=None)[source]¶ Return a node associated to the vertex vid.
It allows to access to the properties with an object oriented interface.
Example: node = g.node(1) print node.edge_type print node.label node.label = 'B' print g.label(1) print node.parent print list(node.children)

order
(v1)[source]¶ Order of a vertex in a graph.
The order of a vertex in a graph is the number of ‘+’ edges crossed when going from v1`to `v2.
If v2 is None, the order of v1 correspond to the order of v1 with respect to the root.

parent
(vtx_id)¶ Return the parent of vtx_id.
Parameters:  vtx_id: The vertex identifier.
Returns: vertex identifier

plot_property
(prop, **kwds)[source]¶ Plot properties of MTG using matplotlib
Example: >>> g.plot_property('length')

properties
()¶ Returns all the property maps contain in the graph.

property
(name)¶ Returns the property map between the vid and the data. :returns: dict of {vid:data}

property_names
()¶ names of all property maps. Properties are defined only on vertices, even edge properties. return iter of names

property_names_iter
()¶ iter on names of all property maps. Properties are defined only on vertices, even edge properties. return iter of names

reindex
(mapping=None, copy=False)[source]¶ Assign a new identifier to each vertex.
This method assigns a new identifier to each vertex of the MTG. The mapping can be user defined or is implicit (mapping). This method modify the MTG in place or return a new MTG (copy).
Usage: >>> g.reindex() >>> g1 = g.reindex(copy=True) >>> mymap = dict(zip(list(traversal.iter_mtg2(g,g.root)), range(len(g)))) >>> g2 = g.reindex(mapping=mymap, copy=True)
Optional Parameters:  mapping (dict): define a mapping between old and new vertex identifiers.
 copy (bool) : modify the object in place or return a new MTG.
Returns:  a MTG
Background: MTGs()
See also

remove_property
(property_name)¶ Remove the property map called property_name from the graph.

remove_scale
(scale)[source]¶ Remove all the vertices at a given scale.
The upper and lower scale are then connected.
 scale : the scale that have to be removed
Returns:   g (the input MTG modified in place.)
  results (a list of dict) – all the vertices that have been removed

remove_tree
(vtx_id)¶ Remove the sub tree rooted on vtx_id.
Returns: bool

remove_vertex
(vid, reparent_child=False)[source]¶ Remove a specified vertex of the graph and remove all the edges attached to it.
Parameters:  vid (int) : the id of the vertex to remove
 reparent_child (bool) : reparent the children of vid to its parent.
Returns: None

replace_parent
(vtx_id, new_parent_id, **properties)[source]¶ Change the parent of vtx_id to new_parent_id. The new parent of vtx_id is new_parent_id. vtx_id and new_parent_id must have the same scale.
This function do not change the edge_type between vtx_id and its parent.
Inherit of the complex of the parent of vtx_id.
Parameters:  vtx_id (int): a vertex identifier
 new_parent_id (int): a vertex identifier
Returns: None

roots
(scale=0)[source]¶ Returns a list of the roots of the tree graphs at a given scale.
In an MTG, the MTG root vertex, namely the vertex g.root, can be decomposed into several, nonconnected, tree graphs at a given scale. This is for example the case of an MTG containing the description of several plants.
Usage: roots = g.roots(scale=g.max_scale() Returns: list on vertex identifiers of root vertices at a given scale. Returns Type: list of vid

roots_iter
(scale=0)[source]¶ Returns an iterator of the roots of the tree graphs at a given scale.
In an MTG, the MTG root vertex, namely the vertex g.root, can be decomposed into several, nonconnected, tree graphs at a given scale. This is for example the case of an MTG containing the description of several plants.
Usage: roots = list(g.roots(scale=g.max_scale()) Returns: iterator on vertex identifiers of root vertices at a given scale. Returns Type: iter

scale
(vid)[source]¶ Returns the scale of a vertex.
All vertices should belong to a given scale.
Usage: g.scale(vid)
Parameters:  vid (int)  vertex identifier.
Returns: The scale of the vertex. It is a positive int in [0,g.max_scale()].

scales
()[source]¶ Return the different scales of the mtg.
Returns: Iterator on scale identifiers (ints). Note
The complexity is \(O(n)\).

scales_iter
()[source]¶ Return the different scales of the mtg.
Returns: Iterator on scale identifiers (ints). Note
The complexity is \(O(n)\).

set_root
(vtx_id)¶ Set the tree root.
Parameters: vtx_id – The vertex identifier.

siblings
(vtx_id)¶ returns an iterator of vtx_id siblings. vtx_id is not include in siblings.
Parameters:  vtx_id: The vertex identifier.
Returns: iter of vertex identifier

siblings_iter
(vtx_id)¶ returns an iterator of vtx_id siblings. vtx_id is not include in siblings.
Parameters:  vtx_id: The vertex identifier.
Returns: iter of vertex identifier

sub_mtg
(vtx_id, copy=True)[source]¶ Return the submtg rooted on vtx_id.
The induced sub mtg of the mtg are all the vertices which have vtx_id has a complex plus vtx_id.
Parameters:  vtx_id: A vertex of the original tree.
 copy: 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.
Returns: A sub mtg of the mtg. If copy=True, a new MTG is returned. Else the sub mtg is created inplace by modifying the original tree.

sub_tree
(vtx_id, copy=True)¶ Return the subtree rooted on vtx_id.
The induced subtree of the tree has the vertices in the ancestors of vtx_id.
Parameters:  vtx_id: A vertex of the original tree.
 copy: 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.
Returns: 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.

vertices
(scale=1)[source]¶ Return a list of the vertices contained in an MTG.
The set of all vertices in the MTG is returned. Vertices from all scales are returned if no scale is given. Otherwise, it returns only the vertices of the given scale. The order of the elements in this array is not significant.
Usage: g = MTG() len(g) == len(list(g.vertices())) for vid in g.vertices(scale=2): print g.class_name(vid)
Optional Parameters:  scale (int): used to select vertices at a given scale.
Returns: Iterator on vertices at “scale” or on all vertices if scale < 0.
Returns Type: list of vid
Background: See also

vertices_iter
(scale=1)[source]¶ Return an iterator of the vertices contained in an MTG.
The set of all vertices in the MTG is returned. Vertices from all scales are returned if no scale is given. Otherwise, it returns only the vertices of the given scale. The order of the elements in this array is not significant.
Usage: g = MTG() len(g) == len(list(g.vertices())) for vid in g.vertices(scale=2): print g.class_name(vid)
Optional Parameters:  scale (int): used to select vertices at a given scale.
Returns: Iterator on vertices at “scale” or on all vertices if scale < 0.
Returns Type: iter of vid
Background: See also

root
¶ Return the tree root.
Returns: vertex identifier

openalea.mtg.mtg.
simple_tree
(tree, vtx_id, nb_children=3, nb_vertices=20)[source]¶ Generate and add a regular tree to an existing one at a given vertex.
Add a regular tree at a given vertex id position vtx_id. The length of the sub_tree is nb_vertices. Each new vertex has at most nb_children children.
Parameters:  tree: the tree thaat will be modified
 vtx_id (id): vertex on which the sub tree will be added.
 nb_children (int) : number of children that are added to each vertex
 nb_vertices (int) : number of vertices to add
Returns: The modified tree
Examples: g = MTG() vid = g.add_component(g.root) simple_tree(g, vid, nb_children=2, nb_vertices=20) print len(g) # 22
See also

openalea.mtg.mtg.
random_tree
(mtg, root, nb_children=3, nb_vertices=20)[source]¶ Generate and add a random tree to an existing one.
Add a random sub tree at a given vertex id position root. The length of the sub_tree is nb_vertices. The number of children for each vertex is sampled according to nb_children distribution. If nb_children is an interger, the random distribution is uniform between [1, nb_children]. Otherwise, you can give your own discrete distribution sampling function.
Parameters:  mtg: the mtg to modified
 root (id): vertex id on which the sub tree will be added.
Optional Parameters:  nb_vertices
 nb_children : an int or a discrete distribution sampling function.
Returns: The last added vid.
Examples: g = MTG() vid = g.add_component(g.root) random_tree(g, vid, nb_children=2, nb_vertices=20) print len(g) # 22
See also

openalea.mtg.mtg.
random_mtg
(tree, nb_scales)[source]¶ Convert a tree into an MTG of nb_scales.
Add a random sub tree at a given vertex id position root. The length of the sub_tree is nb_vertices. Each new vertex has at most nb_children children.
Parameters:  mtg: the mtg to modified
 root (id): vertex id on which the sub tree will be added.
Returns: The last added vid.
Examples: g = MTG() random_tree(g, g.root, nb_children=2, nb_vertices=20) print len(g) # 21
See also

openalea.mtg.mtg.
colored_tree
(tree, colors)[source]¶ Compute a mtg from a tree and the list of vertices to be quotiented.
Note
The tree has to be a real tree and not an MTG
Example: from random import randint, sample g = MTG() random_tree(g, g.root, nb_vertices=200) # At each scale, define the vertices which will define a complex nb_scales=4 colors = {} colors[3] = g.vertices() colors[2] = random.sample(colors[3], randint(1,len(g))) colors[2].sort() if g.root not in colors[2]: colors[2].insert(0, g.root) colors[1] = [g.root] g, mapping = colored_tree(g, colors)

openalea.mtg.mtg.
display_tree
(tree, vid, tab='', labels={}, edge_type={})[source]¶ Display a tree structure.
Download the source file ../../src/mtg/mtg.py
.