dendropy.dataobject.tree – Tree Data

The TreeList Class

class dendropy.dataobject.tree.TreeList(*args, **kwargs)

Collects and coordinates a list of trees with the associated with the same set of taxa.

__init__ creates a new TreeList object, populating it with any iterable container with Tree object members passed as unnamed argument, or from a data source if stream and schema are passed.

If passed an iterable container, the objects in that container must be of type Tree (or derived). If the container is of type TreeList, then, because each Tree object must have the same TaxonSet reference as the containing TreeList, the trees in the container passed as an initialization argument will be deep-copied (except for associated TaxonSet and Taxon objects, which will be shallow-copied). If the container is any other type of iterable, then the Tree objects will be shallow-copied.

TreeList objects can directly thus be instantiated in the following ways:

# /usr/bin/env python

import StringIO
from dendropy import TaxonSet, Tree, TreeList

# empty tree
tlst1 = TreeList()

# populated from list of Tree objects
t1 = Tree(stream=StringIO("((A,B),(C,D))"), schema="newick")
t2 = Tree(stream=StringIO("((A,C),(B,D))"), schema="newick")
tlist2 = TreeList([t1, t2])

# tree from data source
tlst3 = TreeList(stream=StringIO("((A,B),(C,D));((A,C),(B,D));"), schema="newick") # same

# passing keywords to underlying tree parser
tlst4 = TreeList(stream=StringIO("((A,B),(C,D));((A,C),(B,D));"),
                 schema="newick",
                 taxon_set=tlst3.taxon_set,
                 encode_splits=True)

# deep-copied (but shallow-copy taxa) from another tree list
tlst5 = TreeList(t4)

# same
tls6 = TreeList([Tree(t) for t in tlst5])

# the canonical way to instantiate a TreeList from a data source
# is the use the `get_from_*` family of static factory methods
tlst7 = TreeList.get_from_stream(open('treefile.tre', 'rU'), "newick")
tlst8 = TreeList.get_from_path('sometrees.nexus', "nexus")
tlst9 = TreeList.get_from_string("((A,B),(C,D));((A,C),(B,D));", "newick")

# can also call `read()` on a TreeList object; each read adds the
# tree(s) found to the TreeList
tlst10 = TreeList()
tlst10.read(open('boot1.tre', 'rU'), "newick")
tlst10.read_from_stream(open('boot2.tre', 'rU'), "newick") # same as above
tlst10.read_from_string("((A,B),(C,D));((A,C),(B,D));", "newick")
tlst10.read_from_path("boot3.tre", "newick")

append(tree, reindex_taxa=True)

Homogeneity of taxon domain specified by self.taxon_set.

as_python_source(tree_list_name=None, tree_list_args=None, oids=False)

Returns string that will rebuild this tree list in Python.

consensus(min_freq=0.5, trees_splits_encoded=False, **kwargs)

Returns a consensus tree of all trees in self, with minumum frequency of split to be added to the consensus tree given by min_freq.

description(depth=1, indent=0, itemize='', output=None)

Returns description of object, up to level depth.

extend(tree_list, reindex_taxa=True)

Homogeneity of taxon domain specified by self.taxon_set.

frequency_of_split(**kwargs)

Given a split or bipartition specified as:

• a split bitmask given the keyword ‘split_bitmask’
• a list of Taxon objects given with the keyword taxa
• a list of taxon labels given with the keyword labels
• a list of oids given with the keyword oids

this function returns the proportion of trees in self in which the split is found.

read(stream, schema, **kwargs)

Populates the TreeList from a schema-formatted file-like source stream. schema must be a recognized and tree file schema, such as nexus, newick, etc, for which a reader is available. If this is not implemented for the schema specified, then a UnsupportedSchemaError is raised. If the source defines multiple tree collections (e.g. multiple NEXUS “Trees” blocks), then the keyword argument collection_offset can be used to specify the 0-based index of the tree collection. If not specified, or if value < 0, then all collections in the source are merged and read.

