NAME
Bio::Phylo::Forest::Node - The tree node object.
SYNOPSIS
# some way to get nodes:
use Bio::Phylo::IO;
my $string = '((A,B),C);';
my $forest = Bio::Phylo::IO->parse(
-format => 'newick',
-string => $string
);
print ref $forest; # prints 'Bio::Phylo::Forest'
foreach my $tree ( @{ $forest->get_entities } ) {
print ref $tree; # prints 'Bio::Phylo::Forest::Tree'
foreach my $node ( @{ $tree->get_entities } ) {
print ref $node; # prints 'Bio::Phylo::Forest::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);
}
}
}
DESCRIPTION
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.
METHODS
CONSTRUCTOR
- new()
-
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 (Bio::Phylo::Forest::Node object) -taxon => $taxon (Bio::Phylo::Taxa::Taxon object) -branch_length => 0.423e+2 (a valid perl number format) -first_daughter => $f_daughter (Bio::Phylo::Forest::Node object) -last_daughter => $l_daughter (Bio::Phylo::Forest::Node object) -next_sister => $n_sister (Bio::Phylo::Forest::Node object) -previous_sister => $p_sister (Bio::Phylo::Forest::Node object) -name => 'node_name' (a string) -desc => 'this is a node' (a string) -score => 0.98 (a valid perl number format) -generic => { -posterior => 0.98, -bootstrap => 0.80 } (a hash reference)
MUTATORS
- set_taxon()
-
Type : Mutator Title : set_taxon Usage : $node->set_taxon($taxon); Function: Assigns taxon crossreferenced with node. Returns : Modified object. Args : If no argument is given, the currently assigned taxon is set to undefined. A valid argument is a Bio::Phylo::Taxa::Taxon object. - set_branch_length()
-
Type : Mutator Title : branch_length Usage : $node->set_branch_length(0.423e+2); Function: Assigns or retrieves a node's branch length. Returns : Modified object. Args : If no argument is given, the current branch length is set to undefined. A valid argument is a number in any of Perl's formats. - set_parent()
-
Type : Mutator Title : parent Usage : $node->set_parent($parent); Function: Assigns a node's parent. Returns : Modified object. Args : If no argument is given, the current parent is set to undefined. A valid argument is Bio::Phylo::Forest::Node object. - set_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. - set_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. - set_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. - set_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.
ACCESSORS
- get_name()
-
Type : Accessor Title : get_name Usage : my $name = $node->get_name; Function: Retrieves a node's name. Returns : SCALAR Args : NONE - get_taxon()
-
Type : Accessor Title : get_taxon Usage : my $taxon = $node->get_taxon; Function: Retrieves taxon crossreferenced with node. Returns : Bio::Phylo::Taxa::Taxon Args : NONE - get_branch_length()
-
Type : Accessor Title : get_branch_length Usage : my $branch_length = $node->get_branch_length; Function: Retrieves a node's branch length. Returns : FLOAT Args : NONE Comments: Test for "defined($node->get_branch_length)" for zero-length (but defined) branches. Testing "if ( $node->get_branch_length ) { ... }" yields false for zero-but-defined branches! - get_parent()
-
Type : Accessor Title : get_parent Usage : my $parent = $node->get_parent; Function: Retrieves a node's parent. Returns : Bio::Phylo::Forest::Node Args : NONE - get_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 - get_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 - get_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 - get_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 - get_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. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE - get_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 - get_children()
-
Type : Query Title : get_children Usage : my @children = @{ $node->get_children }; Function: Returns an array reference of immediate descendants, ordered from left to right. Returns : Array reference of Bio::Phylo::Forest::Node objects. Args : NONE - get_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. - get_terminals()
-
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 - get_internals()
-
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 - get_mrca()
-
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. - get_leftmost_terminal()
-
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 - get_rightmost_terminal()
-
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 - get_generic()
-
Type : Accessor Title : get_generic Usage : my $generic_value = $node->get_generic($key); # or my %generic_hash = %{ $node->get_generic }; # such that $generic_hash{$key} == $generic_value; Function: Retrieves value of a generic key/value pair attached to $node, given $key. If no $key is given, a reference to the entire hash is returned. Returns : A SCALAR string, or a HASH ref Args : Key/value pairs are stored in a hashref. If $node->set_generic(posterior => 0.3543) has been set, the value can be retrieved using $node->get_generic('posterior'); if multiple key/value pairs were set, e.g. $node->set_generic( x => 12, y => 80) and $node->get_generic is called without arguments, a hash reference { x => 12, y => 80 } is returned.
TESTS
- is_terminal()
-
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 - is_internal()
-
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 - is_descendant_of()
-
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. - is_ancestor_of()
-
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. - is_sister_of()
-
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. - is_outgroup_of()
-
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.
CALCULATIONS
- calc_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 - calc_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 - calc_max_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 - calc_min_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 - calc_max_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 - calc_min_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 - calc_patristic_distance()
-
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
SEE ALSO
- Bio::Phylo
-
This object inherits from Bio::Phylo, so the methods defined therein are also applicable to Bio::Phylo::Node objects.
- Bio::Phylo::Manual
-
Also see the manual: Bio::Phylo::Manual.
FORUM
CPAN hosts a discussion forum for Bio::Phylo. If you have trouble using this module the discussion forum is a good place to start posting questions (NOT bug reports, see below): http://www.cpanforum.com/dist/Bio-Phylo
BUGS
Please report any bugs or feature requests to bug-bio-phylo@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Phylo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Be sure to include the following in your request or comment, so that I know what version you're using:
$Id: Node.pm,v 1.10 2005/09/29 20:31:17 rvosa Exp $
AUTHOR
Rutger A. Vos,
- email:
rvosa@sfu.ca - web page: http://www.sfu.ca/~rvosa/
ACKNOWLEDGEMENTS
The author would like to thank Jason Stajich for many ideas borrowed from BioPerl http://www.bioperl.org, and CIPRES http://www.phylo.org and FAB* http://www.sfu.ca/~fabstar for comments and requests.
COPYRIGHT & LICENSE
Copyright 2005 Rutger A. Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.