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

NAME

Bio::Phylo::Trees::Tree - An object-oriented module for phylogenetic trees

SYNOPSIS

use Bio::Phylo::Trees::Tree;
my $tree = new Bio::Phylo::Trees::Tree;

DESCRIPTION

The object models a phylogenetic tree, which consists of Bio::Phylo::Trees::Node objects.

METHODS

CONSTRUCTOR

new()
Type    : Constructor
Title   : new
Usage   : my $tree = new Bio::Phylo::Trees::Tree;
Function: Instantiates a Bio::Phylo::Trees::Tree object.
Returns : A Bio::Phylo::Trees::Tree object.
Args    : none.

TREE POPULATION

_analyze()
Type    : Internal method
Title   : _analyze
Usage   : $tree->_analyze;
Function: Traverses the tree, creates references to first_daughter,
          last_daughter, next_sister and previous_sister.
Returns : A Bio::Phylo::Trees::Tree object.
Args    : none.
Comments: This method only looks at the parent, so theoretically
          one could mess around with the
          Bio::Phylo::Trees::Node::parent(Bio::Phylo::Trees::Node) method and
          subsequently call Bio::Phylo::Trees::Tree::_analyze to overwrite old
          (and wrong) child and sister references with new (and correct) ones.

QUERIES

get_terminals()
Type    : Query
Title   : get_terminals
Usage   : $tree->get_terminals;
Function: Retrieves all terminal nodes in
          the current Bio::Phylo::Trees::Tree object.
Returns : A list of Bio::Phylo::Trees::Node objects.
Args    : none.
Comments: If the tree is valid, this method retrieves the same set
          of nodes as $node->get_terminals($root). However, because
          there is no recursion it may be faster. Also, the node
          method by the same name does not see orphans.
get_internals()
Type    : Query
Title   : get_internals
Usage   : $tree->get_internals;
Function: Retrieves all internal nodes in the current Bio::Phylo::Trees::Tree
          object.
Returns : A list of Bio::Phylo::Trees::Node objects.
Args    : none.
Comments: If the tree is valid, this method retrieves the same set
          of nodes as $node->get_internals($root). However, because
          there is no recursion it may be faster. Also, the node
          method by the same name does not see orphans.
get_root()
Type    : Query
Title   : get_root
Usage   : $tree->get_root;
Function: Retrieves the first orphan in the current Bio::Phylo::Trees::Tree
          object - which should be the root.
Returns : A Bio::Phylo::Trees::Node object.
Args    : none.

TESTS

is_binary()
Type    : Test
Title   : is_binary
Usage   : $tree->is_binary;
Function: Tests whether the current Bio::Phylo::Trees::Tree
          object is bifurcating.
Returns : BOOLEAN.
Args    : none.
is_ultrametric($margin)
Type    : Test
Title   : is_ultrametric
Usage   : $tree->is_ultrametric(0.01);
Function: Tests whether the current Bio::Phylo::Trees::Tree object is
          ultrametric.
Returns : BOOLEAN.
Args    : Optional margin between pairwise comparisons (default = 0).
Comments: The test is done by performing all pairwise comparisons for
          root-to-tip path lengths. Since many programs introduce
          rounding errors in branch lengths the optional argument is
          available to test TRUE for nearly ultrametric trees. For
          example, a value of 0.01 indicates that no pairwise
          comparison may differ by more than 1%. Note: behaviour is
          undefined for negative branch lengths.
is_monophyletic(\@ARRAY, Bio::Phylo::Trees::Node)
Type    : Test
Title   : is_monophyletic
Usage   : $tree->is_monophyletic(\@tips, $outgroup);
Function: Tests whether the set of \@tips is
          monophyletic w.r.t. $outgroup.
Returns : BOOLEAN.
Args    : A reference to a list of nodes, and a node.
Comments: This method is essentially the
          same as Bio::Phylo::Trees::Node::is_outgroup_of.

CALCULATIONS

calc_tree_length()
Type    : Calculation
Title   : calc_tree_length
Usage   : $tree->calc_tree_length;
Function: Calculates the sum of all branch
          lengths (i.e. the tree length).
Returns : FLOAT
Args    : none.
calc_tree_height()
Type    : Calculation
Title   : calc_tree_height
Usage   : $tree->calc_tree_height;
Function: Calculates the height of the tree.
Returns : FLOAT
Args    : none.
Comments: For ultrametric trees this method returns the height, but this is
          done by averaging over all root-to-tip path lengths, so for
          additive trees the result should consequently be interpreted
          differently.
calc_number_of_nodes()
Type    : Calculation
Title   : calc_number_of_nodes
Usage   : $tree->calc_number_of_nodes;
Function: Calculates the number of nodes (internals AND terminals).
Returns : INT.
Args    : none.
calc_number_of_terminals()
Type    : Calculation
Title   : calc_number_of_terminals
Usage   : $tree->calc_number_of_terminals;
Function: Calculates the number of terminal nodes.
Returns : INT.
Args    : none.
calc_number_of_internals()
Type    : Calculation
Title   : calc_number_of_internals
Usage   : $tree->calc_number_of_internals;
Function: Calculates the number of internal nodes.
Returns : INT.
Args    : none.
calc_total_paths()
Type    : Calculation
Title   : calc_total_paths
Usage   : $tree->calc_total_paths;
Function: Calculates the sum of all root-to-tip path lengths.
Returns : FLOAT.
Args    : none.
calc_redundancy()
Type    : Calculation
Title   : calc_redundancy
Usage   : $tree->calc_redundancy;
Function: Calculates the amount of shared
          (redundant) history on the total.