The following optional keyword arguments are recognized:

• encode_splits specifies whether or not split bitmasks will be

  calculated and attached to the edges.

• translate_dict should provide a dictionary mapping taxon numbers

  (as found in the source) to taxon labels (as defined in the source).

• rooted specifies the default rooting interpretation of the tree

  (see dendropy.dataio.nexustokenizer for details).

• finish_node_func is a function that will be applied to each node

  after it has been constructed.

• edge_len_type specifies the type of the edge lengths (int or float)

Other keyword arguments may be available, depending on the implementation of the reader specialized to handle schema formats.

reindex_subcomponent_taxa()

Synchronizes TaxonSet of member trees to taxon_set of self.

reindex_tree_taxa(tree)

Synchronizes tree TaxonSet with self.

write(stream, schema, **kwargs)

Writes out TreeList in schema to a destination described by given by stream.

Additionally, for some formats, the following keywords are recognized:

• edge_lengths : if False, edges will not write edge lengths [True]
• internal_labels : if False, internal labels will not be written [True]

The Tree Class

class dendropy.dataobject.tree.Tree(*args, **kwargs)

Fundamental class that encapsulates functionality and attributes need for working with trees. A Tree contains a seed_node attribute (from which the entire tree springs), which may or may not be the root node. The distinction is not consequential in the current implementation, which identifies the root node as a node without child_node objects.

__init__ creates a new Tree object, optionally constructing it by cloning another Tree object if this is passed as the first argument, or out of a data source if stream and schema are keyword arguments are passed with a file-like object and a schema-specification string object values respectively.

If stream and schema keyword arguments are given, will construct this Tree object from schema-formatted source given by file-like object stream. schema must be a recognized and tree file schema, such as nexus, newick, etc, for which a specialized tree list writer is available. If this is not implemented for the schema specified, then a UnsupportedSchemaError is raised. Other keywords will be passed to the underlying tree parser.

Tree objects can thus be instantiated in the following ways:

# /usr/bin/env python

from cStringIO import StringIO
from dendropy import Tree, TaxonSet

# empty tree
t1 = Tree()

# tree from data source
t2 = dendropy.Tree(stream=StringIO("((A,B),(C,D));"), schema="newick")

# passing keywords to underlying tree parser
t3 = dendropy.Tree(stream=StringIO("((A,B),(C,D));"),
          schema="newick",
          taxon_set=t3.taxon_set,
          encode_splits=True)

# tree structure deep-copied from another tree
t4 = dendropy.Tree(t3)
assert t4 is not t3                             # Trees are distinct
assert t4.symmetric_difference(t3) == 0         # and structure is identical
assert t4.taxon_set is t3.taxon_set             # BUT taxa are not cloned.
nds3 = [nd for nd in t3.postorder_node_iter()]  # Nodes in the two trees
nds4 = [nd for nd in t4.postorder_node_iter()]  # are distinct objects,
for i, n in enumerate(nds3):                    # and can be manipulated
    assert nds3[i] is not nds4[i]               # independentally.
egs3 = [eg for eg in t3.postorder_edge_iter()]  # Edges in the two trees
egs4 = [eg for eg in t4.postorder_edge_iter()]  # are also distinct objects,
for i, e in enumerate(egs3):                    # and can also be manipulated
    assert egs3[i] is not egs4[i]               # independentally.
lves3 = t3.leaf_nodes()                         # Leaf nodes in the two trees
lves4 = t4.leaf_nodes()                         # are also distinct objects,
for i, lf in enumerate(lves3):                  # but order is the same,
    assert lves3[i] is not lves4[i]             # and associated Taxon objects
    assert lves3[i].taxon is lves4[i].taxon     # are the same.

