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

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

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)