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)[source]

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)[source]

TreeTime constructor

Parameters:

  • *args – Arguments to construct ClockTree

  • **kwargs – Keyword arguments to construct the GTR model

Main pipeline method

TreeTime.run(raise_uncaught_exceptions=False, **kwargs)[source]

Additional functionality

TreeTime.resolve_polytomies(merge_compressed=False, resolution_threshold=0.05, stochastic_resolve=False)[source]

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).

Parameters:

  • 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.

Returns:

poly_found – The number of polytomies found

Return type:

int

TreeTime.relaxed_clock(slack=None, coupling=None, **kwargs)[source]

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.

Parameters:

  • 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)[source]

Labels outlier branches that don’t seem to follow a molecular clock and excludes them from subsequent molecular clock estimation and the timetree propagation.

Parameters:

  • reroot (str) – Method to find the best root in the tree (see treetime.TreeTime.reroot() for options)

  • 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)[source]

Find best root and re-root the tree to the new root

Parameters:

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_name>

[<node_name1>, <node_name2>, ...] - reroot to the MRCA of these nodes

force_positivebool

only consider positive rates when searching for the optimal root

covariationbool

account for covariation in root-to-tip regression

TreeTime.plot_root_to_tip(add_internal=False, label=True, ax=None)[source]

Plot root-to-tip regression

Parameters:

  • 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

TreeTime.print_lh(joint=True)[source]

Print the total likelihood of the tree given the constrained leaves

Parameters:

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)[source]

Converts branch length to years and plots the time tree on a time axis.

Parameters:

  • 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