# to create deep copy of a tree with a different taxon set
taxa = TaxonSet()
t5 = dendropy.Tree(t3, taxon_set=taxa)
assert t5 is not t3                             # As above, the trees are distinct
assert t5.symmetric_difference(t3) == 0         # and the structures are identical,
assert t5.taxon_set is not t3.taxon_set         # but this time, the taxa *are* different
assert t5.taxon_set is taxa                     # as the given TaxonSet is used instead.
lves3 = t3.leaf_nodes()                         # Leaf nodes (and, for that matter other nodes
lves5 = t5.leaf_nodes()                         # as well as edges) are also distinct objects
for i, lf in enumerate(lves3):                  # and the order is the same, as above,
    assert lves3[i] is not lves5[i]             # but this time the associated Taxon
    assert lves3[i].taxon is not lves5[i].taxon # objects are distinct though the taxon
    assert lves3[i].taxon.label == lves5[i].taxon.label # labels are the same.

# the canonical way to instantiate a Tree from a data source
# is the use the `get_from_*` family of static factory methods
t6 = Tree.get_from_stream(open('treefile.tre', 'rU'), "newick", tree_offset=0)
t7 = Tree.get_from_path('sometrees.nexus',
        "nexus",
        collection_offset=2,
        tree_offset=1)
s = "((A,B),(C,D));((A,C),(B,D));"
t8 = Tree.get_from_string(s, "newick") # tree will be '((A,B),(C,D))'
t9 = Tree.get_from_string(s, "newick", tree_offset=1) # tree will be '((A,C),(B,D))'

# can also call `read()` on a Tree object; each read adds the
# *replaces* the current tree with the definition specified in the
# data source
t10 = Tree()
t10.read(open('boot1.tre', 'rU'), "newick", tree_offset=0)
t10.read_from_stream(open('boot2.tre', 'rU'), "newick") # same as above
t10.read_from_string("((A,B),(C,D));((A,C),(B,D));", "newick", tree_offset=0)
t10.read_from_path("mle.tre", "newick")

# to 'switch out' the TaxonSet of a tree, replace the reference and
# reindex the taxa:
t11 = Tree.get_from_string('((A,B),(C,D));', 'newick')
taxa = TaxonSet()
t11.taxon_set = taxa
t11.reindex_subcomponent_taxa()

age_order_node_iter(include_leaves=True, filter_fn=None, descending=False)

Iterates over nodes in order of age. If include_leaves is False, will skip leaves (default is not to skip leaves). If descending is True, will go from oldest nodes to youngest (default is asecending: youngest nodes to oldest).

as_ascii_plot(**kwargs)

Returns a string representation a graphic of this tree using ASCII characters.

Keyword arguments:

plot_metric

A string which specifies how branches should be scaled, one of: ‘age’ (distance from tips), ‘depth’ (distance from root), ‘level’ (number of branches from root) or ‘length’ (edge length/weights).

show_internal_node_labels

Boolean: whether or not to write out internal node labels.

• show_internal_node_ids

  Boolean: whether or not to write out internal node id’s.

leaf_spacing_factor

Positive integer: number of rows between each leaf.

display_width

Force a particular display width, in terms of number of columns.

as_newick_string(**kwargs)

kwargs[“reverse_translate”] can be function that takes a taxon and returns the label to appear in the tree.

as_python_source(tree_obj_name=None, tree_args=None, oids=False)

Returns string that will rebuild this tree in Python.

calc_node_ages(check_prec=1e-07)

Adds an attribute called “age” to each node, with the value equal to the sum of edge lengths from the node to the tips. If the lengths of different paths to the node differ by more than check_prec, then a ValueError exception will be raised indicating deviation from ultrametricity. If check_prec is negative or False, then this check will be skipped.

clone_from(other)

Clones the structure and properties of Tree object other.

coalescence_intervals()

Returns list of coalescence intervals of self., i.e., the waiting times between successive coalescence events.

collapse_unweighted_edges(threshold=1e-07, update_splits=False)

Collapse all edges with edge lengths less than or equal to threshold.

deroot()

Converts a degree-2 node at the root to a degree-3 node.

description(depth=1, indent=0, itemize='', output=None)

