Bio::Phylo::Forest::NodeRole - Extra behaviours for a node in a phylogenetic tree
# some way to get nodes: use Bio::Phylo::IO; my $string = '((A,B),C);'; my $forest = Bio::Phylo::IO->parse( -format => 'newick', -string => $string ); # prints 'Bio::Phylo::Forest' print ref $forest; foreach my $tree ( @{ $forest->get_entities } ) { # prints 'Bio::Phylo::Forest::Tree' print ref $tree; foreach my $node ( @{ $tree->get_entities } ) { # prints 'Bio::Phylo::Forest::Node' print ref $node; # node has a parent, i.e. is not root if ( $node->get_parent ) { $node->set_branch_length(1); } # node is root else { $node->set_branch_length(0); } } }
This module defines a node object and its methods. The node is fairly syntactically rich in terms of navigation, and additional getters are provided to further ease navigation from node to node. Typical first daughter -> next sister traversal and recursion is possible, but there are also shrinkwrapped methods that return for example all terminal descendants of the focal node, or all internals, etc.
Node objects are inserted into tree objects, although technically the tree object is only a container holding all the nodes together. Unless there are orphans all nodes can be reached without recourse to the tree object.
Node constructor.
Type : Constructor Title : new Usage : my $node = Bio::Phylo::Forest::Node->new; Function: Instantiates a Bio::Phylo::Forest::Node object Returns : Bio::Phylo::Forest::Node Args : All optional: -parent => $parent, -taxon => $taxon, -branch_length => 0.423e+2, -first_daughter => $f_daughter, -last_daughter => $l_daughter, -next_sister => $n_sister, -previous_sister => $p_sister, -name => 'node_name', -desc => 'this is a node', -score => 0.98, -generic => { -posterior => 0.98, -bootstrap => 0.80 }
Node constructor from bioperl Bio::Tree::NodeI argument.
Type : Constructor Title : new_from_bioperl Usage : my $node = Bio::Phylo::Forest::Node->new_from_bioperl( $bpnode ); Function: Instantiates a Bio::Phylo::Forest::Node object from a bioperl node object. Returns : Bio::Phylo::Forest::Node Args : An objects that implements Bio::Tree::NodeI Notes : The following BioPerl properties are copied: BioPerl output: Bio::Phylo output: ------------------------------------------------ id get_name branch_length get_branch_length description get_desc bootstrap get_generic('bootstrap') In addition all BioPerl tags and values are copied to set_generic( 'tag' => 'value' );
Removes argument child node (and its descendants) from invocants children.
Type : Mutator Title : prune_child Usage : $parent->prune_child($child); Function: Removes $child (and its descendants) from $parent's children Returns : Modified object. Args : A valid argument is Bio::Phylo::Forest::Node object.
Collapse node.
Type : Mutator Title : collapse Usage : $node->collapse; Function: Attaches invocant's children to invocant's parent. Returns : Modified object. Args : NONE Comments: If defined, adds invocant's branch length to that of its children. If $node is in a tree, removes itself from that tree.
Sets argument as invocant's first daughter.
Type : Mutator Title : set_first_daughter Usage : $node->set_first_daughter($f_daughter); Function: Assigns a node's leftmost daughter. Returns : Modified object. Args : Undefines the first daughter if no argument given. A valid argument is a Bio::Phylo::Forest::Node object.
Sets argument as invocant's last daughter.
Type : Mutator Title : set_last_daughter Usage : $node->set_last_daughter($l_daughter); Function: Assigns a node's rightmost daughter. Returns : Modified object. Args : A valid argument consists of a Bio::Phylo::Forest::Node object. If no argument is given, the value is set to undefined.
Sets argument as invocant's previous sister.
Type : Mutator Title : set_previous_sister Usage : $node->set_previous_sister($p_sister); Function: Assigns a node's previous sister (to the left). Returns : Modified object. Args : A valid argument consists of a Bio::Phylo::Forest::Node object. If no argument is given, the value is set to undefined.
Sets argument as invocant's next sister.
Type : Mutator Title : set_next_sister Usage : $node->set_next_sister($n_sister); Function: Assigns or retrieves a node's next sister (to the right). Returns : Modified object. Args : A valid argument consists of a Bio::Phylo::Forest::Node object. If no argument is given, the value is set to undefined.
Sets new (unbranched) node below invocant.
Type : Mutator Title : set_node_below Usage : my $new_node = $node->set_node_below; Function: Creates a new node below $node Returns : New node if tree was modified, undef otherwise Args : NONE
Reroots below invocant.
Type : Mutator Title : set_root_below Usage : $node->set_root_below; Function: Creates a new tree root below $node Returns : New root if tree was modified, undef otherwise Args : NONE Comments: This implementation is a port of @lh3's kn_reroot algorithm found here: http://lh3lh3.users.sourceforge.net/knhx.js
Gets invocant's first daughter.
Type : Accessor Title : get_first_daughter Usage : my $f_daughter = $node->get_first_daughter; Function: Retrieves a node's leftmost daughter. Returns : Bio::Phylo::Forest::Node Args : NONE
Gets invocant's last daughter.
Type : Accessor Title : get_last_daughter Usage : my $l_daughter = $node->get_last_daughter; Function: Retrieves a node's rightmost daughter. Returns : Bio::Phylo::Forest::Node Args : NONE
Gets invocant's previous sister.
Type : Accessor Title : get_previous_sister Usage : my $p_sister = $node->get_previous_sister; Function: Retrieves a node's previous sister (to the left). Returns : Bio::Phylo::Forest::Node Args : NONE
Gets invocant's next sister.
Type : Accessor Title : get_next_sister Usage : my $n_sister = $node->get_next_sister; Function: Retrieves a node's next sister (to the right). Returns : Bio::Phylo::Forest::Node Args : NONE
Gets invocant's ancestors.
Type : Query Title : get_ancestors Usage : my @ancestors = @{ $node->get_ancestors }; Function: Returns an array reference of ancestral nodes, ordered from young to old (i.e. $ancestors[-1] is root). Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE
Gets root relative to the invocant, i.e. by walking up the path of ancestors
Type : Query Title : get_root Usage : my $root = $node->get_root; Function: Gets root relative to the invocant Returns : Bio::Phylo::Forest::Node Args : NONE
Gets node farthest away from the invocant. By default this is nodal distance, but when supplied an optional true argument it is based on patristic distance instead.
Type : Query Title : get_farthest_node Usage : my $farthest = $node->get_farthest_node; Function: Gets node farthest away from the invocant. Returns : Bio::Phylo::Forest::Node Args : Optional, TRUE value to use patristic instead of nodal distance
Gets invocant's sisters.
Type : Query Title : get_sisters Usage : my @sisters = @{ $node->get_sisters }; Function: Returns an array reference of sisters, ordered from left to right. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE
Gets invocant's i'th child.
Type : Query Title : get_child Usage : my $child = $node->get_child($i); Function: Returns the child at index $i Returns : A Bio::Phylo::Forest::Node object. Args : An index (integer) $i Comments: if no index is specified, first child is returned
Gets invocant's descendants.
Type : Query Title : get_descendants Usage : my @descendants = @{ $node->get_descendants }; Function: Returns an array reference of descendants, recursively ordered breadth first. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : none.
Gets invocant's terminal descendants.
Type : Query Title : get_terminals Usage : my @terminals = @{ $node->get_terminals }; Function: Returns an array reference of terminal descendants. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE
Gets invocant's internal descendants.
Type : Query Title : get_internals Usage : my @internals = @{ $node->get_internals }; Function: Returns an array reference of internal descendants. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE
Gets invocant's most recent common ancestor shared with argument.
Type : Query Title : get_mrca Usage : my $mrca = $node->get_mrca($other_node); Function: Returns the most recent common ancestor of $node and $other_node. Returns : Bio::Phylo::Forest::Node Args : A Bio::Phylo::Forest::Node object in the same tree.
Gets invocant's leftmost terminal descendant.
Type : Query Title : get_leftmost_terminal Usage : my $leftmost_terminal = $node->get_leftmost_terminal; Function: Returns the leftmost terminal descendant of $node. Returns : Bio::Phylo::Forest::Node Args : NONE
Gets invocant's rightmost terminal descendant
Type : Query Title : get_rightmost_terminal Usage : my $rightmost_terminal = $node->get_rightmost_terminal; Function: Returns the rightmost terminal descendant of $node. Returns : Bio::Phylo::Forest::Node Args : NONE
Returns the tree subtended by the invocant
Type : Query Title : get_subtree Usage : my $tree = $node->get_subtree; Function: Returns the tree subtended by the invocant Returns : Bio::Phylo::Forest::Tree Args : NONE
Returns the subtree rooted at the common ancestor of u and v, and the respective subtrees that contain u and v
Type : Query Title : get_subtrees Usage : my ( $found_u, $found_v, $subtree, $subtree_u, $subtree_v ) = $root->get_subtrees($u,$v); Function: Returns the tree subtended by the invocant Returns : A list containing the following variables: - boolean: did we find u - boolean: did we find v - Bio::Phylo::Forest::Node - the root node of the connecting subtree - Bio::Phylo::Forest::Node - the root node of the subtree for $u - Bio::Phylo::Forest::Node - the root node of the subtree for $v Args : Two nodes, $u and $v Comments: This is a recursive method that is used by the RANKPROB calculations (see below). Typically you would invoke this method on the root node of the tree containing $u and $v, and the method then recurses up the tree. The tree must be bifurcating, or an exception is thrown.
Tests if invocant is a terminal node.
Type : Test Title : is_terminal Usage : if ( $node->is_terminal ) { # do something } Function: Returns true if node has no children (i.e. is terminal). Returns : BOOLEAN Args : NONE
Tests if invocant is an internal node.
Type : Test Title : is_internal Usage : if ( $node->is_internal ) { # do something } Function: Returns true if node has children (i.e. is internal). Returns : BOOLEAN Args : NONE
Tests if all direct descendents are terminal
Type : Test Title : is_preterminal Usage : if ( $node->is_preterminal ) { # do something } Function: Returns true if all direct descendents are terminal Returns : BOOLEAN Args : NONE
Tests if invocant is first sibling in left-to-right order.
Type : Test Title : is_first Usage : if ( $node->is_first ) { # do something } Function: Returns true if first sibling in left-to-right order. Returns : BOOLEAN Args : NONE
Tests if invocant is last sibling in left-to-right order.
Type : Test Title : is_last Usage : if ( $node->is_last ) { # do something } Function: Returns true if last sibling in left-to-right order. Returns : BOOLEAN Args : NONE
Tests if invocant is a root.
Type : Test Title : is_root Usage : if ( $node->is_root ) { # do something } Function: Returns true if node is a root Returns : BOOLEAN Args : NONE
Tests if invocant is descendant of argument.
Type : Test Title : is_descendant_of Usage : if ( $node->is_descendant_of($grandparent) ) { # do something } Function: Returns true if the node is a descendant of the argument. Returns : BOOLEAN Args : putative ancestor - a Bio::Phylo::Forest::Node object.
Tests if invocant is ancestor of argument.
Type : Test Title : is_ancestor_of Usage : if ( $node->is_ancestor_of($grandchild) ) { # do something } Function: Returns true if the node is an ancestor of the argument. Returns : BOOLEAN Args : putative descendant - a Bio::Phylo::Forest::Node object.
Tests if invocant is sister of argument.
Type : Test Title : is_sister_of Usage : if ( $node->is_sister_of($sister) ) { # do something } Function: Returns true if the node is a sister of the argument. Returns : BOOLEAN Args : putative sister - a Bio::Phylo::Forest::Node object.
Tests if invocant is child of argument.
Type : Test Title : is_child_of Usage : if ( $node->is_child_of($parent) ) { # do something } Function: Returns true if the node is a child of the argument. Returns : BOOLEAN Args : putative parent - a Bio::Phylo::Forest::Node object.
Test if invocant is outgroup of argument nodes.
Type : Test Title : is_outgroup_of Usage : if ( $node->is_outgroup_of(\@ingroup) ) { # do something } Function: Tests whether the set of \@ingroup is monophyletic with respect to the $node. Returns : BOOLEAN Args : A reference to an array of Bio::Phylo::Forest::Node objects; Comments: This method is essentially the same as &Bio::Phylo::Forest::Tree::is_monophyletic.
Test if argument(s) can be a child/children of invocant.
Type : Test Title : can_contain Usage : if ( $parent->can_contain(@children) ) { # do something } Function: Test if arguments can be children of invocant. Returns : BOOLEAN Args : An array of Bio::Phylo::Forest::Node objects; Comments: This method is an override of Bio::Phylo::Listable::can_contain. Since node objects hold a list of their children, they inherit from the listable class and so they need to be able to validate the contents of that list before they are inserted.
Calculates path to root.
Type : Calculation Title : calc_path_to_root Usage : my $path_to_root = $node->calc_path_to_root; Function: Returns the sum of branch lengths from $node to the root. Returns : FLOAT Args : NONE
Calculates number of nodes to root.
Type : Calculation Title : calc_nodes_to_root Usage : my $nodes_to_root = $node->calc_nodes_to_root; Function: Returns the number of nodes from $node to the root. Returns : INT Args : NONE
Calculates maximum number of nodes to tips.
Type : Calculation Title : calc_max_nodes_to_tips Usage : my $max_nodes_to_tips = $node->calc_max_nodes_to_tips; Function: Returns the maximum number of nodes from $node to tips. Returns : INT Args : NONE
Calculates minimum number of nodes to tips.
Type : Calculation Title : calc_min_nodes_to_tips Usage : my $min_nodes_to_tips = $node->calc_min_nodes_to_tips; Function: Returns the minimum number of nodes from $node to tips. Returns : INT Args : NONE
Calculates longest path to tips.
Type : Calculation Title : calc_max_path_to_tips Usage : my $max_path_to_tips = $node->calc_max_path_to_tips; Function: Returns the path length from $node to the tallest tip. Returns : FLOAT Args : NONE
Calculates shortest path to tips.
Type : Calculation Title : calc_min_path_to_tips Usage : my $min_path_to_tips = $node->calc_min_path_to_tips; Function: Returns the path length from $node to the shortest tip. Returns : FLOAT Args : NONE
Calculates patristic distance between invocant and argument.
Type : Calculation Title : calc_patristic_distance Usage : my $patristic_distance = $node->calc_patristic_distance($other_node); Function: Returns the patristic distance between $node and $other_node. Returns : FLOAT Args : Bio::Phylo::Forest::Node
Calculates node distance between invocant and argument.
Type : Calculation Title : calc_nodal_distance Usage : my $nodal_distance = $node->calc_nodal_distance($other_node); Function: Returns the number of nodes between $node and $other_node. Returns : INT Args : Bio::Phylo::Forest::Node
Calculates number of terminals subtended by the invocant
Type : Calculation Title : calc_terminals Usage : my $ntips = $node->calc_terminals; Function: Returns the number of terminals subtended by the invocant Returns : INT Args : None
Recurses from the root to the tips, returns an array reference at every step whose first element is a boolean set to true once the query node has been seen. The second element is an array that contains the number of subtended leaves - 1 for the query node and for all sisters of the nodes on the path from the query to the root. This method is used by the RANKPROB calculations (see below)
Type : Calculation Title : calc_rankprob_tipcounts Usage : my @rp = @{ $root->calc_rankprob_tipcounts($node) }; Function: Returns tip counts for RANKPROB Returns : ARRAY Args : NONE
Calculates the probabilities for all rank orderings that the invocant node can occupy among all possible labeled histories. Uses Stadler's RANKPROB algorithm as described in:
Gernhard, T. et al., 2006. Estimating the relative order of speciation or coalescence events on a given phylogeny. Evolutionary Bioinformatics Online. 2:285. http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2674681/.
Type : Calculation Title : calc_rankprob Usage : my @rp = @{ $root->calc_rankprob($node) }; Function: Returns the rank probabilities of the invocant node Returns : ARRAY, indices are ranks, values are probabilities Args : NONE
Calculates the expected rank and variance that the invocant node occupies among all possible labeled histories. Uses Stadler's RANKPROB algorithm as described in:
Type : Calculation Title : calc_expected_rank Usage : my ( $rank, $variance ) = $root->calc_expected_rank($node); Function: Calculates expected rank and variance Returns : Two numbers: rank and variance Args : NONE
Calculates the probability that the argument node is below the invocant node over all possible labeled histories. Uses Stadler's COMPARE algorithm as described in:
Type : Calculation Title : calc_rankprob_compare Usage : my $prob = $root->calc_rankprob_compare($u,$v); Function: Compares rankings of nodes Returns : A number (probability) Args : Bio::Phylo::Forest::Node
The methods below are similar in spirit to those by the same name in Bio::Phylo::Forest::Tree, except those in the tree class operate from the tree root, and those in this node class operate on an invocant node, and so these process a subtree.
Visits nodes depth first
Type : Visitor method Title : visit_depth_first Usage : $tree->visit_depth_first( -pre => sub{ ... }, -post => sub { ... } ); Function: Visits nodes in a depth first traversal, executes subs Returns : $tree Args : Optional: # first event handler, is executed when node is reached in recursion -pre => sub { print "pre: ", shift->get_name, "\n" }, # is executed if node has a daughter, but before that daughter is processed -pre_daughter => sub { print "pre_daughter: ", shift->get_name, "\n" }, # is executed if node has a daughter, after daughter has been processed -post_daughter => sub { print "post_daughter: ", shift->get_name, "\n" }, # is executed if node has no daughter -no_daughter => sub { print "no_daughter: ", shift->get_name, "\n" }, # is executed whether or not node has sisters, if it does have sisters # they're processed first -in => sub { print "in: ", shift->get_name, "\n" }, # is executed if node has a sister, before sister is processed -pre_sister => sub { print "pre_sister: ", shift->get_name, "\n" }, # is executed if node has a sister, after sister is processed -post_sister => sub { print "post_sister: ", shift->get_name, "\n" }, # is executed if node has no sister -no_sister => sub { print "no_sister: ", shift->get_name, "\n" }, # is executed last -post => sub { print "post: ", shift->get_name, "\n" }, # specifies traversal order, default 'ltr' means first_daugher -> next_sister # traversal, alternate value 'rtl' means last_daughter -> previous_sister traversal -order => 'ltr', # ltr = left-to-right, 'rtl' = right-to-left # passes sister node as second argument to pre_sister and post_sister subs, # and daughter node as second argument to pre_daughter and post_daughter subs -with_relatives => 1 # or any other true value Comments:
Visits nodes breadth first
Type : Visitor method Title : visit_breadth_first Usage : $tree->visit_breadth_first( -pre => sub{ ... }, -post => sub { ... } ); Function: Visits nodes in a breadth first traversal, executes handlers Returns : $tree Args : Optional handlers in the order in which they would be executed on an internal node: # first event handler, is executed when node is reached in recursion -pre => sub { print "pre: ", shift->get_name, "\n" }, # is executed if node has a sister, before sister is processed -pre_sister => sub { print "pre_sister: ", shift->get_name, "\n" }, # is executed if node has a sister, after sister is processed -post_sister => sub { print "post_sister: ", shift->get_name, "\n" }, # is executed if node has no sister -no_sister => sub { print "no_sister: ", shift->get_name, "\n" }, # is executed whether or not node has sisters, if it does have sisters # they're processed first -in => sub { print "in: ", shift->get_name, "\n" }, # is executed if node has a daughter, but before that daughter is processed -pre_daughter => sub { print "pre_daughter: ", shift->get_name, "\n" }, # is executed if node has a daughter, after daughter has been processed -post_daughter => sub { print "post_daughter: ", shift->get_name, "\n" }, # is executed if node has no daughter -no_daughter => sub { print "no_daughter: ", shift->get_name, "\n" }, # is executed last -post => sub { print "post: ", shift->get_name, "\n" }, # specifies traversal order, default 'ltr' means first_daugher -> next_sister # traversal, alternate value 'rtl' means last_daughter -> previous_sister traversal -order => 'ltr', # ltr = left-to-right, 'rtl' = right-to-left Comments:
Visits nodes in a level order traversal.
Type : Visitor method Title : visit_level_order Usage : $tree->visit_level_order( sub{...} ); Function: Visits nodes in a level order traversal, executes sub Returns : $tree Args : A subroutine reference that operates on visited nodes. Comments:
Serializes invocant to xml.
Type : Serializer Title : to_xml Usage : my $xml = $obj->to_xml; Function: Turns the invocant object (and its descendants )into an XML string. Returns : SCALAR Args : NONE
Serializes subtree subtended by invocant to newick string.
Type : Serializer Title : to_newick Usage : my $newick = $obj->to_newick; Function: Turns the invocant object into a newick string. Returns : SCALAR Args : takes same arguments as Bio::Phylo::Unparsers::Newick Comments: takes same arguments as Bio::Phylo::Unparsers::Newick
Type : Serializer Title : to_dom Usage : $node->to_dom($dom) Function: Generates an array of DOM elements from the invocant's descendants Returns : an array of Element objects Args : DOM factory object
There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.
This object inherits from Bio::Phylo::Taxa::TaxonLinker, so methods defined there are also applicable here.
This object inherits from Bio::Phylo::Listable, so methods defined there are also applicable here.
Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com.
If you use Bio::Phylo in published research, please cite it:
Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/1471-2105-12-63
To install Bio::Phylo, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Phylo
CPAN shell
perl -MCPAN -e shell install Bio::Phylo
For more information on module installation, please visit the detailed CPAN module installation guide.