The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Bio-Phylo-0.05
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Forest::Tree

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

CONSTRUCTOR

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.

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_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_binary()
 Type    : Test
 Title   : is_binary
 Usage   : if ( $tree->is_binary ) {
              # do something
           }
 Function: Tests whether the current Bio::Phylo::Forest::Tree 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 Bio::Phylo::Forest::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()
 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_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.

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 Bio::Phylo::Forest::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()
 Type    : Tree manipulator
 Title   : scale
 Usage   : $tree->scale($height);
 Function: Scales the tree to the specified height.
 Returns : The modified Bio::Phylo::Forest::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 : The modified Bio::Phylo::Forest::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::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    : A list of taxon names.
 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 Bio::Phylo::Forest::Tree object.
 Args    : NONE
 Comments:
exponentiate()
 Type    : Tree manipulator
 Title   : exponentiate
 Usage   : $tree->exponentiate($power);
 Function: Raises branch lengths to $power.
 Returns : The modified Bio::Phylo::Forest::Tree object.
 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 Bio::Phylo::Forest::Tree object.
 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 Bio::Phylo::Forest::Tree object.
 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

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::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,v 1.13 2005/09/29 20:31:17 rvosa Exp $

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.