Returns description of object, up to level depth.

euclidean_distance(other_tree)

Returns Euclidean_distance distance between this tree and other_tree.

false_positives_and_negatives(other_tree)

Returns a tuple pair: all splits found in other but in self, and all splits in self not found in other.

find_edge(oid)

Finds the first edge with matching id.

find_missing_splits(other_tree)

Returns a list of splits that are in self, but not in other_tree.

find_node(filter_fn)

Finds the first node for which filter_fn(node) = True. For example, if:

filter_fn = lambda n: hasattr(n, 'genes') and n.genes is not None

then:

t.find_node(filter_fn=filter_fn)

will return all nodes which have an attributed ‘genes’ and this value is not None.

find_node_with_label(label)

Finds the first node with matching label.

find_node_with_taxon(taxon_filter_fn=None)

Finds the first node for which taxon_filter_fn(node.taxon) == True.

find_node_with_taxon_label(label)

Returns node with taxon with given label.

get_edge_set(filter_fn=None)

Returns the set of edges that are currently in the tree. Note: the returned set acts like a shallow copy of the edge set (adding or deleting elements from the set does not change the tree, but modifying the elements does).

get_node_set(filter_fn=None)

Returns the set of nodes that are currently in the tree

Note: the returned set acts like a shallow copy of the edge set (adding or deleting elements from the set does not change the tree, but modifying the elements does).

infer_taxa()

Returns a new TaxonSet object populated with taxa from this tree.

internal_nodes()

Returns list of internal node in the tree.

ladderize(ascending=True)

Sorts child nodes in ascending (if ascending is False) or descending (if ascending is False) order in terms of the number of children each child node has.

leaf_edge_iter(filter_fn=None)

Returns iterator over tree leaf edges.

leaf_iter(filter_fn=None)

Returns an iterator over tree leaf_nodes (order determined by postorder tree-traversal).

leaf_nodes()

Returns list of leaf_nodes on the tree.

length()

Returns sum of edge lengths of self. Edges with no lengths defined (None) will be considered to have a length of 0. Note that we do not overrride __len__ as this requires an integer return value.

level_order_edge_iter(filter_fn=None)

Returns level-order iterator over tree edges.

level_order_node_iter(filter_fn=None)

Returns level-order iterator over tree nodes.

mrca(**kwargs)

Returns the shallowest node in the tree (the node furthest from the root, or start_node, in the direction toward the tips of the tree) that has all of the taxa that:

• are specified by the split bitmask given by the keyword argument split_bitmask
• are in the list of Taxon objects given by the keyword argument ‘taxa’
• have the labels specified by the list of strings given by the keyword argument ‘taxon_labels’

Returns None if no appropriate node is found. Assumes that edges on tree have been decorated with treesplit. It is possible that split is not compatible with the subtree that is returned! (compatibility tests are not fully performed). This function is used to find the “insertion point” for a new split via a root to tip search.

node_ages(check_prec=1e-07)

Returns list of ages of speciation events / coalescence times on tree.

nodes(cmp_fn=None, filter_fn=None)

Returns list of nodes on the tree, sorted using cmp_fn.

postorder_edge_iter(filter_fn=None)

Returns postorder iterator over tree edges.

postorder_internal_node_iter(filter_fn=None)

Iterates over all internal nodes in post-order.

postorder_node_iter(filter_fn=None)

Returns postorder iterator over tree nodes.

preorder_edge_iter(filter_fn=None)

Returns preorder iterator over tree edges.

preorder_internal_node_iter(filter_fn=None)

Iterates over all internal nodes in pre-order.

preorder_node_iter(filter_fn=None)

Returns preorder iterator over tree nodes.

print_newick(**kwargs)

Convenience method to newick string representation of this tree to the standard output stream.

print_plot(**kwargs)

Writes an ASCII text graphic of this tree to standard output.

Keyword arguments:

plot_metric

