NAME
Bio::Phylo::Forest::TreeRole  Extra behaviours for a phylogenetic tree
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()

Tree constructor.
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()

Tree constructor from Bio::Tree::TreeI argument.
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_midpoint()

Gets node that divides tree into two distancebalanced partitions.
Type : Query Title : get_midpoint Usage : my $midpoint = $tree>get_midpoint; Function: Gets node nearest to the middle of the longest path Returns : A Bio::Phylo::Forest::Node object. Args : NONE Comments: This algorithm was ported from ETE. It assumes the tree has branch lengths.
 get_terminals()

Get terminal nodes.
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()

Get internal nodes.
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_cherries()

Get all cherries, i.e. nodes that have two terminal children
Type : Query Title : get_cherries Usage : my @cherries = @{ $tree>get_cherries }; Function: Returns an array ref of cherries Returns : ARRAY Args : NONE
 get_all_rootings()

Gets a forest of all rooted versions of the invocant tree.
Type : Query Title : get_all_rootings Usage : my $forest = $tree>get_all_rootings; Function: Returns an array ref of cherries Returns : Bio::Phylo::Forest object Args : NONE Comments: This method assumes the invocant tree has a basal trichotomy. "Rooted" trees with a basal bifurcation will give strange results.
 get_root()

Get root node.
Type : Query Title : get_root Usage : my $root = $tree>get_root; Function: Returns the root node. Returns : Bio::Phylo::Forest::Node Args : NONE
 get_ntax()

Gets number of tips
Type : Query Title : get_ntax Usage : my $ntax = $tree>get_ntax; Function: Calculates the number of terminal nodes Returns : Int Args : NONE
 get_tallest_tip()

Retrieves the node furthest from the root.
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 roottotip path length, else it is based on number of nodes to root
 get_nodes_for_taxa()

Gets node objects for the supplied taxon objects
Type : Query Title : get_nodes_for_taxa Usage : my @nodes = @{ $tree>get_nodes_for_taxa(\@taxa) }; Function: Gets node objects for the supplied taxon objects Returns : array ref of Bio::Phylo::Forest::Node objects Args : A reference to an array of Bio::Phylo::Taxa::Taxon objects or a Bio::Phylo::Taxa object
 get_mrca()

Get most recent common ancestor of argument nodes.
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_binary()

Test if tree is bifurcating.
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()

Test if tree 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 roottotip 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()

Tests if first argument (node array ref) is monophyletic with respect to second argument.
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_paraphyletic()

Type : Test Title : is_paraphyletic Usage : if ( $tree>is_paraphyletic(\@nodes,$node) ){ } Function: Tests whether or not a given set of nodes are paraphyletic (representing the full clade) given an outgroup Returns : [1,0,1] , 1 if the group is not monophyletic 0 if the group is not paraphyletic 1 if the group is paraphyletic Args : Array ref of node objects which are in the tree, Outgroup to compare the nodes to
 is_clade()

Tests if argument (node array ref) forms a 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, or a reference to an array of Bio::Phylo::Taxa::Taxon objects, or a Bio::Phylo::Taxa object Comments:
 is_cladogram()

