Provided by: libbio-perl-perl_1.7.8-1_all bug

NAME

       Bio::Tree::Statistics - Calculate certain statistics for a Tree

SYNOPSIS

         use Bio::Tree::Statistics;

DESCRIPTION

       This should be where Tree statistics are calculated.  It was previously where statistics
       from a Coalescent simulation.

       It now contains several methods for calculating Tree-Trait statistics.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Jason Stajich

       Email jason AT bioperl.org

CONTRIBUTORS

       Heikki Lehvaslaiho, heikki at bioperl dot org

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $obj = Bio::Tree::Statistics->new();
        Function: Builds a new Bio::Tree::Statistics object
        Returns : Bio::Tree::Statistics
        Args    :

   assess_bootstrap
        Title   : assess_bootstrap
        Usage   : my $tree_with_bs = $stats->assess_bootstrap(\@bs_trees,$guide_tree);
        Function: Calculates the bootstrap for internal nodes based on the percentage
                  of times \@bs_trees agree with each internal node
        Returns : L<Bio::Tree::TreeI>
        Args    : Arrayref of L<Bio::Tree::TreeI>s
                  Guide tree, L<Bio::Tree::TreeI>s

   transfer_bootstrap_expectation
        Title   : transfer_bootstrap_expectation
        Usage   : my $tree_with_bs = $stats->transfer_bootstrap_expectation(\@bs_trees,$guide_tree);
        Function: Calculates the Transfer Bootstrap Expectation (TBE) for internal nodes based on
                  the methods outlined in Lemoine et al, Nature, 2018.
                  Currently experimental.
        Returns : L<Bio::Tree::TreeI>
        Args    : Arrayref of L<Bio::Tree::TreeI>s
                  Guide tree, L<Bio::Tree::TreeI>s

   cherries
         Example    : cherries($tree, $node);
         Description: Count number of paired leaf nodes
                      in a binary tree
         Returns    : integer
         Exceptions :
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Commonly used statistics assume a binary tree, but this methods returns a value even for
       trees with polytomies.

   Tree-Trait statistics
       The following methods produce descriptors of trait distribution among leaf nodes within
       the trees. They require that a trait has been set for each leaf node. The tag methods of
       Bio::Tree::Node are used to store them as key/value pairs. In this way, one tree can store
       more than one trait.

       Trees have method add_traits() to set trait values from a file. See the add_trait() method
       in Bio::Tree::TreeFunctionsI.

   fitch
         Example    : fitch($tree, $key, $node);
         Description: Calculates Parsimony Score (PS) and internal trait
                      values using the Fitch 1971 parsimony algorithm for
                      the subtree a defined by the (internal) node.
                      Node defaults to the root.
         Returns    : true on success
         Exceptions : leaf nodes have to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. trait name string
                      3. Bio::Tree::NodeI object within the tree, optional

       Runs first fitch_up that calculates parsimony scores and then fitch_down that should
       resolve most of the trait/character state ambiguities.

       Fitch, W.M., 1971. Toward defining the course of evolution: minimal change for a specific
       tree topology. Syst. Zool. 20, 406-416.

       You can access calculated parsimony values using:

         $score = $node->->get_tag_values('ps_score');

       and the trait value with:

         $traitvalue = $node->->get_tag_values('ps_trait'); # only the first
         @traitvalues = $node->->get_tag_values('ps_trait');

       Note that there can be more that one trait value, especially for the root node.

   ps
         Example    : ps($tree, $key, $node);
         Description: Calculates Parsimony Score (PS) from Fitch 1971
                      parsimony algorithm for the subtree as defined
                      by the (internal) node.
                      Node defaults to the root.
         Returns    : integer, 1 < PS < n, where n is number of branches
         Exceptions : leaf nodes have to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. trait name string
                      3. Bio::Tree::NodeI object within the tree, optional

       This is the first half of the Fitch algorithm that is enough for calculating the resolved
       parsimony values. The trait/chararacter states are commonly left in ambiguous state. To
       resolve them, run fitch_down.

   fitch_up
         Example    : fitch_up($tree, $key, $node);
         Description: Calculates Parsimony Score (PS) from the Fitch 1971
                      parsimony algorithm for the subtree as defined
                      by the (internal) node.
                      Node defaults to the root.
         Returns    : integer, 1< PS < n, where n is number of branches
         Exceptions : leaf nodes have to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. trait name string
                      3. Bio::Tree::NodeI object within the tree, optional

       This is a more generic name for ps and indicates that it performs the first bottom-up tree
       traversal that calculates the parsimony score but usually leaves trait/character states
       ambiguous. If you are interested in internal trait states, running fitch_down should
       resolve most of the ambiguities.

   fitch_down
         Example    : fitch_down($tree, $node);
         Description: Runs the second pass from Fitch 1971
                      parsimony algorithm to resolve ambiguous
                      trait states left by first pass.
                      by the (internal) node.
                      Node defaults to the root.
         Returns    : true
         Exceptions : dies unless the trait is defined in all nodes
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Before running this method you should have ran fitch_up (alias to ps ). Note that it is
       not guaranteed that all states are completely resolved.

   persistence
         Example    : persistence($tree, $node);
         Description: Calculates the persistence
                      for node in the subtree defined by the (internal)
                      node.  Node defaults to the root.
         Returns    : int, number of generations trait value has to remain same
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Persistence measures the stability that the trait value has in a tree. It expresses the
       number of generations the trait value remains the same. All the decendants of the root in
       the same generation have to share the same value.

       Depends on Fitch's parsimony score (PS).

   count_subclusters
         Example    : count_clusters($tree, $node);
         Description: Calculates the number of sub-clusters
                      in the subtree defined by the (internal)
                      node.  Node defaults to the root.
         Returns    : int, count
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Depends on Fitch's parsimony score (PS).

   count_leaves
         Example    : count_leaves($tree, $node);
         Description: Calculates the number of leaves with same trait
                      value as root in the subtree defined by the (internal)
                      node.  Requires an unbroken line of identical trait values.
                      Node defaults to the root.
         Returns    : int, number of leaves with this trait value
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Depends on Fitch's parsimony score (PS).

   phylotype_length
         Example    : phylotype_length($tree, $node);
         Description: Sums up the branch lengths within phylotype
                      excluding the subclusters where the trait values
                      are different
         Returns    : float, length
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Depends on Fitch's parsimony score (PS).

   sum_of_leaf_distances
         Example    : sum_of_leaf_distances($tree, $node);
         Description: Sums up the branch lengths from root to leaf
                      excluding the subclusters where the trait values
                      are different
         Returns    : float, length
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Depends on Fitch's parsimony score (PS).

   genetic_diversity
         Example    : genetic_diversity($tree, $node);
         Description: Diversity is the sum of root to leaf distances
                      within the phylotype normalised by number of leaf
                      nodes
         Returns    : float, value of genetic diversity
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Depends on Fitch's parsimony score (PS).

   statratio
         Example    : statratio($tree, $node);
         Description: Ratio of the stem length and the genetic diversity of the
                      phylotype L<genetic_diversity>
         Returns    : float, separation score
         Exceptions : all the  nodes need to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. Bio::Tree::NodeI object within the tree, optional

       Statratio gives a measure of separation and variability within the phylotype.  Larger
       values identify more rapidly evolving and recent phylotypes.

       Depends on Fitch's parsimony score (PS).

   ai
         Example    : ai($tree, $key, $node);
         Description: Calculates the Association Index (AI) of Whang et
                      al. 2001 for the subtree defined by the (internal)
                      node.  Node defaults to the root.
         Returns    : real
         Exceptions : leaf nodes have to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. trait name string
                      3. Bio::Tree::NodeI object within the tree, optional

         Association index (AI) gives a more fine grained results than PS since
         the result is a real number. ~0 E<lt>= AI.

         Wang, T.H., Donaldson, Y.K., Brettle, R.P., Bell, J.E., Simmonds, P.,
         2001.  Identification of shared populations of human immunodeficiency
         Virus Type 1 infecting microglia and tissue macrophages outside the
         central nervous system. J. Virol. 75 (23), 11686-11699.

   mc
         Example    : mc($tree, $key, $node);
         Description: Calculates the Monophyletic Clade (MC) size statistics
                      for the subtree a defined by the (internal) node.
                      Node defaults to the root;
         Returns    : hashref with trait values as keys
         Exceptions : leaf nodes have to have the trait defined
         Args       : 1. Bio::Tree::TreeI object
                      2. trait name string
                      3. Bio::Tree::NodeI object within the tree, optional

         Monophyletic Clade (MC) size statistics by Salemi at al 2005. It is
         calculated for each trait value. 1 E<lt>= MC E<lt>= nx, where nx is the
         number of tips with value x:

          pick the internal node with maximim value for
             number of of tips with only trait x

         MC was defined by Parker et al 2008.

         Salemi, M., Lamers, S.L., Yu, S., de Oliveira, T., Fitch, W.M., McGrath, M.S.,
          2005. Phylodynamic analysis of Human Immunodeficiency Virus Type 1 in
          distinct brain compartments provides a model for the neuropathogenesis of
          AIDS. J. Virol. 79 (17), 11343-11352.

         Parker, J., Rambaut A., Pybus O., 2008. Correlating viral phenotypes
          with phylogeny: Accounting for phylogenetic uncertainty Infection,
          Genetics and Evolution 8 (2008), 239-246.