New upstream version 0.5.2

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 [treetime.ch](https://treetime.ch).

In addition to scripting TreeTime or using it via the command-line, there is also a small web server at [treetime.ch](https://treetime.biozentrum.unibas.ch/).

![Molecular clock phylogeny of 200 NA sequences of influenza A H3N2](https://raw.githubusercontent.com/neherlab/treetime_examples/master/figures/tree_and_clock.png)

Have a look at our [examples and tutorials](https://github.com/neherlab/treetime_examples).

#### Features

* ancestral sequence reconstruction (marginal and joint maximum likelihood)

* molecular clock tree inference (marginal and joint maximum likelihood)

    + [Ancestral sequence reconstruction](#ancestral-sequence-reconstruction)

    + [Homoplasy analysis](#homoplasy-analysis)

    + [Mugration analysis](#mugration-analysis)

    + [Metadata and date format](#metadata-and-date-format)

  * [Example scripts](#example-scripts)

  * [Related tools](#related-tools)

  * [Projects using TreeTime](#projects-using-treetime)

  pip install .

```

within this repository.

You can also install TreeTime from PyPi via

```bash

  pip install phylo-treetime

```

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.

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, see [below](#metadata-and-date-format) for details.

#### Timetrees

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

The full list if options is available by typing `treetime mugration -h`.

Please see [treetime_examples/mugration.md](https://github.com/neherlab/treetime_examples/blob/master/mugration.md) for examples and more documentation.

#### Metadata and date format

Several 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 named `name`, `accession`, or `strain`.

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 of `name`, `accession`, or `strain` is found, TreeTime will use the first.

If the analysis requires dates, at least one column name needs to contain `date` (i.e. `sampling date` is fine).

Again, if multiple hits are found, TreeTime will use the first.

TreeTime will attempt to parse dates in the following way and order

| order | type/format | example | description|

| --- |-------------|---------|------------|

| 1| float       | 2017.56 | decimal date |

| 2| [float:float] | [2013.45:2015.56] | decimal date range |

| 3| %Y-%m-%d    | 2017-08-25 | calendar date in ISO format |

| 4| %Y-XX-XX    | 2017-XX-XX | calendar date missing month and/or day |

### 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/ancestral_inference.py`.

def add_gtr_arguments(parser):

    parser.add_argument('--gtr', default='infer', help=gtr_description)

    parser.add_argument('--gtr-params', nargs='+', help=gtr_params_description)

    parser.add_argument('--aa', action='store_true', help="use aminoacid alphabet")

def add_anc_arguments(parser):

    add_reroot_group(t_parser)

    add_gtr_arguments(t_parser)

    t_parser.add_argument('--clock-rate', type=float, help="if specified, the rate of the molecular clock won't be optimized.")

    t_parser.add_argument('--clock-std-dev', type=float, help="standard deviation of the provided clock rate estimate")

    t_parser.add_argument('--branch-length-mode', default='auto', type=str, choices=['auto', 'input', 'joint', 'marginal'],

                        help="If set to 'input', the provided branch length will be used without modification. "

                             "Note that branch lengths optimized by treetime are only accurate at short evolutionary distances.")

    t_parser.add_argument('--confidence', action='store_true', help="estimate confidence intervals of divergence times.")

    t_parser.add_argument('--keep-polytomies', default=False, action='store_true',

                        help="Don't resolve polytomies using temporal information.")

    t_parser.add_argument('--relax',nargs='*', default=False,

                        help='use an autocorrelated molecular clock. Prior strength and coupling of parent '

                             'and offspring rates can be specified e.g. as --relax 1.0 0.5')

    t_parser.add_argument('--relax',nargs=2, type=float,

                        help='use an autocorrelated molecular clock. Strength of the gaussian priors on'

                             ' branch specific rate deviation and the coupling of parent and offspring'

                             ' rates can be specified e.g. as --relax 1.0 0.5. Values around 1.0 correspond'

                             ' to weak priors, larger values constrain rate deviations more strongly.'

                             ' Coupling 0 (--relax 1.0 0) corresponds to an un-correlated clock.')

    t_parser.add_argument('--max-iter', default=2, type=int,

                        help='maximal number of iterations the inference cycle is run. Note that for polytomy resolution and coalescence models max_iter should be at least 2')

    t_parser.add_argument('--coalescent', default="0.0", type=str,

    t_parser.add_argument('--plot-rtt', default="root_to_tip_regression.pdf",

                            help = "filename to save the plot to. Suffix will determine format"

                                   " (choices pdf, png, svg, default=pdf)")

    t_parser.add_argument('--tip-labels', action='store_true',

                            help = "add tip labels (default for small trees with <30 leaves)")

    t_parser.add_argument('--no-tip-labels', action='store_true',

                            help = "don't show tip labels (default for small trees with >=30 leaves)")

    add_anc_arguments(t_parser)

    add_common_args(t_parser)

# General information about the project.

project = u'TreeTime'

copyright = u'2017, Pavel Sagulenko and Richard Neher'

copyright = u'2017-2018, Pavel Sagulenko and Richard Neher'

author = u'Pavel Sagulenko and Richard Neher'

# The version info for the project you're documenting, acts as replacement for

# built documents.

#

# The short X.Y version.

version = u'0.4.0'

version = u'0.5.0'

# The full version, including alpha/beta/rc tags.

release = u'0.4.0'

release = u'0.5.0'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

Command-line functions

======================

TreeTime is designed to be part of python workflows, but for a number of standard

tasks we have implemented scripts that can be called from the command line like

regular linux programs.

TreeTime is designed to be part of python workflows, but we have exposed a number of standard

tasks via a command-line interface.

The TreeTime command-line tool is called :code:`treetime`.

Examples and documentation of the command-line interface can be found in the github repo https://github.com/neherlab/treetime_examples.

In its standard mode, it will take a tree, an alignment, and file with dates as input and estimate a time-scaled phylogeny.

The full set of options are available via :code:`treetime -h`.

Subcommand :code:`treetime ancestral`

-------------------------------------

This subcommand reconstructs ancestral sequences and maps mutations to the tree.

It produces an alignment file containing inferred ancestral sequences and a tree file

with mutations included as comments. The inferred GTR model is written to stdout.

homoplasy_scanner

-----------------

Subcommand :code:`treetime homoplasy`

-------------------------------------

Reconstructs ancestral sequences and maps mutations to the tree.

The tree is then scanned for homoplasies. An excess number of homoplasies

might suggest contamination, recombination, culture adaptation or similar.

Results are printed to stdout.

ancestral_reconstruction

------------------------

Reconstructs ancestral sequences and maps mutations to the tree.

Produces an alignment file containing inferred ancestral sequences and a tree file

with mutations included as comments. The inferred GTR model is written to stdout.

temporal_signal

Subcommand :code:`treetime clock`

---------------

Calculates the root-to-tip regression and quantifies the 'clock-i-ness' of the tree.

It will reroot the tree to maximize the clock-like

signal and recalculate branch length unless run with --keep_root.

signal and recalculate branch length unless run with :code:`--keep_root`.

timetree_inference

------------------

Reconstructs ancestral sequences and infers a molecular clock tree. Produces

an alignment file containing inferred ancestral sequences and a tree file with

mutations included as comments, and prints the molecular clock and inferred

GTR model.

mugration

---------

Subcommand :code:`treetime mugration`

-------------------------------------

Reconstructs discrete ancestral states, for example geographic location, host, or similar.

Indices and tables

==================

.. automethod:: treetime.TreeTime.reroot_to_best_root

.. automethod:: treetime.TreeTime.find_best_root_and_regression

.. automethod:: treetime.TreeTime.plot_root_to_tip

.. automethod:: treetime.TreeTime.print_lh