Tests if tree is a cladogram (i.e. no branch lengths)
Type : Test Title : is_cladogram Usage : if ( $tree>is_cladogram() ) { # do something } Function: Tests whether the tree is a cladogram (i.e. no branch lengths) Returns : BOOLEAN Args : NONE Comments:
CALCULATIONS
 calc_branch_length_distance()

Calculates the Euclidean branch length distance between two trees. See Kuhner & Felsenstein (1994). A simulation comparison of phylogeny algorithms under equal and unequal evolutionary rates. MBE 11(3):459468.
Type : Calculation Title : calc_branch_length_distance Usage : my $distance = $tree1>calc_branch_length_distance($tree2); Function: Calculates the Euclidean branch length distance between two trees Returns : SCALAR, number Args : NONE
 calc_branch_length_score()

Calculates the squared Euclidean branch length distance between two trees.
Type : Calculation Title : calc_branch_length_score Usage : my $score = $tree1>calc_branch_length_score($tree2); Function: Calculates the squared Euclidean branch length distance between two trees Returns : SCALAR, number Args : A Bio::Phylo::Forest::Tree object, Optional second argument flags that results should be normalized
 calc_tree_length()

Calculates the sum of all branch lengths.
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()

Calculates the height of the tree.
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 roottotip path lengths, so for additive trees the result should consequently be interpreted differently.
 calc_number_of_nodes()

Calculates the 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()

Calculates the number of terminal nodes.
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()

Calculates the number of internal nodes.
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_number_of_cherries()

Calculates the number of cherries, i.e. the number of nodes that subtend exactly two tips. See for applications of this metric: http://dx.doi.org/10.1016/S00255564(99)000607
Type : Calculation Title : calc_number_of_cherries Usage : my $number_of_cherries = $tree>calc_number_of_cherries; Function: Calculates the number of cherries Returns : INT Args : NONE
 calc_total_paths()

Calculates the sum of all roottotip path lengths.
Type : Calculation Title : calc_total_paths Usage : my $total_paths = $tree>calc_total_paths; Function: Calculates the sum of all roottotip path lengths. Returns : FLOAT Args : NONE
 calc_redundancy()

Calculates the amount of shared (redundant) history on the total.
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()

Calculates Colless' coefficient of tree 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): 100104
 calc_i2()

Calculates I2 imbalance.
Type : Calculation Title : calc_i2 Usage : my $ci2 = $tree>calc_i2; Function: Calculates I2 imbalance. Returns : FLOAT Args : NONE Comments:
 calc_gamma()

Calculates the Pybus & Harvey (2000) gamma statistic.
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 macroevolutionary models using incomplete molecular phylogenies. Proc. R. Soc. Lond. B 267, 22672272
 calc_fiala_stemminess()

Calculates stemminess measure of Fiala and Sokal (1985).
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: 609622
 calc_rohlf_stemminess()

Calculates stemminess measure from Rohlf et al. (1990).
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): 16711684
 calc_resolution()

Calculates tree resolution.
Type : Calculation Title : calc_resolution Usage : my $resolution = $tree>calc_resolution; Function: Calculates the 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()

Calculates cumulative branching times.
Type : Calculation Title : calc_branching_times Usage : my $branching_times = $tree>calc_branching_times; Function: Returns a twodimensional 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_waiting_times()

Calculates intervals between splits.
Type : Calculation Title : calc_waiting_times Usage : my $waitings = $tree>calc_waiting_times; Function: Returns a twodimensional 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 waiting 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_node_ages()

Calculates node ages.
Type : Calculation Title : calc_node_ages Usage : $tree>calc_node_ages; Function: Calculates the age of all the nodes in the tree (i.e. the distance from the tips) and assigns these to the 'age' slot, such that, after calling this method, the age of any one node can be retrieved by calling $node>get_generic('age'); Returns : The invocant Args : NONE Comments: This method computes, in a sense, the opposite of calc_branching_times: here, we compute the distance from the tips (i.e. how long ago the split occurred), whereas calc_branching_times calculates the distance from the root.
 calc_ltt()

Calculates lineagethroughtime data points.
Type : Calculation Title : calc_ltt Usage : my $ltt = $tree>calc_ltt; Function: Returns a twodimensional 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()

Calculates the symmetric difference metric between invocant and argument. This metric is identical to the RobinsonFoulds tree comparison distance. See http://dx.doi.org/10.1016/00255564(81)900432
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, Optional second argument flags that results should be normalized Comments: Trees in comparison must span the same set of terminal taxa or results are meaningless.
 calc_avtd()

Calculates the average taxonomic distinctiveness. See Clarke KR, Warwick RM (1998) A taxonomic distinctness index and its statistical properties. J Appl Ecol 35:523525 http://dx.doi.org/10.1046/j.13652664.1998.3540523.x
Type : Calculation Title : calc_avtd Usage : my $avtd = $tree>calc_avtd; Function: Returns the average taxonomic distinctiveness Returns : SCALAR Args : A Bio::Phylo::Forest::Tree object Comments:
 calc_fp()

Calculates the Fair Proportion value for each terminal.
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_fp_mean()

Calculates the mean Fair Proportion value over all terminals.
Type : Calculation Title : calc_fp_mean Usage : my $fp = $tree>calc_fp_mean(); Function: Returns the mean Fair Proportion value over all terminals Returns : FLOAT Args : NONE
 calc_es()

Calculates the Equal Splits value for each terminal
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_es_mean()

Calculates the mean Equal Splits value over all terminals
Type : Calculation Title : calc_es_mean Usage : my $es = $tree>calc_es_mean(); Function: Returns the Equal Splits value over all terminals Returns : FLOAT Args : NONE
 calc_pe()

Calculates the Pendant Edge value for each terminal.
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_pe_mean()

