TreeTime class documentation
TreeTime is the top-level wrapper class of the time tree inference package. In addition to inferring time trees, TreeTime can reroot your tree, resolve polytomies, mark tips that violate the molecular clock, or infer coalescent models. The core time tree inference is implemented in the class ClockTree.
TreeTime docstring and constructor
- class treetime.TreeTime(*args, **kwargs)
TreeTime is a wrapper class to ClockTree that adds additional functionality such as reroot, detection and exclusion of outliers, resolution of polytomies using temporal information, and relaxed molecular clock models
- __init__(*args, **kwargs)
*args – Arguments to construct ClockTree
**kwargs – Keyword arguments to construct the GTR model
Main pipeline method
- TreeTime.run(raise_uncaught_exceptions=False, **kwargs)
- TreeTime.resolve_polytomies(merge_compressed=False, resolution_threshold=0.05, stochastic_resolve=False)
Resolve the polytomies on the tree.
The function scans the tree, resolves polytomies if present, and re-optimizes the tree with new topology. Note that polytomies are only resolved if that would result in higher likelihood. Sometimes, stretching two or more branches that carry several mutations is less costly than an additional branch with zero mutations (long branches are not stiff, short branches are).
merge_compressed (bool) – If True, keep compressed branches as polytomies. Applies to greedy resolve
resolution_threshold (float) – minimal delta LH to consider for polytomy resolution. Otherwise, keep parent as polytomy
stochastic_resolve (bool) – generate a stochastic binary coalescent tree with mutation from the children of a polytomy. Doesn’t necessarily resolve the node fully. This step is stochastic and different runs will result in different outcomes.
poly_found – The number of polytomies found
- Return type:
- TreeTime.relaxed_clock(slack=None, coupling=None, **kwargs)
Allow the mutation rate to vary on the tree (relaxed molecular clock). Changes of the mutation rates from one branch to another are penalized. In addition, deviation of the mutation rate from the mean rate is penalized.
slack (float) – Maximum change in substitution rate between parent and child nodes
coupling (float) – Maximum difference in substitution rates in sibling nodes
- TreeTime.clock_filter(reroot='least-squares', method='residual', n_iqd=None, plot=False, fixed_clock_rate=None)
Labels outlier branches that don’t seem to follow a molecular clock and excludes them from subsequent molecular clock estimation and the timetree propagation.
reroot (str) – Method to find the best root in the tree (see
n_iqd (float) –
Number of iqd intervals. The outlier nodes are those which do not fall into \(IQD\cdot n_iqd\) interval (\(IQD\) is the interval between 75th and 25th percentiles)
If None, the default (3) assumed
plot (bool) – If True, plot the results
- TreeTime.reroot(root='least-squares', force_positive=True, covariation=None, clock_rate=None)
Find best root and re-root the tree to the new root
root (str) –
Which method should be used to find the best root. Available methods are:
best, least-squares - minimize squared residual or likelihood of root-to-tip regression
min_dev- minimize variation of root-to-tip distance
oldest- reroot on the oldest node
<node_name>- reroot to the node with name
[<node_name1>, <node_name2>, ...]- reroot to the MRCA of these nodes
only consider positive rates when searching for the optimal root
account for covariation in root-to-tip regression
- TreeTime.plot_root_to_tip(add_internal=False, label=True, ax=None)
Plot root-to-tip regression
add_internal (bool) – If true, plot inte`rnal node positions
label (bool) – If true, label the plots
ax (matplotlib axes) – If not None, use the provided matplotlib axes to plot the results
Print the total likelihood of the tree given the constrained leaves
joint (bool) – If true, print joint LH, else print marginal LH
- treetime.plot_vs_years(tt, step=None, ax=None, confidence=None, ticks=True, selective_confidence=None, **kwargs)
Converts branch length to years and plots the time tree on a time axis.
tt (TreeTime object) – A TreeTime instance after a time tree is inferred
step (int) – Width of shaded boxes indicating blocks of years. Will be inferred if not specified. To switch off drawing of boxes, set to 0
ax (matplotlib axes) – Axes to be used to plot, will create new axis if None
confidence (tuple, float) – Draw confidence intervals. This assumes that marginal time tree inference was run. Confidence intervals are either specified as an interval of the posterior distribution like (0.05, 0.95) or as the weight of the maximal posterior region , e.g. 0.9
**kwargs (dict) – Key word arguments that are passed down to Phylo.draw