/ 
Bio-Phylo-0.17_RC2
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Forest::Node

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
);

# 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);
      }
   }
}

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,
          -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
          }
new_from_bioperl()
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

MUTATORS

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_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.
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_child()
Type    : Mutator
Title   : set_child
Usage   : $node->set_child($child);
Function: Assigns a new child to $node
Returns : Modified object.
Args    : A valid argument consists of a
          Bio::Phylo::Forest::Node object.
set_branch_length()
Type    : Mutator
Title   : set_branch_length
Usage   : $node->set_branch_length(0.423e+2);
Function: Assigns 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_root_below()
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: throws Bio::Phylo::Util::Exceptions::BadArgs if 
          $node isn't part of a tree

ACCESSORS

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_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_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_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_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
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

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
to_xml()
Type    : Serializer
Title   : to_xml
Usage   : my $xml = $obj->to_xml;
Function: Turns the invocant object into an XML string.
Returns : SCALAR
Args    : NONE
to_newick()
Type    : Serializer
Title   : to_newick
Usage   : my $newick = $obj->to_newick;
Function: Turns the invocant object into a newick string.
Returns : SCALAR
Args    : NONE

SEE ALSO

Bio::Phylo

This object inherits from Bio::Phylo, so the methods defined therein are also applicable to Bio::Phylo::Forest::Node objects.

Bio::Phylo::Taxa::TaxonLinker

This object inherits from Bio::Phylo::Taxa::TaxonLinker, so methods defined there are also applicable here.

Bio::Phylo::Util::XMLWritable

This object inherits from Bio::Phylo::Util::XMLWritable, so methods defined there are also applicable here.

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 4193 2007-07-11 20:26:06Z rvosa $

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.