Calculates the mean Pendant Edge value over all terminals
Type : Calculation Title : calc_pe_mean Usage : my $es = $tree>calc_pe_mean(); Function: Returns the mean Pendant Edge value over all terminals Returns : FLOAT Args : NONE
 calc_shapley()

Calculates the Shapley value for each terminal.
Type : Calculation Title : calc_shapley Usage : my $es = $tree>calc_shapley(); Function: Returns the Shapley value for each terminal Returns : HASHREF Args : NONE
 calc_shapley_mean()

Calculates the mean Shapley value over all terminals
Type : Calculation Title : calc_shapley_mean Usage : my $es = $tree>calc_shapley_mean(); Function: Returns the mean Shapley value over all terminals Returns : HASHREF Args : NONE
VISITOR METHODS
The following methods are a  not entirely truetoform  implementation of the Visitor design pattern: the nodes in a tree are visited, and rather than having an object operate on them, a set of code references is used. This can be used, for example, to serialize a tree to a string format. To create a newick string without branch lengths you would use something like this (there is a more powerful 'to_newick' method, so this is just an example):
$tree>visit_depth_first(
'pre_daughter' => sub { print '(' },
'post_daughter' => sub { print ')' },
'in' => sub { print shift>get_name },
'pre_sister' => sub { print ',' },
);
print ';';
 visit_depth_first()

Visits nodes depth first
Type : Visitor method Title : visit_depth_first Usage : $tree>visit_depth_first( pre => sub{ ... }, post => sub { ... } ); Function: Visits nodes in a depth first traversal, executes subs Returns : $tree Args : Optional handlers in the order in which they would be executed on an internal node: # first event handler, is executed when node is reached in recursion pre => sub { print "pre: ", shift>get_name, "\n" }, # is executed if node has a daughter, but before that daughter is processed pre_daughter => sub { print "pre_daughter: ", shift>get_name, "\n" }, # is executed if node has a daughter, after daughter has been processed post_daughter => sub { print "post_daughter: ", shift>get_name, "\n" }, # is executed whether or not node has sisters, if it does have sisters # they're processed first in => sub { print "in: ", shift>get_name, "\n" }, # is executed if node has a sister, before sister is processed pre_sister => sub { print "pre_sister: ", shift>get_name, "\n" }, # is executed if node has a sister, after sister is processed post_sister => sub { print "post_sister: ", shift>get_name, "\n" }, # is executed last post => sub { print "post: ", shift>get_name, "\n" }, # specifies traversal order, default 'ltr' means first_daugher > next_sister # traversal, alternate value 'rtl' means last_daughter > previous_sister traversal order => 'ltr', # ltr = lefttoright, 'rtl' = righttoleft Comments:
 visit_breadth_first()

Visits nodes breadth first
Type : Visitor method Title : visit_breadth_first Usage : $tree>visit_breadth_first( pre => sub{ ... }, post => sub { ... } ); Function: Visits nodes in a breadth first traversal, executes handlers Returns : $tree Args : Optional handlers in the order in which they would be executed on an internal node: # first event handler, is executed when node is reached in recursion pre => sub { print "pre: ", shift>get_name, "\n" }, # is executed if node has a sister, before sister is processed pre_sister => sub { print "pre_sister: ", shift>get_name, "\n" }, # is executed if node has a sister, after sister is processed post_sister => sub { print "post_sister: ", shift>get_name, "\n" }, # is executed whether or not node has sisters, if it does have sisters # they're processed first in => sub { print "in: ", shift>get_name, "\n" }, # is executed if node has a daughter, but before that daughter is processed pre_daughter => sub { print "pre_daughter: ", shift>get_name, "\n" }, # is executed if node has a daughter, after daughter has been processed post_daughter => sub { print "post_daughter: ", shift>get_name, "\n" }, # is executed last post => sub { print "post: ", shift>get_name, "\n" }, # specifies traversal order, default 'ltr' means first_daugher > next_sister # traversal, alternate value 'rtl' means last_daughter > previous_sister traversal order => 'ltr', # ltr = lefttoright, 'rtl' = righttoleft Comments:
 visit_level_order()

Visits nodes in a level order traversal.
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:
TREE MANIPULATION
 chronompl()

Modifies branch lengths using the mean path lengths method of Britton et al. (2002). For more about this method, see: http://dx.doi.org/10.1016/S10557903(02)002683
Type : Tree manipulator Title : chronompl Usage : $tree>chronompl; Function: Makes tree ultrametric using MPL method Returns : The modified, now ultrametric invocant. Args : NONE Comments:
 grafenbl()

