Package: phylo-treetime
TreeTime: maximum likelihood dating and ancestral sequence inferenceOverviewTreeTime 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 (assuming the branch length of the input tree is in units of average number of nucleotide or protein substitutions per site in the sequence). After infering ancestral sequences TreeTime 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.The documentation of TreeTime is hosted on readthedocs.org.In addition to scripting TreeTime or using it via the command-line, there is also a small web server attreetime.ch.Have a look at our repository withexample dataand thetutorials.Featuresancestral sequence reconstruction (marginal and joint maximum likelihood)molecular clock tree inference (marginal and joint maximum likelihood)inference of GTR modelsrerooting to maximize temporal signal and optimize the root-to-tip distance vs time relationshipsimple phylodynamic analysis such as coalescent model fitssequence evolution along trees using flexible site specific models.Table of contentsInstallation and prerequisitesCommand-line usageTimetreesRerooting and substitution rate estimationAncestral sequence reconstructionHomoplasy analysisMugration analysisMetadata and date formatExample scriptsRelated toolsProjects using TreeTimeBuilding the documentationDeveloper infoInstallation and prerequisitesTreeTime is compatible with Python 3.7 upwards and is tested on 3.7 to 3.10.  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
functionalitymatplotlib: optional dependency for plottingYou may install TreeTime and its dependencies by runningpipinstall.within this repository.
You can also install TreeTime from PyPi viapipinstallphylo-treetimeYou 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 usageTreeTime 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, TreeTime can be used from the command line with arguments specifying input data and parameters.
Trees can be read as newick, nexus and phylip files; fasta and phylip are supported alignment formats; metadata and dates can be provided as csv or tsv files, seebelowfor details.TimetreesThe 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 is available inthe documentation on readthedocs.org.Rerooting and substitution rate estimationTo explore the temporal signal in the data and estimate the substitution rate (instead if full-blown timetree estimation), TreeTime implements a subcommandclockthat is called as followstreetimeclock--tree<input.nwk>--aln<input.fasta>--dates<dates.csv>--rerootleast-squaresThe full list if options is available by typingtreetime clock -h.
Instead of an input alignment,--sequence-length <L>can be provided.
Documentation of additional options and examples are available at inthe documentation on readthedocs.org.Ancestral sequence reconstruction:The subcommandtreetimeancestral--alninput.fasta--treeinput.nwkwill reconstruct ancestral sequences at internal nodes of the input tree.
The full list if options is available by typingtreetime ancestral -h.
A detailed explanation oftreetime ancestralwith examples is available at inthe documentation on readthedocs.org.Homoplasy analysisDetecting 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 datatreetimehomoplasy--aln<input.fasta>--tree<input.nwk>The full list if options is available by typingtreetime homoplasy -h.
Please seethe documentation on readthedocs.orgfor examples and more documentation.Mugration analysisMigration 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:treetimemugration--tree<input.nwk>--states<states.csv>--attribute<field>where<field>is the relevant column in the csv file specifying the metadatastates.csv, e.g.<field>=country.
The full list if options is available by typingtreetime mugration -h.
Please seethe documentation on readthedocs.orgfor examples and more documentation.Metadata and date formatSeveral of TreeTime commands require the user to specify a file with dates and/or other meta data.
TreeTime assumes these files to by either comma (csv) or tab-separated (tsv) files.
The first line of these files is interpreted as header line specifying the content of the columns.
Each file needs to have at least one column that is namedname,accession, orstrain.
This column needs to contain the names of each sequence and match the names of taxons in the tree if one is provided.
If more than one ofname,accession, orstrainis found, TreeTime will use the first.If the analysis requires dates, at least one column name needs to containdate(i.e.sampling dateis fine).
Again, if multiple hits are found, TreeTime will use the first.
TreeTime will attempt to parse dates in the following way and orderordertype/formatexampledescription1float2017.56decimal date2[float:float][2013.45:2015.56]decimal date range3%Y-%m-%d2017-08-25calendar date in ISO format4%Y-XX-XX2017-XX-XXcalendar date missing month and/or dayExample scriptsThe 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 asrun examples/ancestral_inference.py.ancestral_inference.pyillustrates how ancestral sequences are inferred and likely mutations are assigned to branches in the tree,relaxed_clock.pywalks the user through the usage of relaxed molecular clock models.examples/rerooting_and_timetrees.pyillustrates the rerooting and root-to-tip regression scatter plots.ebola.pyuses 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 athere.Related toolsThere are several other tools which estimate molecular clock phylogenies.Beastrelies 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) asTreeTime), but provides limited scope for customization.treedaterby Eric Volz and Simon Frost is an R package that implements time tree estimation and supports relaxed clocks.Projects using TreeTimeTreeTime is an integral part of thenextstrain.orgproject to track and analyze viral sequence data in real time.panXuses TreeTime for ancestral reconstructions and inference of gene gain-loss patterns.Building the documentationThe 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 aspipinstallSphinxAfter required packages are installed, navigate to doc directory, and build the docs by typing:makehtmlInstead of html, another target aslatexorepubcan be specified to build the docs in the desired format.RequirementsTo 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 infoCopyright and License: Pavel Sagulenko, Emma Hodcroft, and Richard Neher, MIT LicenceReferencesTreeTime: Maximum-likelihood phylodynamic analysisby Pavel Sagulenko, Vadim Puller and Richard A Neher. Virus Evolution.NextStrain: real-time tracking of pathogen evolutionby James Hadfield et al. Bioinformatics.