/ 
Bio-Phylo-0.01
River stage two • 8 direct dependents • 17 total dependents
/ Bio::Phylo::Trees::Node

NAME

Bio::Phylo::Trees::Node - An object-oriented module for nodes in phylogenetic trees.

SYNOPSIS

use Bio::Phylo::Trees::Node;

my $node = Bio::Phylo::Trees::Node->new(
   -name=>'Homo_sapiens',
   -desc=>'Unstable terminal node in NJ tree',
   -branch_length=>5.04e+20
);

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 = new Bio::Phylo::Trees::Node;
Function: Initializes a Bio::Phylo::Trees::Node object
Returns : Bio::Phylo::Trees::Node
Args    : none

MUTATORS

set_name($name)
Type    : Mutator
Title   : set_name
Usage   : $node->set_name($name);
Function: Assigns a node's name.
Returns : NONE
Args    : Argument must be a string that doesn't contain [;|,|:\(|\)]
set_taxon($taxon)
Type    : Mutator
Title   : set_taxon
Usage   : $node->set_taxon($taxon);
Function: Assigns taxon crossreferenced with node.
Returns : NONE
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($bl)
Type    : Mutator
Title   : branch_length
Usage   : $node->set_branch_length($bl);
Function: Assigns or retrieves a node's branch length.
Returns : NONE
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($p)
Type    : Mutator
Title   : parent
Usage   : $node->set_parent($p);
Function: Assigns a node's parent.
Returns : NONE
Args    : If no argument is given, the current parent is set to undefined. A
          valid argument is Bio::Phylo::Trees::Node object.
set_first_daughter($fd)
Type    : Mutator
Title   : set_first_daughter
Usage   : $node->set_first_daughter($fd);
Function: Assigns a node's leftmost daughter.
Returns : NONE
Args    : Undefines the first daughter if no argument given. A valid argument
          is a Bio::Phylo::Trees::Node object.
set_last_daughter($ld)
Type    : Mutator
Title   : set_last_daughter
Usage   : $node->set_last_daughter($ld);
Function: Assigns a node's rightmost daughter.
Returns : NONE
Args    : A valid argument consists of a Bio::Phylo::Trees::Node object. If no
          argument is given, the value is set to undefined.
set_next_sister($ns)
Type    : Mutator
Title   : set_next_sister
Usage   : $node->set_next_sister($ns);
Function: Assigns or retrieves a node's next sister (to the right).
Returns : NONE
Args    : A valid argument consists of a Bio::Phylo::Trees::Node object. If no
          argument is given, the value is set to undefined.
set_previous_sister($ps)
Type    : Mutator
Title   : set_previous_sister
Usage   : $node->set_previous_sister($ps);
Function: Assigns a node's previous sister (to the left).
Returns : NONE
Args    : A valid argument consists of a Bio::Phylo::Trees::Node object. If no
          argument is given, the value is set to undefined.
set_generic(%generic)
Type    : Mutator
Title   : set_generic
Usage   : $node->set_generic(%generic);
Function: Assigns generic key/value pairs to the invocant.
Returns : NONE
Args    : Valid arguments constitute key/value pairs, for example:
          $node->set_generic(posterior => 0.87565);

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
get_parent()
Type    : Accessor
Title   : get_parent
Usage   : my $parent = $node->get_parent;
Function: Retrieves a node's parent.
Returns :
get_first_daughter()
Type    : Accessor
Title   : get_first_daughter
Usage   : my $first_daughter = $node->get_first_daughter();
Function: Retrieves a node's leftmost daughter.
Returns : A Bio::Phylo::Trees::Node object.
get_last_daughter()
Type    : Accessor
Title   : last_daughter
Usage   : my $last_daughter = $node->get_last_daughter;
Function: Retrieves a node's rightmost daughter.
Returns : A Bio::Phylo::Trees::Node object.
get_next_sister()
Type    : Accessor
Title   : next_sister
Usage   : my $next_sister = $node->get_next_sister;
Function: Retrieves a node's next sister (to the right).
Returns : A Bio::Phylo::Trees::Node object.
Args    : An argument of Bio::Phylo::Trees::Node is possible, but maybe
          not such a great idea. Unless you have some way of keeping
          track of all the relationships you might end up with
          circular references or orphans.
get_previous_sister()
Type    : Accessor
Title   : get_previous_sister
Usage   : my $previous_sister = $node->get_previous_sister;
Function: Retrieves a node's previous sister (to the left).
Returns : A Bio::Phylo::Trees::Nodeobject.
Args    : An argument of Bio::Phylo::Trees::Node is possible, but maybe
          not such a great idea. Unless you have some way of keeping
          track of all the relationships you might end up with
          circular references or orphans.
get_generic()
Type    : Accessor
Title   : get_generic
Usage   : my $get_generic = $node->get_generic($key);
Function: Retrieves value of a generic key/value pair given $key.
Returns : A SCALAR string
Args    : Key/value pairs are stored as hashrefs. If
          $node->set_generic(posterior => 0.3543) has been set, the value
          can be retrieved using $node->get_generic('posterior');

TESTS