Computes and assigns branch lengths using Grafen's method, which makes node ages proportional to clade size. For more about this method, see: http://dx.doi.org/10.1098/rstb.1989.0106
Type : Tree manipulator Title : grafenbl Usage : $tree>grafenbl; Function: Assigns branch lengths using Grafen's method Returns : The modified, now ultrametric invocant. Args : Optional, a power ('rho') to which all node ages are raised Comments:
 agetobl()

Converts node ages to branch lengths
Type : Tree manipulator Title : agetobl Usage : $tree>agetobl; Function: Converts node ages to branch lengths Returns : The modified invocant. Args : NONE Comments: This method uses ages as assigned to the generic 'age' slot on the nodes in the trees. I.e. for each node in the tree, $node>get_generic('age') must return a number
 rankprobbl()

Generates branch lengths by calculating the rank probabilities for each node and applying the expected waiting times under a pure birth process to these ranks. Uses Stadler's RANKPROB algorithm as described in:
Gernhard, T. et al., 2006. Estimating the relative order of speciation or coalescence events on a given phylogeny. Evolutionary Bioinformatics Online. 2:285. http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2674681/.
Type : Tree manipulator Title : rankprobbl Usage : $tree>rankprobbl; Function: Generates pure birth branch lengths Returns : The modified invocant. Args : NONE Comments: Tree must be fully bifurcating
 ultrametricize()

Sets all roottotip path lengths equal.
Type : Tree manipulator Title : ultrametricize Usage : $tree>ultrametricize; Function: Sets all roottotip 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()

Scales the tree to the specified height.
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 roottotip path length. Comments: This method uses the $tree>calc_tree_height method, and so for additive trees the *average* roottotip path length is scaled to $height (i.e. some nodes might be taller than $height, others shorter).
 resolve()

Randomly breaks polytomies.
Type : Tree manipulator Title : resolve Usage : $tree>resolve; Function: Randomly breaks polytomies by inserting additional internal nodes. Returns : The modified invocant. Args : Optionally, when passed a true value (e.g. '1'), the newly created nodes will be unnamed, otherwise they will be named 'r1', 'r2', 'r3' and so on. Comments:
 replicate()

Simulates tree(s) whose properties resemble that of the input tree in terms of birth/death rate, depth, and size/depth distribution of genera. This uses the R environment for statistics to get a maximum likelihood estimate of birth/death rates on the source tree and therefore requires the package Statistics::R to be installed, and the R package 'ape'. The idea is that this is used on a species tree that is ultrametric. To get simulated genera whose sizes and root depths approximate those of the source tree, annotate genus nodes in the source tree, e.g. using $tree>generize, and provide the optional genera flag of replicate() with a true value.
This method uses the function
birthdeath
from the R packageape
. If you use this method in a publication, you should therefore cite that package (in addition to Bio::Phylo). More information aboutape
can be found at http://apepackage.ird.fr/.Type : Tree manipulator Title : replicate Usage : my $forest = $tree>replicate; Function: Simulates tree(s) whose properties resemble that of the invocant tree Returns : Bio::Phylo::Forest Args : Optional: trees => number of replicates, default is 1 Optional: rootedge => keep the birth/death root branch, then scale the tree(s) Optional: genera => approximate distribution of source genus sizes and depths (do this by tagging internal nodes: $node>set_rank('genus')) Optional: seed => a random integer seed for generating the birth/death tree Comments: Requires Statistics::R, and an R environment with 'ape' installed Expects to operate on an ultrametric tree
 generize()

Identifies monophyletic genera by traversing the tree, taking the first word of the tip names and finding the MRCA of each word. That MRCA is tagged as rank 'genus' and assigned the name.
Type : Tree manipulator Title : generize Usage : $tree>generize(%args); Function: Identifies monophyletic genera Returns : Invocant Args : Optional: delim => the delimiter that separates the genus name from any following (sub)specific epithets. Default is a space ' '. Optional: monotypic => if true, also tags monotypic genera Optional: polypara => if true, also tags poly/paraphyletic genera. Any putative genera nested within the largest of the entangled, poly/paraphyletic genera will be ignored. Comments:
 prune_tips()

Prunes argument nodes from invocant.
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, or a taxa block, or a reference to an array of taxon objects, or a reference to an array of node objects Comments:
 keep_tips()

Keeps argument nodes from invocant (i.e. prunes all others).
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 : Same as prune_tips, but with inverted meaning Comments:
 negative_to_zero()

Converts negative branch lengths 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:
 ladderize()

