NAME
Bio::Phylo::Forest::Tree - The tree object.
SYNOPSIS
# some way to get a tree
use Bio::Phylo::IO;
my $string = '((A,B),C);';
my $forest = Bio::Phylo::IO->parse(
-format => 'newick',
-string => $string
);
my $tree = $forest->first;
# do something:
print $tree->calc_imbalance;
# prints "1"DESCRIPTION
The object models a phylogenetic tree, a container of Bio::Phylo::Forest::Node objects. The tree object inherits from Bio::Phylo::Listable, so look there for more methods.
METHODS
CONSTRUCTORS
- new()
-
Type : Constructor Title : new Usage : my $tree = Bio::Phylo::Forest::Tree->new; Function: Instantiates a Bio::Phylo::Forest::Tree object. Returns : A Bio::Phylo::Forest::Tree object. Args : No required arguments. - new_from_bioperl()
-
Type : Constructor Title : new_from_bioperl Usage : my $tree = Bio::Phylo::Forest::Tree->new_from_bioperl( $bptree ); Function: Instantiates a Bio::Phylo::Forest::Tree object. Returns : A Bio::Phylo::Forest::Tree object. Args : A tree that implements Bio::Tree::TreeI
QUERIES
- get_terminals()
-
Type : Query Title : get_terminals Usage : my @terminals = @{ $tree->get_terminals }; Function: Retrieves all terminal nodes in the Bio::Phylo::Forest::Tree object. Returns : An array reference of Bio::Phylo::Forest::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 : my @internals = @{ $tree->get_internals }; Function: Retrieves all internal nodes in the Bio::Phylo::Forest::Tree object. Returns : An array reference of Bio::Phylo::Forest::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 : my $root = $tree->get_root; Function: Retrieves the first orphan in the current Bio::Phylo::Forest::Tree object - which should be the root. Returns : Bio::Phylo::Forest::Node Args : NONE - get_tallest_tip()
-
Type : Query Title : get_tallest_tip Usage : my $tip = $tree->get_tallest_tip; Function: Retrieves the node furthest from the root in the current Bio::Phylo::Forest::Tree object. Returns : Bio::Phylo::Forest::Node Args : NONE Comments: If the tree has branch lengths, the tallest tip is based on root-to-tip path length, else it is based on number of nodes to root - get_mrca()
-
Type : Query Title : get_mrca Usage : my $mrca = $tree->get_mrca(\@nodes); Function: Retrieves the most recent common ancestor of \@nodes Returns : Bio::Phylo::Forest::Node Args : A reference to an array of Bio::Phylo::Forest::Node objects in $tree.
TESTS
- is_rooted()
-
Type : Test Title : is_rooted Usage : if ( $tree->is_rooted ) { # do something } Function: Tests whether the invocant object is rooted. Returns : BOOLEAN Args : NONE Comments: A tree is considered unrooted if the basal split is a polytomy - is_binary()
-
Type : Test Title : is_binary Usage : if ( $tree->is_binary ) { # do something } Function: Tests whether the invocant object is bifurcating. Returns : BOOLEAN Args : NONE - is_ultrametric()
-
Type : Test Title : is_ultrametric Usage : if ( $tree->is_ultrametric(0.01) ) { # do something } Function: Tests whether the invocant 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()
-
Type : Test Title : is_monophyletic Usage : if ( $tree->is_monophyletic(\@tips, $node) ) { # do something } 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::Forest::Node::is_outgroup_of. - is_clade()
-
Type : Test Title : is_clade Usage : if ( $tree->is_clade(\@tips) ) { # do something } Function: Tests whether the set of \@tips forms a clade Returns : BOOLEAN Args : A reference to an array of Bio::Phylo::Forest::Node objects. Comments:
CALCULATIONS
- calc_tree_length()
-
Type : Calculation Title : calc_tree_length Usage : my $tree_length = $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 : my $tree_height = $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 : my $number_of_nodes = $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 : my $number_of_terminals = $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 : my $number_of_internals = $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 : my $total_paths = $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 : my $redundancy = $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 : my $imbalance = $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_i2()
-
Type : Calculation Title : calc_i2 Usage : my $ci2 = $tree->calc_i2; Function: Calculates I2 imbalance. Returns : FLOAT Args : NONE Comments: - calc_gamma()
-
Type : Calculation Title : calc_gamma Usage : my $gamma = $tree->calc_gamma(); Function: Calculates the Pybus gamma statistic Returns : FLOAT Args : NONE Comments: As described in Pybus, O.G. and Harvey, P.H., 2000. Testing macro-evolutionary models using incomplete molecular phylogenies. Proc. R. Soc. Lond. B 267, 2267-2272 - calc_fiala_stemminess()
-
Type : Calculation Title : calc_fiala_stemminess Usage : my $fiala_stemminess = $tree->calc_fiala_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_rohlf_stemminess Usage : my $rohlf_stemminess = $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 : my $resolution = $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 : my $branching_times = $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 : my $ltt = $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 - calc_symdiff()
-
Type : Calculation Title : calc_symdiff Usage : my $symdiff = $tree->calc_symdiff($other_tree); Function: Returns the symmetric difference metric between $tree and $other_tree, sensu Penny and Hendy, 1985. Returns : SCALAR Args : A Bio::Phylo::Forest::Tree object Comments: Trees in comparison must span the same set of terminal taxa or results are meaningless. - calc_fp()
-
Type : Calculation Title : calc_fp Usage : my $fp = $tree->calc_fp(); Function: Returns the Fair Proportion value for each terminal Returns : HASHREF Args : NONE - calc_es()
-
Type : Calculation Title : calc_es Usage : my $es = $tree->calc_es(); Function: Returns the Equal Splits value for each terminal Returns : HASHREF Args : NONE - calc_pe()
-
Type : Calculation Title : calc_pe Usage : my $es = $tree->calc_pe(); Function: Returns the Pendant Edge value for each terminal Returns : HASHREF Args : NONE - calc_shapley()
-
Type : Calculation Title : calc_shapley Usage : my $es = $tree->calc_shapley(); Function: Returns the Shapley value for each terminal Returns : HASHREF Args : NONE
VISITOR METHODS
- visit_pre_order()
-
Type : Visitor method Title : visit_pre_order Usage : $tree->visit_pre_order( sub{...} ); Function: Visits nodes in a pre order traversal, executes sub Returns : $tree Args : A subroutine reference that operates on visited nodes. Comments: - visit_level_order()
-
Type : Visitor method Title : visit_level_order Usage : $tree->visit_level_order( sub{...} ); Function: Visits nodes in a level order traversal, executes sub Returns : $tree Args : A subroutine reference that operates on visited nodes. Comments: - visit_post_order()
-
Type : Visitor method Title : visit_post_order Usage : $tree->visit_post_order( sub{...} ); Function: Visits nodes in a post order traversal, executes sub Returns : $tree Args : A subroutine reference that operates on visited nodes. Comments:
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 : The modified invocant. 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()
-
Type : Tree manipulator Title : scale Usage : $tree->scale($height); Function: Scales the tree to the specified height. Returns : The modified invocant. 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 : The modified invocant. 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::Forest::Tree object. Args : A reference to an array of taxon names. Comments: - keep_tips()
-
Type : Tree manipulator Title : keep_tips Usage : $tree->keep_tips(\@taxa); Function: Keeps specified taxa from invocant. Returns : The pruned Bio::Phylo::Forest::Tree object. Args : An array ref of taxon names or a Bio::Phylo::Taxa object Comments: - negative_to_zero()
-
Type : Tree manipulator Title : negative_to_zero Usage : $tree->negative_to_zero; Function: Converts negative branch lengths to zero. Returns : The modified invocant. Args : NONE Comments: - exponentiate()
-
Type : Tree manipulator Title : exponentiate Usage : $tree->exponentiate($power); Function: Raises branch lengths to $power. Returns : The modified invocant. Args : A $power in any of perl's number formats. - log_transform()
-
Type : Tree manipulator Title : log_transform Usage : $tree->log_transform($base); Function: Log $base transforms branch lengths. Returns : The modified invocant. Args : A $base in any of perl's number formats. - 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 : The modified invocant. Args : NONE Comments: - to_newick()
-
Type : Stringifier Title : to_newick Usage : my $string = $tree->to_newick; Function: Turns the invocant tree object into a newick string Returns : SCALAR Args : NONE - to_cipres()
-
Type : Format converter Title : to_cipres Usage : my $ciprestree = $tree->to_cipres; Function: Turns the invocant tree object into a CIPRES CORBA compliant data structure Returns : HASHREF Args : NONE
SEE ALSO
- Bio::Phylo::Listable
-
The Bio::Phylo::Forest::Tree object inherits from the Bio::Phylo::Listable object, so the methods defined therein also apply to trees.
- Bio::Tree::TreeI
-
If you have BioPerl installed, the Bio::Phylo::Forest::Tree will implement the TreeI 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: Tree.pm 4196 2007-07-12 03:04:01Z 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.