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_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_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   : 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_generic()

Type    : Mutator
Title   : set_generic
Usage   : $node->set_generic( $key => $value );
Function: Attaches a generic key => value pair to $node.
Returns : Modified object.
Args    : Comma separated key => value pairs.

ACCESSORS

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

to_xml()

Type    : Format converter
Title   : to_xml
Usage   : my $xml = $obj->to_xml;
Function: Turns the invocant object into an XML string.
Returns : SCALAR
Args    : NONE

DESTRUCTOR

DESTROY()

Type    : Destructor
Title   : DESTROY
Usage   : $phylo->DESTROY
Function: Destroys Phylo object
Alias   :
Returns : TRUE
Args    : none
Comments: You don't really need this,
          it is called automatically when
          the object goes out of scope.

Bio::Tree::NodeI methods

If Bio::Tree::NodeI is found in @INC, the Bio::Phylo::Forest::Node object will implement the Bio::Tree::NodeI methods. Consult the Bio::Tree::NodeI documentation for details about the following methods.

add_Descendent()

add_tag_value()

ancestor()

branch_length()

descendent_count()

description()

each_Descendent()

get_all_Descendents()

get_all_tags()

get_tag_values()

has_tag()

height()

id()

internal_id()

invalidate_height()

is_Leaf()

remove_all_tags()

remove_tag()

to_string()

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::Tree::NodeI

If you have BioPerl installed, the Bio::Phylo::Forest::Node will implement the NodeI interface.

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.21 2006/04/12 22:38:22 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.

cpanm Bio::Phylo

perl -MCPAN -e shell
install Bio::Phylo