treesumstats 0.1__tar.gz → 0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. treesumstats-0.2/PKG-INFO +496 -0
  2. treesumstats-0.2/README.md +474 -0
  3. {treesumstats-0.1 → treesumstats-0.2}/setup.py +1 -1
  4. treesumstats-0.1/treesumstats/topology_sumstats.py → treesumstats-0.2/treesumstats/balance_sumstats.py +6 -6
  5. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/branch_sumstats.py +22 -40
  6. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/calculator.py +25 -25
  7. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/event_time_sumstats.py +2 -2
  8. treesumstats-0.2/treesumstats/help.py +37 -0
  9. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/subtree_sumstats.py +4 -4
  10. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/sumstats.py +0 -3
  11. treesumstats-0.2/treesumstats.egg-info/PKG-INFO +496 -0
  12. {treesumstats-0.1 → treesumstats-0.2}/treesumstats.egg-info/SOURCES.txt +2 -1
  13. treesumstats-0.1/PKG-INFO +0 -144
  14. treesumstats-0.1/README.md +0 -122
  15. treesumstats-0.1/treesumstats.egg-info/PKG-INFO +0 -144
  16. {treesumstats-0.1 → treesumstats-0.2}/LICENSE +0 -0
  17. {treesumstats-0.1 → treesumstats-0.2}/setup.cfg +0 -0
  18. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/__init__.py +0 -0
  19. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/basic_sumstats.py +0 -0
  20. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/ltt_sumstats.py +0 -0
  21. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/resolution_sumstats.py +0 -0
  22. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/transmission_chain_sumstats.py +0 -0
  23. {treesumstats-0.1 → treesumstats-0.2}/treesumstats/tree_manager.py +0 -0
  24. {treesumstats-0.1 → treesumstats-0.2}/treesumstats.egg-info/dependency_links.txt +0 -0
  25. {treesumstats-0.1 → treesumstats-0.2}/treesumstats.egg-info/entry_points.txt +0 -0
  26. {treesumstats-0.1 → treesumstats-0.2}/treesumstats.egg-info/requires.txt +0 -0
  27. {treesumstats-0.1 → treesumstats-0.2}/treesumstats.egg-info/top_level.txt +0 -0