Sorts nodes in ascending (or descending) order of number of children. Tips are sorted alphabetically (ascending or descending) relative to their siblings.
Type : Tree manipulator Title : ladderize Usage : $tree>ladderize(1); Function: Sorts nodes Returns : The modified invocant. Args : Optional, a true value to reverse the sort order
 sort_tips()

Sorts nodes in (an approximation of) the provided ordering. Given an array reference of taxa, an array reference of name strings, or a taxa object, this method attempts to order the tips in the same way. It does this by recursively computing the rank for all internal nodes by taking the average rank of its children. This results in the following orderings:
(a,b,c,d,e,f); => $tree>sort_tips( [ qw(a c b f d e) ] ) => (a,c,b,f,d,e); (a,b,(c,d),e,f); => $tree>sort_tips( [ qw(a b e d c f) ] ); => (a,b,(e,(d,c)),f); ((a,b),((c,d),e),f); => $tree>sort_tips( [ qw(a e d c b f) ] ); => ((e,(d,c)),(a,b),f); Type : Tree manipulator Title : sort_tips Usage : $tree>sort_tips($ordering); Function: Sorts nodes Returns : The modified invocant. Args : Required, an array reference (or taxa object) whose ordering to match
 exponentiate()

Raises branch lengths to argument.
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.
 multiply()

Multiples branch lengths by argument.
Type : Tree manipulator Title : multiply Usage : $tree>multiply($num); Function: Multiplies branch lengths by $num. Returns : The modified invocant. Args : A $number in any of perl's number formats.
 log_transform()

Log argument base transform branch lengths.
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()

Collapses internal nodes with fewer than 2 children.
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:
 remove_orphans()

Removes all unconnected nodes.
Type : Tree manipulator Title : remove_orphans Usage : $tree>remove_orphans; Function: Removes all unconnected nodes Returns : The modified invocant. Args : NONE Comments:
 deroot()

Collapses one of the children of a basal bifurcation
Type : Tree manipulator Title : deroot Usage : $tree>deroot; Function: Removes root Returns : The modified invocant. Args : Optional: node to collapse Comments:
UTILITY METHODS
 clone()

Clones invocant.
Type : Utility method Title : clone Usage : my $clone = $object>clone; Function: Creates a copy of the invocant object. Returns : A copy of the invocant. Args : Optional: a hash of code references to override reflectionbased getter/setter copying my $clone = $object>clone( 'set_forest' => sub { my ( $self, $clone ) = @_; for my $forest ( @{ $self>get_forests } ) { $clone>set_forest( $forest ); } }, 'set_matrix' => sub { my ( $self, $clone ) = @_; for my $matrix ( @{ $self>get_matrices } ) { $clone>set_matrix( $matrix ); } ); Comments: Cloning is currently experimental, use with caution. It works on the assumption that the output of get_foo called on the invocant is to be provided as argument to set_foo on the clone  such as $clone>set_name( $self>get_name ). Sometimes this doesn't work, for example where this symmetry doesn't exist, or where the return value of get_foo isn't valid input for set_foo. If such a copy fails, a warning is emitted. To make sure all relevant attributes are copied into the clone, additional code references can be provided, as in the example above. Typically, this is done by overrides of this method in child classes.
SERIALIZERS
 to_nexus()

Serializes invocant to nexus string.
Type : Stringifier Title : to_nexus Usage : my $string = $tree>to_nexus; Function: Turns the invocant tree object into a nexus string Returns : SCALAR Args : Any arguments that can be passed to Bio::Phylo::Forest::to_nexus
 to_newick()

Serializes invocant to newick string.
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_xml()

Serializes invocant to xml.
Type : Serializer Title : to_xml Usage : my $xml = $obj>to_xml; Function: Turns the invocant object into an XML string. Returns : SCALAR Args : NONE
 to_svg()

Serializes invocant to SVG.
Type : Serializer Title : to_svg Usage : my $svg = $obj>to_svg; Function: Turns the invocant object into an SVG string. Returns : SCALAR Args : Same args as the Bio::Phylo::Treedrawer constructor Notes : This will only work if you have the SVG module from CPAN installed on your system.
 to_dom()

Type : Serializer Title : to_dom Usage : $tree>to_dom($dom) Function: Generates a DOM subtree from the invocant and its contained objects Returns : an Element object Args : DOM factory object
SEE ALSO
There is a mailing list at https://groups.google.com/forum/#!forum/biophylo for any user or developer questions and discussions.
 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::Phylo::Manual

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com.
CITATION
If you use Bio::Phylo in published research, please cite it:
Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo  phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/147121051263