Package ete2 :: Package coretype :: Module tree :: Class TreeNode
[hide private]
[frames] | no frames]

Class TreeNode

source code

object --+
         |
        TreeNode
Known Subclasses:

TreeNode (Tree) class is used to store a tree structure. A tree
consists of a collection of TreeNode instances connected in a
hierarchical way. Trees can be loaded from the New Hampshire Newick
format (newick).

CONSTRUCTOR ARGUMENTS:
======================

 * newick: Path to the file containing the tree or, alternatively,
   the text string containing the same information.

RETURNS:
========
 The TreeNode object which represents the base (root) of the
tree.

EXAMPLES:
=========
    t1 = Tree() # creates an empty tree
    t2 = Tree( '(A:1,(B:1,(C:1,D:1):0.5):0.5);' )
    t3 = Tree( '/home/user/myNewickFile.txt' )

Instance Methods [hide private]
 
__add__(self, value)
This allows to sum two trees.
source code
 
__and__(self, value)
This allows to execute tree&'A' to obtain the descendant node A
source code
 
__contains__(self, item)
Check if item belongs to this node.
source code
 
__init__(self, newick=None, format=0)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
source code
 
__iter__(self)
Iterator over leaf nodes
source code
 
__len__(self)
Node len returns number of children.
source code
 
__str__(self)
Print tree in newick format.
source code
 
_asciiArt(self, char1='-', show_internal=True, compact=False)
Returns the ASCII representation of the tree.
source code
 
_get_children(self) source code
 
_get_dist(self) source code
 
_get_support(self) source code
 
_get_up(self) source code
 
_iter_descendants_postorder(self)
Iterator over all desdecendant nodes.
source code
 
_iter_descendants_preorder(self)
Iterator over all desdecendant nodes.
source code
 
_set_children(self, value) source code
 
_set_dist(self, value) source code
 
_set_support(self, value) source code
 
_set_up(self, value) source code
 
add_child(self, child=None, name=None, dist=None, support=None)
Adds a new child to this node.
source code
 
add_feature(self, pr_name, pr_value)
Adds or updates a node's feature.
source code
 
add_features(self, **features)
Adds or updates a node's feature.
source code
 
add_sister(self, sister=None, name=None, dist=None)
Adds a sister to this node.
source code
 
collapse(self) source code
 
del_feature(self, pr_name)
Deletes permanently a node's feature.
source code
 
delete(self, prevent_nondicotomic=True)
Deletes node from the tree structure.
source code
 
describe(self)
Prints general information about this node and its connections.
source code
 
detach(self)
Detachs this node (and all its descendants) from its parent and returns the referent to itself.
source code
 
expand(self) source code
 
get_ascii(self, show_internal=True, compact=False)
Returns a string containing an ascii drawing of the tree.
source code
 
get_children(self)
Returns an independent list of node's children.
source code
 
get_common_ancestor(self, *target_nodes)
Returns the first common ancestor between this node and a given list of 'target_nodes'.
source code
 
get_descendants(self, strategy='preorder')
Returns the list of all nodes (leaves and internal) under this node.
source code
 
get_distance(self, target, target2=None, topology_only=False)
Returns the distance between two nodes.
source code
 
get_farthest_leaf(self, topology_only=False)
Returns node's farthest descendant node (which is always a leaf), and the distance to it.
source code
 
get_farthest_node(self, topology_only=False)
Returns the node's farthest descendant or ancestor node, and the distance to it.
source code
 
get_leaf_names(self)
Returns the list of terminal node names under the current node.
source code
 
get_leaves(self)
Returns the list of terminal nodes (leaves) under this node.
source code
 
get_leaves_by_name(self, name)
Returns a list of nodes marching a given name.
source code
 
get_midpoint_outgroup(self)
Returns the node that divides the current tree into two distance-balanced partitions.
source code
 
get_sisters(self)
Returns an indepent list of sister nodes.
source code
 
get_tree_root(self)
Returns the absolute root node of current tree structure.
source code
 
is_leaf(self) source code
 
is_root(self) source code
 
iter_descendants(self, strategy='preorder')
Returns an iterator over descendant nodes.
source code
 
iter_leaf_names(self)
Returns an iterator over the leaf names under this node.
source code
 
iter_leaves(self)
Returns an iterator over the leaves under this node.
source code
 
iter_search_nodes(self, **conditions) source code
 
populate(self, size, names_library=[], reuse_names=True)
Populates the partition under this node with a given number of leaves.
source code
 
prune(self, nodes)
Prunes the topology of this node in order to conserve only a selected list of leaf or internal nodes.
source code
 
remove_child(self, child)
Removes a child from this node (parent and child nodes still exit but are no longer connected).
source code
 
remove_sister(self, sister=None)
Removes a node's sister node.
source code
 
render(self, file_name, layout=None, w=None, h=None, img_properties=None, header=None)
Renders the tree structure into an image file.
source code
 
search_nodes(self, **conditions) source code
 
set_outgroup(self, outgroup)
Sets a descendant node as the outgroup of a tree.
source code
 
show(self, layout=None, image_properties=None)
Begins an interative session to visualize this node structure.
source code
 
swap_childs(self)
Swaps current childs order.
source code
 
traverse(self, strategy='preorder')
Returns an iterator that traverse the tree structure under this node.
source code
 
unroot(self)
Unroots this node.
source code
 
write(self, features=None, outfile=None, format=0)
Returns the newick representation of this node topology.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

Properties [hide private]
  children
  dist
  support
  up

Inherited from object: __class__

Method Details [hide private]

__contains__(self, item)
(In operator)

source code 

Check if item belongs to this node. The 'item' argument must be a node instance or its associated name.

__init__(self, newick=None, format=0)
(Constructor)