@@ -0,0 +1,496 @@
1
+ Metadata-Version: 2.1
2
+ Name: treesumstats
3
+ Version: 0.2
4
+ Summary: Encoding phylogenetic trees with summary statistics.
5
+ Home-page: https://github.com/evolbioinfo/treesumstats
6
+ Author: Anna Zhukova
7
+ Author-email: anna.zhukova@pasteur.fr
8
+ Keywords: phylogenetics,summary statistics,phylogenetic trees,phylogeny
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
13
+ Classifier: Topic :: Software Development
14
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: ete3
18
+ Requires-Dist: numpy==2.0.2
19
+ Requires-Dist: scipy==1.14.1
20
+ Requires-Dist: biopython
21
+ Requires-Dist: pandas==2.2.3
22
+
23
+ # treesumstats
24
+
25
+ Representing phylogenetic trees (or forests of such trees) as summary statistics.
26
+
27
+
28
+
29
+ [//]: # ([![DOI:10.1093/sysbio/syad059](https://zenodo.org/badge/DOI/10.1093/sysbio/syad059.svg)](https://doi.org/10.1093/sysbio/syad059))
30
+ [//]: # ([![GitHub release](https://img.shields.io/github/v/release/evolbioinfo/treesumstats.svg)](https://github.com/evolbioinfo/treesumstats/releases))
31
+ [![PyPI version](https://badge.fury.io/py/treesumstats.svg)](https://pypi.org/project/treesumstats/)
32
+ [![PyPI downloads](https://shields.io/pypi/dm/treesumstats)](https://pypi.org/project/treesumstats/)
33
+ [![Docker pulls](https://img.shields.io/docker/pulls/evolbioinfo/treesumstats)](https://hub.docker.com/r/evolbioinfo/treesumstats/tags)
34
+
35
+ ## Implemented summary statistics
36
+
37
+ ### Basic Tree statistics
38
+ Implemented in [_treesumstats.basic_sumstats.BasicFeatureCalculator_](treesumstats/balance_sumstats.py).
39
+
40
+ 1. **n_trees:** number of trees in the forest.
41
+ 1. **n_tips:** number of tips in the forest.
42
+ 1. **n_inodes:** number of internal nodes in the forest.
43
+ 1. **len_forest:** sum of forest branch lengths.
44
+
45
+ ### Tree resolution statistics
46
+ Implemented in [_treesumstats.resolution_sumstats.ResolutionFeatureCalculator_](treesumstats/resolution_sumstats.py).
47
+
48
+ 1. **n_children_mean:** average of the number of children per internal node of forest trees.
49
+ 1. **n_children_min:** minimum of the number of children per internal node of forest trees.
50
+ 1. **n_children_max:** maximum of the number of children per internal node of forest trees.
51
+ 1. **n_children_var:** variance of the number of children per internal node of forest trees.
52
+ 1. **n_children_median:** median of the number of children per internal node of forest trees.
53
+ 1. **n_inodes_resolved:** number of resolved (i.e., with exactly 2 children) nodes in the forest.
54
+ 1. **n_inodes_resolved_non_zero:** number of resolved (i.e., with exactly 2 children) forest nodes that are either root nodes or have non-zero branch length.
55
+ 1. **frac_inodes_resolved:** fraction of resolved (i.e., with exactly 2 children) nodes in the forest with respect to the number of internal nodes in this forest if all its trees were fully resolved (i.e., binary).
56
+ 1. **frac_inodes_resolved_non_zero:** fraction of resolved (i.e., with exactly 2 children) forest nodes that are either root nodes or have non-zero branch length with respect to the number of internal nodes in this forest if all its trees were fully resolved (i.e., binary).
57
+
58
+ ### Tree balance statistics
59
+ Adapted from [Saulnier et al. 2027](https://doi.org/10.1371/journal.pcbi.1005416), [Colless 1982](https://doi.org/10.2307/2413420), [Sackin 1972](https://doi.org/10.1093/sysbio/21.2.225)
60
+ and [Colijn et al. 2014](https://doi.org/10.1093/emph/eou018).
61
+
62
+ Implemented in [_treesumstats.balance_sumstats.BalanceFeatureCalculator_](treesumstats/balance_sumstats.py).
63
+
64
+ A _forest width_ is defined as the number of nodes that are at the same depth,
65
+ and _node depth_ as the number of branches separating a node from its tree root [[Colijn et al. 2014]](https://doi.org/10.1093/emph/eou018).
66
+
67
+ To normalize balance and depth-related statistics we calculate them on the deepest (and at the same time most unbalanced) forest F_deep with the same numbers of tips (n_tips) and trees (n_trees).
68
+ It contains a ladder tree with (n_tips - n_trees + 1) tips and (n_trees - 1) one-tip trees.
69
+
70
+ To normalize width-related statistics we calculate them on the widest forest F_wide with the same numbers of tips (n_tips) and trees (n_trees).
71
+ It contains n_trees balanced trees with the total number of n_tips tips (distributed as equally as possible among the trees).
72
+
73
+ 1. **colless:** sum (over internal nodes) of absolute differences of numbers of tips in their left and right subtrees [[Colless 1982]](https://doi.org/10.2307/2413420).
74
+ 1. **colless_normalized:** colless value (see above), divided it by the colless value for F_deep: (n_tips - n_trees - 1) (n_tips - n_trees) / 2.
75
+ 1. **sackin:** sum (over tips) of the number of internal nodes separating them from the root [[Sackin 1972]](https://doi.org/10.1093/sysbio/21.2.225).
76
+ 1. **sackin_normalized:** sackin value (see above), divided it the sackin value for F_deep: (n_tips - n_trees) (n_tips - n_trees + 1) / 2 - 1.
77
+ 1. **width_max:** maximum width.
78
+ 1. **width_max_normalized:** maximum width, divided it by the maximum width of F_wide.
79
+ 1. **depth_max:** maximum node depth.
80
+ 1. **depth_max_normalized:** maximum node depth, divided it by the maximum node depth in F_deep: (n_tips - n_trees).
81
+ 1. **width_depth_ratio:** maximum width to maximum depth ratio.
82
+ 1. **width_depth_ratio_normalized:** maximum width to maximum depth ratio, divided it by this ratio for F_wide.
83
+ 1. **width_delta:** maximum width difference between neighbouring depths.
84
+ 1. **width_delta_normalized:** maximum width difference between neighbouring depths, divided it this value for F_wide whose last two layers were reorganised to increase the delta (tips at the last layer were grouped into one ladderized subtree).
85
+ 1. **frac_inodes_in_ladder:** fraction of forest internal nodes that are resolved and have a tip descendant [[Colijn et al. 2014]](https://doi.org/10.1093/emph/eou018).
86
+ 1. **n_inodes_in_ladder:** number of forest internal nodes that are resolved and have a tip descendant.
87
+ 1. **len_ladder_max:** maximum number of connected internal nodes with a single tip descendant.
88
+ 1. **len_ladder_max_normalized:** maximum number of connected internal nodes with a single tip descendant. We calculate it separately on each forest's tree and divide it by the number of tips in that tree. The maximum of these values is then reported.
89
+ 1. **frac_inodes_imbalanced:** fraction of internal nodes that have different number of tips in their smallest and their largest child subtrees.
90
+ 1. **n_inodes_imbalanced:** number of internal nodes that have different number of tips in their smallest and their largest child subtrees.
91
+ 1. **imbalance_avg:** mean ratio of min-to-max subtree sizes over all internal nodes.
92
+
93
+ ### Event time statistics
94
+ Implemented in [_treesumstats.event_time_sumstats.EventTimeFeatureCalculator_](treesumstats/event_time_sumstats.py).
95
+
96
+ 1. **time_tip_mean:** average of the times of forest tips.
97
+ 1. **time_tip_min:** minimum of the times of forest tips.
98
+ 1. **time_tip_max:** maximum of the times of forest tips.
99
+ 1. **time_tip_var:** variance of the times of forest tips.
100
+ 1. **time_tip_median:** median of the times of forest tips.
101
+ 1. **time_inode_mean:** average of the times of forest internal nodes.
102
+ 1. **time_inode_min:** minimum of the times of forest internal nodes.
103
+ 1. **time_inode_max:** maximum of the times of forest internal nodes.
104
+ 1. **time_inode_var:** variance of the times of forest internal nodes.
105
+ 1. **time_inode_median:** median of the times of forest internal nodes.
106
+ 1. **time_tip_normalized_mean:** average of the times of forest tips, divided by the last tip's time.
107
+ 1. **time_tip_normalized_min:** minimum of the times of forest tips, divided by the last tip's time.
108
+ 1. **time_tip_normalized_max:** maximum of the times of forest tips, divided by the last tip's time.
109
+ 1. **time_tip_normalized_var:** variance of the times of forest tips, divided by the last tip's time.
110
+ 1. **time_tip_normalized_median:** median of the times of forest tips, divided by the last tip's time.
111
+ 1. **time_inode_normalized_mean:** average of the times of forest internal nodes, divided by the last tip's time.
112
+ 1. **time_inode_normalized_min:** minimum of the times of forest internal nodes, divided by the last tip's time.
113
+ 1. **time_inode_normalized_max:** maximum of the times of forest internal nodes, divided by the last tip's time.
114
+ 1. **time_inode_normalized_var:** variance of the times of forest internal nodes, divided by the last tip's time.
115
+ 1. **time_inode_normalized_median:** median of the times of forest internal nodes, divided by the last tip's time.
116
+
117
+ ### Branch length statistics
118
+ Adapted from [Saulnier et al. 2027](https://doi.org/10.1371/journal.pcbi.1005416).
119
+
120
+ Implemented in [_treesumstats.branch_sumstats.BranchFeatureCalculator_](treesumstats/branch_sumstats.py).
121
+
122
+ The following statistics include ones calculated on the full forest, but also those calculated on its top, middle or bottom parts.
123
+ The total time between the earliest forest tree start (0) and the time of the last sampled tip (T) is split into three equal parts.
124
+ For each part only the branches finishing within the corresponding time period are considered,
125
+ and their start time is cut to the interval start time for the branches that started before.
126
+
127
+ 1. **brlen_inode_mean:** average of branch lengths of the forest internal nodes.
128
+ 1. **brlen_inode_median:** median of branch lengths of the forest internal nodes.
129
+ 1. **brlen_inode_var:** variance of branch lengths of the forest internal nodes.
130
+ 1. **brlen_tip_mean:** average of branch lengths of the forest tips.
131
+ 1. **brlen_tip_median:** median of branch lengths of the forest tips.
132
+ 1. **brlen_tip_var:** variance of branch lengths of the forest tips.
133
+ 1. **brlen_inode_top_mean:** average of branch lengths of the forest's top internal nodes.
134
+ 1. **brlen_inode_top_median:** median of branch lengths of the forest's top internal nodes.
135
+ 1. **brlen_inode_top_var:** variance of branch lengths of the forest's top internal nodes.
136
+ 1. **brlen_tip_top_mean:** average of branch lengths of the forest's top tips.
137
+ 1. **brlen_tip_top_median:** median of branch lengths of the forest's top tips.
138
+ 1. **brlen_tip_top_var:** variance of branch lengths of the forest's top tips.
139
+ 1. **brlen_inode_middle_mean:** average of branch lengths of the forest's middle internal nodes.
140
+ 1. **brlen_inode_middle_median:** median of branch lengths of the forest's middle internal nodes.
141
+ 1. **brlen_inode_middle_var:** variance of branch lengths of the forest's middle internal nodes.
142
+ 1. **brlen_tip_middle_mean:** average of branch lengths of the forest's middle tips.
143
+ 1. **brlen_tip_middle_median:** median of branch lengths of the forest's middle tips.
144
+ 1. **brlen_tip_middle_var:** variance of branch lengths of the forest's middle tips.
145
+ 1. **brlen_inode_bottom_mean:** average of branch lengths of the forest's bottom internal nodes.
146
+ 1. **brlen_inode_bottom_median:** median of branch lengths of the forest's bottom internal nodes.
147
+ 1. **brlen_inode_bottom_var:** variance of branch lengths of the forest's bottom internal nodes.
148
+ 1. **brlen_tip_bottom_mean:** average of branch lengths of the forest's bottom tips.
149
+ 1. **brlen_tip_bottom_median:** median of branch lengths of the forest's bottom tips.
150
+ 1. **brlen_tip_bottom_var:** variance of branch lengths of the forest's bottom tips.
151
+ 1. **frac_brlen_inode_mean_by_brlen_tip_mean:** fraction of two values. The dividend is average of branch lengths of the forest internal nodes. The divisor is average of branch lengths of the forest tips.
152
+ 1. **frac_brlen_inode_median_by_brlen_tip_median:** fraction of two values. The dividend is median of branch lengths of the forest internal nodes. The divisor is median of branch lengths of the forest tips.
153
+ 1. **frac_brlen_inode_var_by_brlen_tip_var:** fraction of two values. The dividend is variance of branch lengths of the forest internal nodes. The divisor is variance of branch lengths of the forest tips.
154
+ 1. **frac_brlen_inode_top_mean_by_brlen_tip_top_mean:** fraction of two values. The dividend is average of branch lengths of the forest's top internal nodes. The divisor is average of branch lengths of the forest's top tips.
155
+ 1. **frac_brlen_inode_top_median_by_brlen_tip_top_median:** fraction of two values. The dividend is median of branch lengths of the forest's top internal nodes. The divisor is median of branch lengths of the forest's top tips.
156
+ 1. **frac_brlen_inode_top_var_by_brlen_tip_top_var:** fraction of two values. The dividend is variance of branch lengths of the forest's top internal nodes. The divisor is variance of branch lengths of the forest's top tips.
157
+ 1. **frac_brlen_inode_middle_mean_by_brlen_tip_middle_mean:** fraction of two values. The dividend is average of branch lengths of the forest's middle internal nodes. The divisor is average of branch lengths of the forest's middle tips.
158
+ 1. **frac_brlen_inode_middle_median_by_brlen_tip_middle_median:** fraction of two values. The dividend is median of branch lengths of the forest's middle internal nodes. The divisor is median of branch lengths of the forest's middle tips.
159
+ 1. **frac_brlen_inode_middle_var_by_brlen_tip_middle_var:** fraction of two values. The dividend is variance of branch lengths of the forest's middle internal nodes. The divisor is variance of branch lengths of the forest's middle tips.
160
+ 1. **frac_brlen_inode_bottom_mean_by_brlen_tip_bottom_mean:** fraction of two values. The dividend is average of branch lengths of the forest's bottom internal nodes. The divisor is average of branch lengths of the forest's bottom tips.
161
+ 1. **frac_brlen_inode_bottom_median_by_brlen_tip_bottom_median:** fraction of two values. The dividend is median of branch lengths of the forest's bottom internal nodes. The divisor is median of branch lengths of the forest's bottom tips.
162
+ 1. **frac_brlen_inode_bottom_var_by_brlen_tip_bottom_var:** fraction of two values. The dividend is variance of branch lengths of the forest's bottom internal nodes. The divisor is variance of branch lengths of the forest's bottom tips.
163
+
164
+
165
+ ### Transmission chain statistics
166
+
167
+ Adapted from [Voznica et al. 2022](https://doi.org/10.1038/s41467-022-31511-0).
168
+
169
+
170
+ Implemented in [_treesumstats.transmission_chain_sumstats.TransmissionChainFeatureCalculator_](treesumstats/transmission_chain_sumstats.py).
171
+
172
+ A _k-node transmission chain_ of node i is the shortest k-branch path descending from i.
173
+ By default k=4, but can be adjusted by setting an argument of _treesumstats.TransmissionChainFeatureCalculator(chain_len=4)_.
174
+
175
+ 4. **n_4-chain:** number of 4-node transmission chains.
176
+ 1. **n_4-chain_normalized:** number of 4-node transmission chains, divided by the number of internal nodes.
177
+ 1. **brlen_sum_4-chain_mean:** average of branch length sums of all 4-node transmission chains.
178
+ 1. **brlen_sum_4-chain_min:** minimum of branch length sums of all 4-node transmission chains.
179
+ 1. **brlen_sum_4-chain_max:** maximum of branch length sums of all 4-node transmission chains.
180
+ 1. **brlen_sum_4-chain_var:** variance of branch length sums of all 4-node transmission chains.
181
+ 1. **brlen_sum_4-chain_median:** median of branch length sums of all 4-node transmission chains.
182
+
183
+ 11-18. **brlen_sum_4-chain_percN:** Nth percentile (where N can be 10, 20, 30, 40, 60, 70, 80 or 90) of branch length sums of all 4-node transmission chains.
184
+
185
+
186
+ ### Lineage-Through-Time (LTT) statistics
187
+ Adapted from [Saulnier et al. 2027](https://doi.org/10.1371/journal.pcbi.1005416).
188
+
189
+
190
+ Implemented in [_treesumstats.ltt_sumstats.LTTFeatureCalculator_](treesumstats/ltt_sumstats.py).
191
+
192
+ In the following metrics times t_i (0 ≤ i ≤ 20) are equally distributed between the time of the start of the first tree (t_0 = 0) in the forest and the time of the forest’s last sampled tip (t_20=T).
193
+ The number of such times (by default 20) can be adjusted by setting the argument of _treesumstats.LTTFeatureCalculator(n_coordinates=20)_.
194
+
195
+ Some of the following statistics are calculated on the top, middle or bottom part of the forest:
196
+ The total time between the earliest forest tree start (0) and the time of the last sampled tip (T) is split into three equal parts.
197
+ The top part includes times <= T/3, the middle one > T/3 and <= 2T/3, the bottom part > 2T/3.
198
+
199
+
200
+ 1-20. **ltt_timeN:** T - t_N, where N can be 0, 1, ..., or 19.
201
+
202
+ 21-40. **ltt_treesN:** number of trees present at t_N, where N can be 0, 1, ..., or 19.
203
+
204
+ 41-60. **ltt_lineagesN:** number of lineages present at t_N, where N can be 0, 1, ..., or 19.
205
+
206
+ 61-80. **ltt_lineagesN_normalized:** number of lineages present at t_N (where N can be 0, 1, ..., or 19), divided by the total number of tips in the forest.
207
+
208
+ 81. **time_trees_max:** T - t_tmax, where t_tmax is the time when the maximum number of trees was first achieved.
209
+ 1. **time_trees_max_top:** T - t_tmax, where t_tmax is the time when the maximum number of trees was first achieved in the top part of the forest.
210
+ 1. **time_trees_max_middle:** T - t_tmax, where t_tmax is the time when the maximum number of trees was first achieved in the middle part of the forest.
211
+ 1. **time_trees_max_bottom:** T - t_tmax, where t_tmax is the time when the maximum number of trees was first achieved in the bottom part of the forest.
212
+ 1. **trees_max:** maximum number of trees.
213
+ 1. **trees_max_top:** maximum number of trees in the top part of the forest.
214
+ 1. **trees_max_middle:** maximum number of trees in the middle part of the forest.
215
+ 1. **trees_max_bottom:** maximum number of trees in the bottom part of the forest.
216
+ 1. **time_lineages_max:** T - t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved.
217
+ 1. **time_lineages_max_top:** T - t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest.
218
+ 1. **time_lineages_max_middle:** T - t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest.
219
+ 1. **time_lineages_max_bottom:** T - t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest.
220
+ 1. **lineages_max:** maximum number of lineages.
221
+ 1. **lineages_max_top:** maximum number of lineages in the top part of the forest.
222
+ 1. **lineages_max_middle:** maximum number of lineages in the middle part of the forest.
223
+ 1. **lineages_max_bottom:** maximum number of lineages in the bottom part of the forest.
224
+ 1. **lineages_max_normalized:** maximum number of lineages, divided by the total number of tips in the forest.
225
+ 1. **lineages_max_top_normalized:** maximum number of lineages in the top part of the forest, divided by the total number of tips in the forest.
226
+ 1. **lineages_max_middle_normalized:** maximum number of lineages in the middle part of the forest, divided by the total number of tips in the forest.
227
+ 1. **lineages_max_bottom_normalized:** maximum number of lineages in the bottom part of the forest, divided by the total number of tips in the forest.
228
+ 1. **lineage_start_to_max_slope:** linear slope between the lineages at the first tree start and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved.
229
+ 1. **lineage_stop_to_max_slope:** linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved.
230
+ 1. **lineage_slope_ratio:** ratio between the linear slope between the lineages at the first tree start and t_lmax, and the linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved.
231
+ 1. **lineage_start_to_max_slope_top:** linear slope between the lineages at the first tree start and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest.
232
+ 1. **lineage_stop_to_max_slope_top:** linear slope between the lineages at the t_lmax and T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest.
233
+ 1. **lineage_slope_ratio_top:** ratio between the linear slope between the lineages at the first tree start and t_lmax, and the linear slope between the lineages at the t_lmax and T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest.
234
+ 1. **lineage_start_to_max_slope_middle:** linear slope between the lineages at the T/3 and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest.
235
+ 1. **lineage_stop_to_max_slope_middle:** linear slope between the lineages at the t_lmax and 2T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest.
236
+ 1. **lineage_slope_ratio_middle:** ratio between the linear slope between the lineages at the T/3 and t_lmax, and the linear slope between the lineages at the t_lmax and 2T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest.
237
+ 1. **lineage_start_to_max_slope_bottom:** linear slope between the lineages at the 2T/3 and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest.
238
+ 1. **lineage_stop_to_max_slope_bottom:** linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest.
239
+ 1. **lineage_slope_ratio_bottom:** ratio between the linear slope between the lineages at the 2T/3 and t_lmax, and the linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest.
240
+ 1. **lineage_start_to_max_slope_normalized:** linear slope between the lineages at the first tree start and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved. This slope is divided by the total number of tips in the forest.
241
+ 1. **lineage_stop_to_max_slope_normalized:** linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved. This slope is divided by the total number of tips in the forest.
242
+ 1. **lineage_start_to_max_slope_top_normalized:** linear slope between the lineages at the first tree start and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest. This slope is divided by the total number of tips in the forest.
243
+ 1. **lineage_stop_to_max_slope_top_normalized:** linear slope between the lineages at the t_lmax and T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the top part of the forest. This slope is divided by the total number of tips in the forest.
244
+ 1. **lineage_start_to_max_slope_middle_normalized:** linear slope between the lineages at the T/3 and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest. This slope is divided by the total number of tips in the forest.
245
+ 1. **lineage_stop_to_max_slope_middle_normalized:** linear slope between the lineages at the t_lmax and 2T/3, where t_lmax is the time when the maximum number of lineages was first achieved in the middle part of the forest. This slope is divided by the total number of tips in the forest.
246
+ 1. **lineage_start_to_max_slope_bottom_normalized:** linear slope between the lineages at the 2T/3 and t_lmax, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest. This slope is divided by the total number of tips in the forest.
247
+ 1. **lineage_stop_to_max_slope_bottom_normalized:** linear slope between the lineages at the t_lmax and T, where t_lmax is the time when the maximum number of lineages was first achieved in the bottom part of the forest. This slope is divided by the total number of tips in the forest.
248
+
249
+ ### Tree topology statistics
250
+ Implemented in [_treesumstats.subtree_sumstats.SubtreeFeatureCalculator_](treesumstats/subtree_sumstats.py).
251
+
252
+ In some of the following statistics reshuffled subtrees are mentioned.
253
+ To construct a _reshuffled subtree_ of a certain kind (cherry, triplet, etc.) from a real one we keep one of its (randomly chosen) tips,
254
+ while for each other tip from the real subtree we replace it with a tip, for which:
255
+ (i) the time at the beginning of its branch is as close as possible to the time at the beginning of the real tip's branch,
256
+ (ii) while all the tips in the reshuffled subtree are different and
257
+ (iii) there are no two tips in the reshuffled subtree that used to belong to the same real subtree of this kind
258
+ (unless there were not enough tips, e.g., 8 tips in total and only 2 ladderized quartets in the forest).
259
+
260
+ We consider the following 2-tip, 3-tip and 4-tip subtrees to calculate the summary statistics:
261
+ * 2: cherry
262
+ * 3U: unresolved triplet (3-tip subtree)
263
+ * 3L: resolved (ladderized) triplet
264
+ * 4U: fully unresolved quartet (4-tip subtree)
265
+ * 4U3U1: partially unresolved quartet with an unresolved triplet and a tip as children
266
+ * 4U211: partially unresolved quartet with a cherry and two tips as children
267
+ * 4L: fully resolved ladderized quartet
268
+ * 4B: fully resolved balanced quartet (with two cherries as children)
269
+
270
+ In the following statistics (spanning several list positions) X must be replaced by one of the following values: 2, 3U, 3L, 4U, 4U3U1, 4U211, 4L or 4B.
271
+
272
+ 1-8. **frac_tips_in_X:** fraction of forest tips that are found in subtrees of type X.
273
+ 9. **frac_tips_in_O:** fraction of forest tips that are not part of any subtree of size 2, 3 or 4.
274
+
275
+ 10-17. **n_tips_in_X:** number of forest tips that are found in subtrees of type X.
276
+ 18. **n_tips_in_O:** number of forest tips that are not part of any subtree of size 2, 3 or 4.
277
+
278
+ 19-26. **time_diff_in_X_real_mean:** mean among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
279
+
280
+ 27-34. **time_diff_in_X_real_min:** minimum among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
281
+
282
+ 35-42. **time_diff_in_X_real_max:** maximum among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
283
+
284
+ 43-50. **time_diff_in_X_real_var:** variance among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
285
+
286
+ 51-58. **time_diff_in_X_real_median:** median among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
287
+
288
+ 19-26. **time_diff_in_X_random_mean:** mean among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
289
+
290
+ 27-34. **time_diff_in_X_random_min:** minimum among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
291
+
292
+ 35-42. **time_diff_in_X_random_max:** maximum among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
293
+
294
+ 43-50. **time_diff_in_X_random_var:** variance among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
295
+
296
+ 51-58. **time_diff_in_X_random_median:** median among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
297
+
298
+ 59-122. **time_diff_in_X_real_percN:** Nth percentile (where N can be 1, 5, 10, 25, 75, 90, 95 or 99) among all subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
299
+
300
+ 123-186. **time_diff_in_X_random_percN:** Nth percentile (where N can be 1, 5, 10, 25, 75, 90, 95 or 99) among all reshuffled subtrees of type X in the forest, of average of all tip pair sampling time differences in the subtree.
301
+
302
+ 187-194. **time_diff_in_X_random_vs_real_n_less:** p-value of the sign test checking that for subtrees of type X, their average tip sampling time differences are indistinguishable in real subtrees and in the corresponding reshuffled ones (the alternative hypothesis is that some real ones are smaller).
303
+
304
+
305
+ ## Input data
306
+ One needs to supply a time-scaled phylogenetic tree in newick format.
307
+ If the file contains several trees (one tree per line), it will be considered as a forest.
308
+
309
+ ## Installation and run
310
+
311
+ There are 4 alternative ways to run __treesumstats__ on your computer:
312
+ with [docker](https://www.docker.com/community-edition),
313
+ [apptainer](https://apptainer.org/),
314
+ in Python3, or via command line (requires installation with Python3).
315
+
316
+
317
+
318
+ ### Install and run in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)
319
+
320
+ You could either install python (version 3.9 or higher) system-wide and then install treesumstats via pip:
321
+ ```bash
322
+ sudo apt install -y python3 python3-pip python3-setuptools python3-distutils
323
+ pip3 install treesumstats
324
+ ```
325
+
326
+ or alternatively, you could install python (version 3.9 or higher) and treesumstats via [conda](https://conda.io/docs/) (make sure that conda is installed first).
327
+ Here we will create a conda environment called _phyloenv_:
328
+ ```bash
329
+ conda create --name phyloenv python=3.9
330
+ conda activate phyloenv
331
+ pip install treesumstats
332
+ ```
333
+
334
+
335
+ #### Basic usage in a command line
336
+ If you installed __treesumstats__ in a conda environment (here named _phyloenv_), do not forget to first activate it, e.g.
337
+
338
+ ```bash
339
+ conda activate phyloenv
340
+ ```
341
+
342
+ Run the following command to calculate the summary statistics for an input tree _tree.nwk_ and save them to an output tab-delimited file _stats.tab_.
343
+ (The non-mandatory option _--add_descriptions_ would add a column with statistics descriptions to the output table.)
344
+
345
+ ```bash
346
+ treesumstats_encode --nwk tree.nwk --tab stats.tab --add_descriptions
347
+ ```
348
+
349
+ #### Help
350
+
351
+ To see detailed options, run:
352
+ ```bash
353
+ treesumstats_encode --help
354
+ ```
355
+
356
+
357
+ ### Run with docker
358
+
359
+ #### Basic usage
360
+ Once [docker](https://www.docker.com/community-edition) is installed,
361
+
362
+ run the following command to calculate the summary statistics for an input tree _tree.nwk_ and save them to an output tab-delimited file _stats.tab_.
363
+ (The non-mandatory option _--add_descriptions_ would add a column with statistics descriptions to the output table.)
364
+
365
+
366
+ ```bash
367
+ docker run -v <path_to_the_folder_containing_the_tree>:/data:rw -t evolbioinfo/treesumstats --nwk /data/tree.nwk --tab /data/stats.tab --add_descriptions
368
+ ```
369
+
370
+
371
+ This will produce a tab-delimited file _stats.tab_ in the <path_to_the_folder_containing_the_tree> folder,
372
+
373
+ containing the summary statistic names in the _statistic_ column, their values in the _value_ column and their descriptions in the _description_ column.
374
+
375
+ #### Help
376
+
377
+ To see advanced options, run
378
+ ```bash
379
+ docker run -t evolbioinfo/treesumstats -h
380
+ ```
381
+
382
+
383
+
384
+ ### Run with apptainer
385
+
386
+ #### Basic usage
387
+ Once [apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation) is installed,
388
+
389
+ run the following command to calculate the summary statistics for an input tree _tree.nwk_ and save them to an output tab-delimited file _stats.tab_.
390
+ (The non-mandatory option _--add_descriptions_ would add a column with statistics descriptions to the output table.)
391
+
392
+
393
+ ```bash
394
+ apptainer run docker://evolbioinfo/treesumstats --nwk tree.nwk --tab stats.tab --add_descriptions
395
+ ```
396
+
397
+
398
+ This will produce a tab-delimited file _stats.tab_,
399
+
400
+ containing the summary statistic names in the _statistic_ column, their values in the _value_ column and their descriptions in the _description_ column.
401
+
402
+
403
+ #### Help
404
+
405
+ To see advanced options, run
406
+ ```bash
407
+ apptainer run docker://evolbioinfo/treesumstats -h
408
+ ```
409
+
410
+
411
+ ## How to add your own summary statistics
412
+
413
+ To add your own summary statistics, your need to first of all
414
+ implement a subclass of an abstract class [summarystatics.FeatureCalculator](treesumstats),
415
+ as in the example below, which calculates 2 summary statistics: 'example_feature_1' and 'example_feature_2'.
416
+
417
+ ```python3
418
+ from treesumstats import FeatureCalculator
419
+
420
+
421
+ class ExampleFeatureCalculator(FeatureCalculator):
422
+ """Computes summary statistics based on ..."""
423
+
424
+ def __init__(self):
425
+ self._forest = None
426
+
427
+ def feature_names(self):
428
+ """Returns a list of names of summary statistics that this class can calculate."""
429
+
430
+ return ['example_feature_1', 'example_feature_2']
431
+
432
+ def set_forest(self, forest, **kwargs):
433
+ self._forest = forest
434
+
435
+ def calculate(self, feature_name, **kwargs):
436
+ if 'example_feature_1' == feature_name:
437
+ # your code to calculate this summary statistic value on the forest self._forest
438
+ # should go here
439
+ return 1
440
+ if 'example_feature_2' == feature_name:
441
+ # your code to calculate this summary statistic value on the forest self._forest
442
+ # should go here
443
+ return 2
444
+ return None
445
+
446
+ def help(self, feature_name, *args, **kwargs):
447
+ """Returns a description of the summary statistic whose name is given as the argument."""
448
+ if 'example_feature_1' == feature_name:
449
+ return 'summary statistic that is equal to 1 for any forest.'
450
+ if 'example_feature_2' == feature_name:
451
+ return 'summary statistic that is equal to 2 for any forest.'
452
+ return None
453
+ ```
454
+
455
+ Then, you need to register it in the [treesumstats.FeatureRegistry](treesumstats),
456
+ potentially with other pertinent statistic calculators:
457
+
458
+ ```python3
459
+ from treesumstats import FeatureManager
460
+ from treesumstats.tree_manager import read_forest
461
+ from treesumstats import FeatureRegistry
462
+
463
+ FeatureRegistry.register(ExampleFeatureCalculator())
464
+
465
+ # below we will also register all existing statistic calculators
466
+ from treesumstats.basic_sumstats import BasicFeatureCalculator
467
+ from treesumstats.branch_sumstats import BranchFeatureCalculator
468
+ from treesumstats.event_time_sumstats import EventTimeFeatureCalculator
469
+ from treesumstats.ltt_sumstats import LTTFeatureCalculator
470
+ from treesumstats.resolution_sumstats import ResolutionFeatureCalculator
471
+ from treesumstats.subtree_sumstats import SubtreeFeatureCalculator
472
+ from treesumstats.balance_sumstats import BalanceFeatureCalculator
473
+ from treesumstats.transmission_chain_sumstats import TransmissionChainFeatureCalculator
474
+
475
+ FeatureRegistry.register(BasicFeatureCalculator())
476
+ FeatureRegistry.register(ResolutionFeatureCalculator())
477
+ FeatureRegistry.register(BalanceFeatureCalculator())
478
+ FeatureRegistry.register(EventTimeFeatureCalculator())
479
+ FeatureRegistry.register(BranchFeatureCalculator())
480
+ FeatureRegistry.register(TransmissionChainFeatureCalculator())
481
+ FeatureRegistry.register(LTTFeatureCalculator())
482
+ FeatureRegistry.register(SubtreeFeatureCalculator())
483
+ ```
484
+
485
+ Once registered, you can use it to calculate statistics:
486
+
487
+ ```python3
488
+ # make sure the FeatureManager now has our new statistics
489
+ assert 'example_feature_1' in FeatureManager.available_features()
490
+
491
+ forest = read_forest('tree.nwk')
492
+
493
+ # Compute all possible features on the input forest and print their values and descriptions to the standard output
494
+ for feature_name, value in zip(FeatureManager.available_features(), FeatureManager.compute_features(forest, *FeatureManager.available_features())):
495
+ print(f'{feature_name}\t{value}{FeatureManager.help(feature_name)}')
496
+ ```