Returns : FLOAT.
Args    : none
Comments: Redundancy is calculated as
1 / ( treelength - height / ( ntax * height - height ) )
calc_imbalance()
Type    : Calculation
Title   : calc_imbalance
Usage   : $tree->calc_imbalance;
Function: Calculates Colless' coefficient of tree imbalance.
Returns : FLOAT.
Args    : none
Comments: As described in Colless, D.H., 1982. The theory and practice of
          phylogenetic systematics. Systematic Zoology 31(1): 100-104
calc_fiala_stemminess()
Type    : Calculation
Title   : calc_stemminess
Usage   : $tree->calc_stemminess;
Function: Calculates stemminess measure Fiala and Sokal (1985).
Returns : FLOAT.
Args    : none
Comments: As described in Fiala, K.L. and R.R. Sokal, 1985. Factors determining
          the accuracy of cladogram estimation: evaluation using computer
          simulation. Evolution, 39: 609-622
calc_rohlf_stemminess()
Type    : Calculation
Title   : calc_stemminess
Usage   : $tree->calc_rohlf_stemminess;
Function: Calculates stemminess measure from Rohlf et al. (1990).
Returns : FLOAT.
Args    : none
Comments: As described in Rohlf, F.J., W.S. Chang, R.R. Sokal, J. Kim, 1990.
          Accuracy of estimated phylogenies: effects of tree topology and
          evolutionary model. Evolution, 44(6): 1671-1684
calc_resolution()
Type    : Calculation
Title   : calc_resolution
Usage   : $tree->calc_resolution;
Function: Calculates the total number of internal nodes over the
          total number of internal nodes on a fully bifurcating
          tree of the same size.
Returns : FLOAT.
Args    : none
calc_branching_times()
Type    : Calculation
Title   : calc_branching_times
Usage   : $tree->calc_branching_times;
Function: Returns a two-dimensional array. The first dimension
          consists of the "records", so that in the second
          dimension $AoA[$first][0] contains the internal node
          references, and $AoA[$first][1] the branching time
          of the internal node. The records are orderered from
          root to tips by time from the origin.
Returns : SCALAR[][] or FALSE.
Args    : none
calc_ltt()
Type    : Calculation
Title   : calc_ltt
Usage   : $tree->calc_ltt;
Function: Returns a two-dimensional array. The first dimension
          consists of the "records", so that in the second dimension
          $AoA[$first][0] contains the internal node references, and
          $AoA[$first][1] the branching time of the internal node,
          and $AoA[$first][2] the cumulative number of lineages over
          time. The records are orderered from root to tips by
          time from the origin.
Returns : SCALAR[][] or FALSE.
Args    : none

TREE MANIPULATION

ultrametricize()
Type    : Tree manipulator
Title   : ultrametricize
Usage   : $tree->ultrametricize();
Function: Sets all root-to-tip path lengths equal by stretching
          all terminal branches to the height of the tallest node.
Returns : A Bio::Phylo::Trees::Tree object.
Args    : none.
Comments: This method is analogous to the 'ultrametricize' command
          in Mesquite, i.e. no rate smoothing or anything like that
          happens, just a lengthening of terminal branches.
scale($height)
Type    : Tree manipulator
Title   : scale
Usage   : $tree->scale($height);
Function: Scales the tree to the specified height.
Returns : A Bio::Phylo::Trees::Tree object.
Args    : $height = a numerical value indicating root-to-tip path length.
Comments: This method uses the $tree->calc_tree_height method, and so for
          additive trees the *average* root-to-tip path length is scaled to
          $height (i.e. some nodes might be taller than $height, others
          shorter).
resolve()
Type    : Tree manipulator
Title   : resolve
Usage   : $tree->resolve();
Function: Breaks polytomies by inserting additional internal nodes orderered
          from left to right.
Returns : A binary Bio::Phylo::Trees::Tree object.
Args    :
Comments:
prune_tips()
Type    : Tree manipulator
Title   : prune_tips
Usage   : $tree->prune_tips(@taxa);
Function: Prunes specified taxa from invocant.
Returns : A pruned Bio::Phylo::Trees::Tree object.
Args    : A list of taxa.
Comments:
keep_tips()
Type    : Tree manipulator
Title   : keep_tips
Usage   : $tree->keep_tips(@taxa);
Function: Keeps specified taxa from invocant.
Returns : A pruned Bio::Phylo::Trees::Tree object.
Args    : A list of taxa.
Comments:
remove_unbranched_internals()
Type    : Tree manipulator
Title   : remove_unbranched_internals
Usage   : $tree->remove_unbranched_internals();
Function: Collapses internal nodes with fewer than 2 children.
Returns : A Bio::Phylo::Trees::Tree object.
Args    : None.
Comments:

CONTAINER

container
Type    : Internal method
Title   : container
Usage   : $tree->container;
Function:
Returns : SCALAR
Args    :
container_type
Type    : Internal method
Title   : container_type
Usage   : $tree->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.