A string which specifies how branches should be scaled, one of: ‘age’ (distance from tips), ‘depth’ (distance from root), ‘level’ (number of branches from root) or ‘length’ (edge length/weights).

show_internal_node_labels

Boolean: whether or not to write out internal node labels.

• show_internal_node_ids

  Boolean: whether or not to write out internal node id’s.

leaf_spacing_factor

Positive integer: number of rows between each leaf.

display_width

Force a particular display width, in terms of number of columns.

prune_leaves_without_taxa(update_splits=False, delete_outdegree_one=True)

Removes all terminal nodes that have their taxon attribute set to None.

prune_subtree(node, update_splits=False, delete_outdegree_one=True)

Removes subtree starting at node from tree.

prune_taxa(taxa, update_splits=False, delete_outdegree_one=True)

Removes terminal nodes associated with Taxon objects given by the container taxa (which can be any iterable, including a TaxonSet object) from self.

prune_taxa_with_labels(labels, update_splits=False, delete_outdegree_one=True)

Removes terminal nodes that are associated with Taxon objects with labels given by labels.

pybus_harvey_gamma(prec=1e-05)

Returns the gamma statistic of Pybus and Harvey (2000). This statistic is used to test for constancy of birth and death rates over the course of a phylogeny. Under the pure-birth process, the statistic should follow a standard Normal distibution: a Normal(mean=0, variance=1).

If the lengths of different paths to the node differ by more than prec,

then a ValueError exception will be raised indicating deviation from ultrametricty.

Raises a Value Error if the tree is not ultrametric, is non-binary, or has

only 2 leaves.

As a side effect a age attribute is added to the nodes of the self.

Pybus and Harvey. 2000. “Testing macro-evolutionary models using incomplete molecular phylogenies.” Proc. Royal Society Series B: Biological Sciences. (267). 2267-2272

randomly_assign_taxa(create_required_taxa=True, rng=None)

Randomly assigns taxa to leaf nodes. If the number of taxa defined in the taxon set of the tree is more than the number of tips, then a random subset of taxa in taxon_set will be assigned to the tips of tree. If the number of tips is more than the number of taxa in the taxon_set, and add_extra_taxa is not True [default], then new Taxon objects will be created and added to the taxon_set; if create_required_taxa is False, then an exception is raised.

In addition, a Random() object or equivalent can be passed using rng; otherwise GLOBAL_RNG is used.

randomly_reorient_tree(rng=None, update_splits=False)

Randomly picks a new rooting position and rotates the branches around all internal nodes in the self. If update_splits is True, the the split_bitmask and split_edges attributes kept valid.

randomly_rotate(rng=None)

Randomly rotates the branches around all internal nodes in self

read(stream, schema, **kwargs)

Populates/constructs objects of this type from schema-formatted data in the file-like object source stream.

Recognized keywords arguments are:

• taxon_set specifies the TaxonSet object to be attached to the

  trees parsed and manage their taxa. If not specified, then the TaxonSet object currently associated with the tree will be used.

• encode_splits specifies whether or not split bitmasks will be

  calculated and attached to the edges.

• translate_dict should provide a dictionary mapping taxon numbers (as

  found in the source) to taxon labels (as defined in the source).

• rooted specifies the default rooting interpretation of the tree (see

  dendropy.dataio.nexustokenizer for details).

• finish_node_func is a function that will be applied to each node

  after it has been constructed.

• edge_len_type specifies the type of the edge lengths (int or float)

If the source defines multiple tree collections (e.g. multiple NEXUS “Trees” blocks), then the keyword argument collection_offset can be used to specify the 0-based index of the tree collection, and the keyword argument tree_offset can be used to specify the 0-based index of the tree within the collection, as the source. If collection_offset is not specified and < 0, then all collections in the source are merged before considering tree_offset. If tree_offset is not specified, then the first tree (offset=0) is returned.

reindex_subcomponent_taxa()

Reassigns node taxon objects

reroot_at_edge(edge, length1=None, length2=None, update_splits=False, delete_outdegree_one=True)