source code 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 

Print tree in newick format.

Overrides: object.__str__

_asciiArt(self, char1='-', show_internal=True, compact=False)

source code 

Returns the ASCII representation of the tree. Code taken from the PyCogent GPL project.

add_child(self, child=None, name=None, dist=None, support=None)

source code 

Adds a new child to this node. If child node is not suplied as an argument, a new node instance will be created.

ARGUMENTS:

* 'child': the node instance to be added as a child. * 'name': the name that will be given to the child. * 'dist': the distance from the node to the child. * 'support': the support value of child partition.

RETURNS:

The child node instace

add_sister(self, sister=None, name=None, dist=None)

source code 

Adds a sister to this node. If sister node is not supplied as an argument, a new TreeNode instance will be created and returned.

delete(self, prevent_nondicotomic=True)

source code 

Deletes node from the tree structure. Notice that this
method makes 'disapear' the node from the tree structure. This
means that children from the deleted node are transferred to the
next available parent.

EXAMPLE:
========
        / C
  root-|
       |        / B
        \--- H |
                \ A

  > root.delete(H) will produce this structure:

        / C
       |
  root-|--B
       |
        \ A

detach(self)

source code 

Detachs this node (and all its descendants) from its parent and returns the referent to itself.

Detached node conserves all its structure of descendants, and can be attached to another node through the 'add_child' function. This mechanisim can be seen as a cut and paste.

get_ascii(self, show_internal=True, compact=False)

source code 
Returns a string containing an ascii drawing of the tree.

Arguments:
- show_internal: includes internal edge names.
- compact: use exactly one line per tip.

get_common_ancestor(self, *target_nodes)

source code 

Returns the first common ancestor between this node and a given list of 'target_nodes'.

EXAMPLES:

t = tree.Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=common], (D:0.00001):0.000001):2.0[&&NHX:name=root];") A = t.get_descendants_by_name("A")[0] C = t.get_descendants_by_name("C")[0] common = A.get_common_ancestor(C) print common.name

get_descendants(self, strategy='preorder')

source code 

Returns the list of all nodes (leaves and internal) under this node. re buil See iter_descendants method.

get_distance(self, target, target2=None, topology_only=False)

source code 

Returns the distance between two nodes. If only one target is specified, it returns the distance bewtween the target and the current node.

ARGUMENTS:

'target': a node within the same tree structure.

'target2': a node within the same tree structure. If not specified, current node is used as target2.

RETURNS:

the distance between nodes

get_farthest_leaf(self, topology_only=False)

source code 

Returns node's farthest descendant node (which is always a leaf), and the
distance to it.

ARGUMENTS:
==========

  * 'topology_only' [True or False]: defines whether branch node
     distances should be discarded from analysis or not. If
     "True", only topological distance (number of steps to get the
     target node) will be used.

 RETURNS:
 ========
  A tuple = (farthest_node, dist_to_farthest_node)

get_farthest_node(self, topology_only=False)

source code 

Returns the node's farthest descendant or ancestor node, and the
distance to it.

ARGUMENTS:
==========

  * 'topology_only' [True or False]: defines whether branch node
   distances should be discarded from analysis or not. If
   "True", only topological distance (number of steps to get the
   target node) will be used.

RETURNS:
========
  A tuple = (farthest_node, dist_to_farthest_node)

populate(self, size, names_library=[], reuse_names=True)

source code 

Populates the partition under this node with a given number
of leaves. Internal nodes are added as required.

ARGUMENTS:
==========

  * 'size' is the number of leaf nodes to add to the current
    tree structure.

prune(self, nodes)

source code 

Prunes the topology of this node in order to conserve only a selected list of leaf or internal nodes. The algorithm deletes nodes until getting a consistent topology with a subset of nodes. Topology relationships among kept nodes is maintained.

ARGUMENTS:

* 'nodes' is a list of node names or node objects that must be kept.

EXAMPLES:

t = Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=I], (D:0.00001):0.000001[&&NHX:name=J]):2.0[&&NHX:name=root];") node_C = t.search_nodes(name="C")[0] t.prune(["A","D", node_C]) print t

remove_sister(self, sister=None)

source code 

Removes a node's sister node. It has the same effect as node.up.remove_child(sister).

If a sister node is not supplied, the first sister will be deleted and returned.

ARGUMENTS:

'sister': A node instance

RETURNS:

The removed node

set_outgroup(self, outgroup)

source code 

Sets a descendant node as the outgroup of a tree.  This function
can be used to root a tree or even an internal node.

ARGUMENTS:
==========

  * 'outgroup' is a leaf or internal node under the current tree
    structure.

traverse(self, strategy='preorder')

source code 

Returns an iterator that traverse the tree structure under this node.

ARGUMENTS:

'strategy' defines the way in which tree will be traversed. Possible values are: "preorder" (first parent and then children) 'postorder' (first children and the parent).

unroot(self)

source code 

Unroots this node. This function is intented to be used over the absolute tree root node, but it can be also be applied to any other internal node.

write(self, features=None, outfile=None, format=0)

source code 
Returns the newick representation of this node
topology. Several arguments control the way in which extra
data is shown for every node:

features: a list of feature names that want to be shown
(when available) for every node. Extended newick format is
used to represent data.

'format' defines the newick standard used to encode the
tree. See tutorial for details.

Example:
     t.get_newick(["species","name"], format=1)


Property Details [hide private]

children

Get Method:
_get_children(self)
Set Method:
_set_children(self, value)

dist

Get Method:
_get_dist(self)
Set Method:
_set_dist(self, value)

support

Get Method:
_get_support(self)
Set Method:
_set_support(self, value)

up

Get Method:
_get_up(self)
Set Method:
_set_up(self, value)