is_terminal()
Type    : Test
Title   : is_terminal
Usage   : $node->is_terminal;
Function: Returns true if node has no children (i.e. is terminal).
Returns : BOOLEAN
Args    : none
is_internal()
Type    : Test
Title   : is_internal
Usage   : $node->is_internal;
Function: Returns true if node has children (i.e. is internal).
Returns : BOOLEAN
Args    : none
is_descendant_of(Bio::Phylo::Trees::Node)
Type    : Test
Title   : is_descendant_of
Usage   : $node->is_descendant_of($grandparent);
Function: Returns true if the node is a descendant of the argument.
Returns : BOOLEAN
Args    : putative ancestor - a Bio::Phylo::Trees::Node object.
is_ancestor_of(Bio::Phylo::Trees::Node)
Type    : Test
Title   : is_ancestor_of
Usage   : $node->is_ancestor_of($grandchild);
Function: Returns true if the node is an ancestor of the argument.
Returns : BOOLEAN
Args    : putative descendant - a Bio::Phylo::Trees::Node object.
is_sister_of(Bio::Phylo::Trees::Node)
Type    : Test
Title   : is_sister_of
Usage   : $node->is_sister_of($sister);
Function: Returns true if the node is a sister of the argument.
Returns : BOOLEAN
Args    : putative sister - a Bio::Phylo::Trees::Node object.
is_outgroup_of(\@{Bio::Phylo::Trees::Node, Bio::Phylo::Trees::Node})
Type    : Test
Title   : is_outgroup_of
Usage   : $outgroup->is_outgroup_of(\@ingroup);
Function: Tests whether the set of \@ingroup is monophyletic
          with respect to the $outgroup.
Returns : BOOLEAN
Args    : A reference to a list of Bio::Phylo::Trees::Node objects;
Comments: This method is essentially the same as
          Bio::Phylo::Trees::Tree::is_monophyletic.

QUERIES

get_ancestors()
Type    : Query
Title   : get_ancestors
Usage   : $node->get_ancestors;
Function: Returns a list of ancestral nodes,
          ordered from young to old.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
get_sisters()
Type    : Query
Title   : get_sisters
Usage   : $node->get_sisters;
Function: Returns a list of sisters, ordered from left to right.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
get_children()
Type    : Query
Title   : get_children
Usage   : $node->get_children;
Function: Returns a list of immediate descendants,
          ordered from left to right.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
get_descendants()
Type    : Query
Title   : get_descendants
Usage   : $node->get_descendants;
Function: Returns a list of descendants,
          recursively ordered breadth first.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
_desc()
Type    : Internal method
Title   : _desc
Usage   : $node->_desc(\@nodes);
Function: Performs recursion for Bio::Phylo::Trees::Node::get_descendants()
Returns : A Bio::Phylo::Trees::Node object.
Args    : A Bio::Phylo::Trees::Node object.
Comments: This method works in conjunction with
          Bio::Phylo::Trees::Node::get_descendants() - the latter simply calls
          the former with a set of nodes, and the former returns their
          children. Bio::Phylo::Trees::Node::get_descendants() then calls
          Bio::Phylo::Trees::Node::_desc with this set of children, and so on
          until all nodes are terminals. A first_daughter ->
          next_sister postorder traversal in a single method would
          have been more elegant - though not more efficient, in
          terms of visited nodes.
get_terminals()
Type    : Query
Title   : get_terminals
Usage   : $node->get_terminals;
Function: Returns a list of terminal descendants.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
get_internals()
Type    : Query
Title   : get_internals
Usage   : $node->get_internals;
Function: Returns a list of internal descendants.
Returns : List of Bio::Phylo::Trees::Node objects.
Args    : none.
get_mrca(Bio::Phylo::Trees::Node)
Type    : Query
Title   : get_mrca(Bio::Phylo::Trees::Node)
Usage   : $node->get_mrca($other_node);
Function: Returns the most recent common ancestor
          of $node and $other_node.
Returns : An Bio::Phylo::Trees::Node object.
Args    : An Bio::Phylo::Trees::Node object.
get_leftmost_terminal()
Type    : Query
Title   : get_leftmost_terminal
Usage   : $node->get_leftmost_terminal;
Function: Returns the leftmost terminal descendant of $node.
Returns : A Bio::Phylo::Trees::Node object.
Args    : none.
get_rightmost_terminal()
Type    : Query
Title   : get_rightmost_terminal
Usage   : $node->get_rightmost_terminal;
Function: Returns the rightmost terminal descendant of $node.
Returns : A Bio::Phylo::Trees::Node object.
Args    : none.

CALCULATIONS

calc_path_to_root()
Type    : Calculation
Title   : calc_path_to_root
Usage   : $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   : $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   : $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   : $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   : $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   : $node->calc_min_path_to_tips;
Function: Returns the path length from $node to the shortest tip.
Returns : FLOAT
Args    : none.
calc_patristic_distance(Bio::Phylo::Trees::Node)
Type    : Calculation
Title   : calc_patristic_distance(Bio::Phylo::Trees::Node)
Usage   : $node->calc_patristic_distance($other_node);
Function: Returns the patristic distance
          between $node and $other_node.
Returns : FLOAT
Args    : A Bio::Phylo::Trees::Node object.

CONTAINER

container
Type    : Internal method
Title   : container
Usage   : $node->container;
Function:
Returns : SCALAR
Args    :
container_type
Type    : Internal method
Title   : container_type
Usage   : $node->container_type;
Function:
Returns : SCALAR
Args    :

AUTHOR

Rutger Vos, <rvosa@sfu.ca>

BUGS

Please report any bugs or feature requests to bug-phylo@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Phylo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

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 Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.