Skip to main content

Maximum-likelihood phylodynamic inference

Project description

Build Status anaconda

TreeTime: maximum likelihood dating and ancestral sequence inference


TreeTime provides routines for ancestral sequence reconstruction and inference of molecular-clock phylogenies, i.e., a tree where all branches are scaled such that the positions of terminal nodes correspond to their sampling times and internal nodes are placed at the most likely time of divergence.

To optimize the likelihood of time-scaled phylogenies, TreeTime uses an iterative approach that first infers ancestral sequences given the branch length of the tree, then optimizes the positions of unconstrained nodes on the time axis, and then repeats this cycle. The only topology optimization are (optional) resolution of polytomies in a way that is most (approximately) consistent with the sampling time constraints on the tree. The package is designed to be used as a stand-alone tool on the command-line or as a library used in larger phylogenetic analysis work-flows.

In addition to scripting TreeTime or using it via the command-line, there is also a small web server at

Molecular clock phylogeny of 200 NA sequences of influenza A H3N2


  • ancestral sequence reconstruction (marginal and joint maximum likelihood)
  • molecular clock tree inference (marginal and joint maximum likelihood)
  • inference of GTR models
  • rerooting to maximize temporal signal and optimize the root-to-tip distance vs time relationship
  • simple phylodynamic analysis such as coalescent model fits

Table of contents

Installation and prerequisites

TreeTime is compatible with Python 2.7 upwards and is tested on 2.7, 3.5, and 3.6. It depends on several Python libraries:

  • numpy, scipy, pandas: for all kind of mathematical operations as matrix operations, numerical integration, interpolation, minimization, etc.

  • BioPython: for parsing multiple sequence alignments and all phylogenetic functionality

  • matplotlib: optional dependency for plotting

You may install TreeTime and its dependencies by running

  pip install .

within this repository.

You might need root privileges for system wide installation. Alternatively, you can simply use it TreeTime locally without installation. In this case, just download and unpack it, and then add the TreeTime folder to your $PYTHONPATH.

Command-line usage

TreeTime can be used as part of python programs that create and interact with tree time objects. How TreeTime can be used to address typical questions like ancestral sequence reconstruction, rerooting, timetree inference etc is illustrated by a collection of example scripts described below.

In addition, we provide scripts that can be run from the command line with arguments specifying input data and parameters.


The to infer a timetree, i.e. a phylogenetic tree in which branch length reflect time rather than divergence, TreeTime offers implements the command:

  treetime --aln <input.fasta> --tree <input.nwk> --dates <dates.csv>

This command will infer a time tree, ancestral sequences, a GTR model, and optionally confidence intervals and coalescent models. A detailed explanation is of this command with its various options and examples are available at treetime_examples/

Rerooting and substitution rate estimation

To explore the temporal signal in the data and estimate the substitution rate (instead if full-blown timetree estimation), TreeTime implements a subcommand clock that is called as follows

  treetime clock --tree <input.nwk> --aln <input.fasta> --dates <dates.csv> --reroot least-squares

The full list if options is available by typing treetime clock -h. Instead of an input alignment, --sequence-length <L> can be provided. Documentation of additional options and examples are available at treetime_examples/

Ancestral sequence reconstruction:

The subcommand

  treetime ancestral --aln input.fasta --tree input.nwk

will reconstruct ancestral sequences at internal nodes of the input tree. The full list if options is available by typing treetime ancestral -h. A detailed explanation of treetime ancestral with examples is available at treetime_examples/

Homoplasy analysis

Detecting and quantifying homoplasies or recurrent mutations is useful to check for recombination, putative adaptive sites, or contamination. TreeTime provides a simple command to summarize homoplasies in data

  treetime homoplasy --aln <input.fasta> --tree <input.nwk>

The full list if options is available by typing treetime homoplasy -h. Please see treetime_examples/ for examples and more documentation.

Mugration analysis

Migration between discrete geographic regions, host switching, or other transition between discrete states are often parameterized by time-reversible models analogous to models describing evolution of genome sequences. Such models are hence often called "mugration" models. TreeTime GTR model machinery can be used to infer mugration models:

  treetime mugration --tree <input.nwk> --states <states.csv> --attribute <field>

where <field> is the relevant column in the csv file specifying the metadata states.csv, e.g. <field>=country. The full list if options is available by typing treetime mugration -h. Please see treetime_examples/ for examples and more documentation.

Example scripts

The following scripts illustrate how treetime can be used to solve common problem with short python scripts. They are meant to be used in an interactive ipython environment and run as run examples/

  • illustrates how ancestral sequences are inferred and likely mutations are assigned to branches in the tree,
  • walks the user through the usage of relaxed molecular clock models.
  • examples/ illustrates the rerooting and root-to-tip regression scatter plots.
  • uses about 300 sequences from the 2014-2015 Ebola virus outbreak to infer a timetree. This example takes a few minutes to run.

HTML documentation of the different classes and function is available at here.

Related tools

There are several other tools which estimate molecular clock phylogenies.

  • Beast relies on the MCMC-type sampling of trees. It is hence rather slow for large data sets. But BEAST allows the flexible inclusion of prior distributions, complex evolutionary models, and estimation of parameters.
  • Least-Square-Dating (LSD) emphasizes speed (it scales as O(N) as TreeTime), but provides limited scope for customization.
  • treedater by Eric Volz and Simon Frost is an R package that implements time tree estimation and supports relaxed clocks.

Projects using TreeTime

  • TreeTime is an integral part of the project to track and analyze viral sequence data in real time.
  • panX uses TreeTime for ancestral reconstructions and inference of gene gain-loss patterns.

Building the documentation

The API documentation for the TreeTime package is generated created with Sphinx. The source code for the documentaiton is located in doc folder.

  • sphinx-build to generate static html pages from source. Installed as
pip install Sphinx
  • basicstrap Html theme for sphinx:
pip install sphinxjp.themes.basicstrap

After required packages are installed, navigate to doc directory, and build the docs by typing:

make html

Instead of html, another target as latex or epub can be specified to build the docs in the desired format.


To build the documentation, sphinx-build tool should be installed. The doc pages are using basicstrap html theme to have the same design as the TreeTime web server. Therefore, the basicstrap theme should be also available in the system.

Developer info

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
phylo_treetime-0.5.1-py3-none-any.whl (111.1 kB) Copy SHA256 hash SHA256 Wheel py3
phylo-treetime-0.5.1.tar.gz (107.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page