Takes an internal edge, edge, adds a new node to it, and then roots the tree on the new node. length1 and length2 will be assigned to the new (sub-)edge leading to the old parent of the original edge, while length2 will be assigned to the old child of the original edge. If update_splits is True, then the edges’ split_bitmask and the tree’s split_edges attributes will be updated. If the old root of the tree had an outdegree of 2, then after this operation, it will have an outdegree of one. In this case, unless delete_outdegree_one is False, then it will be removed from the tree.

reroot_at_midpoint(update_splits=False, delete_outdegree_one=True)

Reroots the tree at the the mid-point of the longest distance between two taxa in a tree. Sets the rooted flag on the tree to True. If update_splits is True, then the edges’ split_bitmask and the tree’s split_edges attributes will be updated. If the old root of the tree had an outdegree of 2, then after this operation, it will have an outdegree of one. In this case, unless delete_outdegree_one is False, then it will be removed from the tree.

reroot_at_node(new_root_node, update_splits=False, delete_outdegree_one=True)

Takes an internal node, new_seed_node that must already be in the tree and roots the tree at that node. This is a ‘hard’ rerooting – i.e., changes the tree representation so tree traversal behaves as if the tree is rooted at ‘new_seed_node’, and changes the tree’s rooting state. If update_splits is True, then the edges’ split_bitmask and the tree’s split_edges attributes will be updated. If the old root of the tree had an outdegree of 2, then after this operation, it will have an outdegree of one. In this case, unless delete_outdegree_one is False, then it will be removed from the tree.

reseed_at(new_seed_node, update_splits=False, delete_outdegree_one=True)

Takes an internal node, new_seed_node that must already be in the tree and rotates the tree such that new_seed_node is the seed_node of the tree. This is a ‘soft’ rerooting – i.e., changes the tree representation so tree traversal behaves as if the tree is rooted at ‘new_seed_node’, but it does not actually change the tree’s rooting state. If update_splits is True, then the edges’ split_bitmask and the tree’s split_edges attributes will be updated. If the old root of the tree had an outdegree of 2, then after this operation, it will have an outdegree of one. In this case, unless delete_outdegree_one is False, then it will be removed from the tree.

resolve_polytomies(update_splits=False, rng=None)

Arbitrarily resolve polytomies using 0-length splits.

If rng is an object with a sample() method then the polytomy will be

