.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Bio::Tree::Statistics 3pm" .TH Bio::Tree::Statistics 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::Tree::Statistics \- Calculate certain statistics for a Tree .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Bio::Tree::Statistics; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This should be where Tree statistics are calculated. It was previously where statistics from a Coalescent simulation. .PP It now contains several methods for calculating Tree-Trait statistics. .SH "FEEDBACK" .IX Header "FEEDBACK" .SS "Mailing Lists" .IX Subsection "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. .PP .Vb 2 \& bioperl\-l@bioperl.org \- General discussion \& http://bioperl.org/wiki/Mailing_lists \- About the mailing lists .Ve .SS "Support" .IX Subsection "Support" Please direct usage questions or support issues to the mailing list: .PP \&\fIbioperl\-l@bioperl.org\fR .PP 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. .SS "Reporting Bugs" .IX Subsection "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: .PP .Vb 1 \& https://github.com/bioperl/bioperl\-live/issues .Ve .SH "AUTHOR \- Jason Stajich" .IX Header "AUTHOR - Jason Stajich" Email jason \s-1AT\s0 bioperl.org .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Heikki Lehvaslaiho, heikki at bioperl dot org .SH "APPENDIX" .IX Header "APPENDIX" The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ .SS "new" .IX Subsection "new" .Vb 5 \& Title : new \& Usage : my $obj = Bio::Tree::Statistics\->new(); \& Function: Builds a new Bio::Tree::Statistics object \& Returns : Bio::Tree::Statistics \& Args : .Ve .SS "assess_bootstrap" .IX Subsection "assess_bootstrap" .Vb 7 \& Title : assess_bootstrap \& Usage : my $tree_with_bs = $stats\->assess_bootstrap(\e@bs_trees,$guide_tree); \& Function: Calculates the bootstrap for internal nodes based on the percentage \& of times \e@bs_trees agree with each internal node \& Returns : L \& Args : Arrayref of Ls \& Guide tree, Ls .Ve .SS "transfer_bootstrap_expectation" .IX Subsection "transfer_bootstrap_expectation" .Vb 8 \& Title : transfer_bootstrap_expectation \& Usage : my $tree_with_bs = $stats\->transfer_bootstrap_expectation(\e@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 \& Args : Arrayref of Ls \& Guide tree, Ls .Ve .SS "cherries" .IX Subsection "cherries" .Vb 7 \& 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 .Ve .PP Commonly used statistics assume a binary tree, but this methods returns a value even for trees with polytomies. .SS "Tree-Trait statistics" .IX Subsection "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. .PP Trees have method \fBadd_traits()\fR to set trait values from a file. See the \&\fBadd_trait()\fR method in Bio::Tree::TreeFunctionsI. .SS "fitch" .IX Subsection "fitch" .Vb 10 \& 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 .Ve .PP Runs first fitch_up that calculates parsimony scores and then fitch_down that should resolve most of the trait/character state ambiguities. .PP Fitch, W.M., 1971. Toward defining the course of evolution: minimal change for a specific tree topology. Syst. Zool. 20, 406\-416. .PP You can access calculated parsimony values using: .PP .Vb 1 \& $score = $node\->\->get_tag_values(\*(Aqps_score\*(Aq); .Ve .PP and the trait value with: .PP .Vb 2 \& $traitvalue = $node\->\->get_tag_values(\*(Aqps_trait\*(Aq); # only the first \& @traitvalues = $node\->\->get_tag_values(\*(Aqps_trait\*(Aq); .Ve .PP Note that there can be more that one trait value, especially for the root node. .SS "ps" .IX Subsection "ps" .Vb 10 \& 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 .Ve .PP 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. .SS "fitch_up" .IX Subsection "fitch_up" .Vb 10 \& 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 .Ve .PP 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. .SS "fitch_down" .IX Subsection "fitch_down" .Vb 10 \& 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 .Ve .PP 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. .SS "persistence" .IX Subsection "persistence" .Vb 8 \& 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 .Ve .PP 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. .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "count_subclusters" .IX Subsection "count_subclusters" .Vb 8 \& 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 .Ve .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "count_leaves" .IX Subsection "count_leaves" .Vb 9 \& 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 .Ve .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "phylotype_length" .IX Subsection "phylotype_length" .Vb 8 \& 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 .Ve .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "sum_of_leaf_distances" .IX Subsection "sum_of_leaf_distances" .Vb 8 \& 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 .Ve .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "genetic_diversity" .IX Subsection "genetic_diversity" .Vb 8 \& 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 .Ve .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "statratio" .IX Subsection "statratio" .Vb 7 \& Example : statratio($tree, $node); \& Description: Ratio of the stem length and the genetic diversity of the \& phylotype L \& 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 .Ve .PP Statratio gives a measure of separation and variability within the phylotype. Larger values identify more rapidly evolving and recent phylotypes. .PP Depends on Fitch's parsimony score (\s-1PS\s0). .SS "ai" .IX Subsection "ai" .Vb 9 \& 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= 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. .Ve .SS "mc" .IX Subsection "mc" .Vb 9 \& 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= MC E= 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. .Ve