Bio::Phylo::Forest::Tree - The tree object.
# 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"
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.
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.
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
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.
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.
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
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: This method assumes the invocant tree has branch lengths.
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.
Type : Test Title : is_binary Usage : if ( $tree->is_binary ) { # do something } Function: Tests whether the invocant object is bifurcating. Returns : BOOLEAN Args : NONE
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.
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.
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:
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
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.
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
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
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
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
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 ) )
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
Type : Calculation Title : calc_i2 Usage : my $ci2 = $tree->calc_i2; Function: Calculates I2 imbalance. Returns : FLOAT Args : NONE Comments:
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
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
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
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
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
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
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.
Type : Calculation Title : calc_fp Usage : my $fp = $tree->calc_fp(); Function: Returns the Fair Proportion value for each terminal Returns : HASHREF Args : NONE
Type : Calculation Title : calc_es Usage : my $es = $tree->calc_es(); Function: Returns the Equal Splits value for each terminal Returns : HASHREF Args : NONE
Type : Calculation Title : calc_pe Usage : my $es = $tree->calc_pe(); Function: Returns the Pendant Edge value for each terminal Returns : HASHREF Args : NONE
Type : Calculation Title : calc_shapley Usage : my $es = $tree->calc_shapley(); Function: Returns the Shapley value for each terminal Returns : HASHREF Args : NONE
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.
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).
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:
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:
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 : A list of taxon names. Comments:
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:
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.
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.
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:
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
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
If Bio::Tree::TreeI is found in @INC, the Bio::Phylo::Forest::Tree object will implement the Bio::Tree::TreeI methods. Consult the Bio::Tree::TreeI documentation for details about the following methods.
The Bio::Phylo::Forest::Tree object inherits from the Bio::Phylo::Listable object, so the methods defined therein also apply to trees.
If you have BioPerl installed, the Bio::Phylo::Forest::Tree will implement the TreeI interface.
Also see the manual: Bio::Phylo::Manual.
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
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:
bug-bio-phylo@rt.cpan.org
$Id: Tree.pm,v 1.22 2006/04/12 22:38:22 rvosa Exp $
Rutger A. Vos,
rvosa@sfu.ca
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 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.
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.