resolved by sequentially adding (generating all tree topologies equiprobably rng.sample() should behave like random.sample()

If rng is not passed in, then polytomy is broken deterministically by

repeatedly joining pairs of children.

retain_taxa(taxa, update_splits=False, delete_outdegree_one=True)

Removes terminal nodes that are not associated with any of the Taxon objects given by taxa (which can be any iterable, including a TaxonSet object) from the self.

retain_taxa_with_labels(labels, update_splits=False, delete_outdegree_one=True)

Removes terminal nodes that are not associated with Taxon objects with labels given by labels.

robinson_foulds_distance(other_tree)

Returns Robinson-Foulds distance between this tree and other_tree.

scale_edges(edge_len_multiplier)

Multiplies every edge length in self by edge_len_multiplier

set_edge_lengths_from_node_ages(allow_negative_edges=False)

Sets the edge lengths of the tree so that the path lengths from the tips equal the value of the age attribute of the nodes.

strip_comments()

Remove comments from tree/nodes.

symmetric_difference(other_tree)

Returns the symmetric_distance between this tree and the tree given by other, i.e. the sum of splits found in one but not in both trees.

to_outgroup_position(outgroup_node, update_splits=False, delete_outdegree_one=True)

Reroots the tree at the parent of outgroup_node and makes outgroup_node the first child of the new root. This is just a convenience function to make it easy to place a clade as the first child under the root. Assumes that outgroup_node and outgroup_node.parent_node and are in the tree/ If update_splits is True, then the edges’ split_bitmask and the tree’s split_edges attributes will be updated. If the old root of the tree had an outdegree of 2, then after this operation, it will have an outdegree of one. In this case, unless delete_outdegree_one is False, then it will be removed from the tree.

unassign_taxa(exclude_leaves=False, exclude_internal=False)

Strips taxon assignments from tree. If exclude_leaves is True, then taxa on leaves will be retained. If exclude_internal is True, then taxa on internal nodes will be retained. The taxon_set is not affected by this operation.

update_splits(**kwargs)

Recalculates split hashes for tree.

write(stream, schema, **kwargs)

Writes out Tree in schema to a destination given by file-like object stream.

schema must be a recognized and tree file schema, such as nexus, newick, etc, for which a specialized tree list writer is available. If this is not implemented for the schema specified, then a UnsupportedSchemaError is raised.

Additionally, for some formats, the following keywords are recognized:

• edge_lengths : if False, edges will not write edge lengths [True]
• internal_labels : if False, internal labels will not be written [True]

write_as_dot(out, **kwargs)

Writes the tree to out as a DOT formatted digraph

write_ascii_plot(stream, **kwargs)

Writes an ASCII text graphic of this tree to stream.

Keyword arguments:

plot_metric

A string which specifies how branches should be scaled, one of: ‘age’ (distance from tips), ‘depth’ (distance from root), ‘level’ (number of branches from root) or ‘length’ (edge length/weights).

show_internal_node_labels

Boolean: whether or not to write out internal node labels.

• show_internal_node_ids

  Boolean: whether or not to write out internal node id’s.

leaf_spacing_factor

Positive integer: number of rows between each leaf.

display_width

Force a particular display width, in terms of number of columns.

The Node Class

class dendropy.dataobject.tree.Node(**kwargs)

A node on a tree, implementing only fundamental behaviour and properties.

add_child(node, edge_length=None, pos=None)

Adds a child node to this node. Results in the parent_node and containing_tree of the node being attached set to this node. If edge_length is given, then the new child’s edge length is set to this. Returns node that was just attached.

adjacent_nodes()

Return parent and child nodes.

age_order_iter(include_leaves=True, filter_fn=None, descending=False)

Iterates over nodes in order of age. If include_leaves is False, will skip leaves (default is not to skip leaves). If descending is True, will go from oldest nodes to youngest (default is asecending: youngest nodes to oldest).

ancestor_iter(filter_fn=None, inclusive=True)

Iterates over all ancestors of self. If inclusive is True, self is returned as the first item of the sequence.

as_newick_string(**kwargs)

This returns the Node as a NEWICK statement according to the given formatting rules. This should be used for debugging purposes only. For production purposes, use the the full-fledged ‘as_string()’ method of the object.

child_nodes()

Returns the a shallow-copy list of all child nodes.

collapse_clade()

Collapses all internal edges that are descendants of self.

description(depth=1, indent=0, itemize='', output=None, taxon_set=None)

Returns description of object, up to level depth.

distance_from_root()

Sum of edge lengths from root. Right now, ‘root’ is taken to be a node with no parent node.

distance_from_tip()

Sum of edge lengths from tip to node. If tree is not ultrametric (i.e., descendent edges have different lengths), then count the maximum of edge lengths. Note that the ‘calc_node_ages()’ method of dendropy.trees.Tree() is a more efficient way of doing this over the whole tree.

edge

Returns the edge subtending this node.

edge_length

Returns the length of the edge subtending this node.

get_adjacent_nodes()

Legacy synonym for ‘get_incident_edges()’

get_incident_edges()

Legacy synonym for ‘incident_edges()’

get_node_str(**kwargs)

returns a string that is an identifier for the node. This is called by the newick-writing functions, so the kwargs that affect how node labels show up in a newick string are the same ones used here: suppress_internal_labels is a Boolean, and defaults to False.

incident_edges()

Return parent and child edges.

is_internal()

Returns True if the node has child_nodes

is_leaf()

Returns True if the node has no child_nodes

leaf_iter(filter_fn=None)

Returns an iterator over the leaf_nodes that are descendants of self (with leaves returned in same order as a post-order traversal of the tree).

leaf_nodes()

Returns list of all leaf_nodes descended from this node (or just list with self as the only member if self is a leaf).

level()

Number of nodes between self and root.

level_order_iter(filter_fn=None)

Level-order traversal of self and its child_nodes. Filtered by filter_fn: node is only returned if no filter_fn is given or if filter_fn returns True

new_child(**kwargs)

Convenience class to create and add a new child to this node. Keyword arguments label, oid and taxon will be passed to Node(). edge_length, if given, will specify the length of the subtending edge of this child.

static nodeset_hash(nodes, attribute='oid')

Returns a hash of a set of nodes, based on the given attribute.

parent_node

Returns the parent node of this node.

postorder_internal_node_iter(filter_fn=None)

Iterates over all internal nodes in post-order.

postorder_iter(filter_fn=None)

Postorder traversal of the self and its child_nodes. Returns self and all descendants such that a node’s child_nodes (and their child_nodes) are visited before node. Filtered by filter_fn: node is only returned if no filter_fn is given or if filter_fn returns True.

preorder_internal_node_iter(filter_fn=None)

Iterates over all internal nodes in pre-order.

preorder_iter(filter_fn=None)

Preorder traversal of self and its child_nodes. Returns self and all descendants such that a node is returned before its child_nodes (and their child_nodes). Filtered by filter_fn: node is only returned if no filter_fn is given or if filter_fn returns True.

reinsert_nodes(nd_connection_list)

This function should be used to “undo” the effects of Node.reversible_remove_child NOTE: the behavior is only guaranteed if the tree has not been modified between the remove_child and reinsert_nodes calls! (or the tree has been restored such that the node/edge identities are identical to the state before the remove_child call.

The order of info in each tuple is:

0 - node removed 1 - parent of node removed 2 - pos in parent matrix 3 - children of node removed that were “stolen” 4 - edge that was lengthened by “stealing” length from node’s edge

remove_child(node, suppress_deg_two=False)

Removes a node from this nodes child set. Results in the parent of the node being removed set to None.

Returns the node removed.

suppress_deg_two should only be called on unrooted trees.

reversible_remove_child(node, suppress_deg_two=False)

This function is a (less-efficient) version of remove_child that also returns the data needed by reinsert_nodes to “undo” the removal.

Returns a list of tuples. The first element of each tuple is the node removed, the other elements are the information needed by reinsert_nodes’ in order to restore the tree to the same topology as it was before the call to `remove_child. If suppress_deg_two is False then the returned list will contain only one item.

suppress_deg_two should only be called on unrooted trees.

set_child_nodes(child_nodes)

Sets the child_nodes for this node. Side effects:

• sets the parent of each child node to this node
• sets the tail node of each child to self

set_children(child_nodes)

Legacy support: delegates to set_child_nodes()

sister_nodes()

Return all other children of parent, excluding self.

write_newick(out, **kwargs)

This returns the Node as a NEWICK statement according to the given formatting rules. This should be used for debugging purposes only. For production purposes, use the the full-fledged ‘write_to_stream()’ method of the object.

The Edge Class

class dendropy.dataobject.tree.Edge(**kwargs)

An edge on a tree. This class implements only the core functionality needed for trees.

__init__ creates an edge from tail_node to head_node. Modified from arbol.

adjacent_edges

Returns a list of all edges that “share” a node with self

collapse()

Inserts all children of the head_node of self as children of the tail_node of self in the same place in the child_node list that head_node had occupied. The edge length and head_node will no longer be part of the tree.

description(depth=1, indent=0, itemize='', output=None, taxon_set=None)

Returns description of object, up to level depth.

get_adjacent_edges()

Returns a list of all edges that “share” a node with self

is_internal()

Returns True if the head node has children

is_terminal()

Returns True if the head node has no children

new_edge(oid=None)

Returns a new edge object of the same class of this edge.