Detailed command line documentation

usage: TreeTime: Maximum Likelihood Phylodynamics

Named Arguments

--tree

Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed)

--sequence-length

length of the sequence, used to calculate expected variation in branch length. Not required if alignment is provided.

--aln

alignment file (fasta)

--vcf-reference

only for vcf input: fasta file of the sequence the VCF was mapped to.

--dates

csv file with dates for nodes with ‘node_name, date’ where date is float (as in 2012.15)

--name-column

label of the column to be used as taxon name

--date-column

label of the column to be used as sampling date

--clock-filter

ignore tips that don’t follow a loose clock, ‘clock-filter=number of interquartile ranges from regression’. Default=3.0, set to 0 to switch off.

Default: 3

--reroot

Reroot the tree using root-to-tip regression. Valid choices are ‘min_dev’, ‘least-squares’, and ‘oldest’. ‘least-squares’ adjusts the root to minimize residuals of the root-to-tip vs sampling time regression, ‘min_dev’ minimizes variance of root-to-tip distances. ‘least-squares’ can be combined with –covariation to account for shared ancestry. Alternatively, you can specify a node name or a list of node names to be used as outgroup or use ‘oldest’ to reroot to the oldest node. By default, TreeTime will reroot using ‘least-squares’. Use –keep-root to keep the current root.

Default: “best”

--keep-root

don’t reroot the tree. Otherwise, reroot to minimize the the residual of the regression of root-to-tip distance and sampling time

Default: False

--tip-slack

excess variance associated with terminal nodes accounting for overdisperion of the molecular clock

Default: 3

--covariation

Account for covariation when estimating rates or rerooting using root-to-tip regression, default False.

Default: False

--gtr

GTR model to use. ‘–gtr infer’ will infer a model from the data. Alternatively, specify the model type. If the specified model requires additional options, use ‘–gtr-params’ to specify those.

Default: “infer”

--gtr-params

GTR parameters for the model specified by the –gtr argument. The parameters should be feed as ‘key=value’ list of parameters. Example: ‘–gtr K80 –gtr-params kappa=0.2 pis=0.25,0.25,0.25,0.25’. See the exact definitions of the parameters in the GTR creation methods in treetime/nuc_models.py or treetime/aa_models.py

--aa

use aminoacid alphabet

Default: False

--clock-rate

if specified, the rate of the molecular clock won’t be optimized.

--clock-std-dev

standard deviation of the provided clock rate estimate

--branch-length-mode

Possible choices: auto, input, joint, marginal

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.

Default: “auto”

--confidence

estimate confidence intervals of divergence times.

Default: False

--keep-polytomies

Don’t resolve polytomies using temporal information.

Default: False

--relax

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.

--max-iter

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

Default: 2

--coalescent

coalescent time scale – sensible values are on the order of the average hamming distance of contemporaneous sequences. In addition, ‘opt’ ‘skyline’ are valid options and estimate a constant coalescent rate or a piecewise linear coalescent rate history

Default: “0.0”

--n-skyline

number of grid points in skyline coalescent model

Default: 20

--plot-tree

filename to save the plot to. Suffix will determine format (choices pdf, png, svg, default=pdf)

Default: “timetree.pdf”

--plot-rtt

filename to save the plot to. Suffix will determine format (choices pdf, png, svg, default=pdf)

Default: “root_to_tip_regression.pdf”

--tip-labels

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

Default: False

--no-tip-labels

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

Default: False

--keep-overhangs

do not fill terminal gaps

Default: False

--zero-based

zero based mutation indexing

Default: False

--reconstruct-tip-states

overwrite ambiguous states on tips with the most likely inferred state

Default: False

--report-ambiguous

include transitions involving ambiguous states

Default: False

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

--version

show program’s version number and exit

Sub-commands:

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.

treetime homoplasy [-h] --aln ALN [--vcf-reference VCF_REFERENCE]
                   [--tree TREE] [--const CONST] [--rescale RESCALE]
                   [--detailed] [--gtr GTR]
                   [--gtr-params GTR_PARAMS [GTR_PARAMS ...]] [--aa]
                   [--zero-based] [-n N] [--drms DRMS] [--verbose VERBOSE]
                   [--outdir OUTDIR]

Named Arguments

--aln

alignment file (fasta)

--vcf-reference

only for vcf input: fasta file of the sequence the VCF was mapped to.

--tree

Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed)

--const

number of constant sites not included in alignment

Default: 0

--rescale

rescale branch lengths

Default: 1.0

--detailed

generate a more detailed report

Default: False

--gtr

GTR model to use. ‘–gtr infer’ will infer a model from the data. Alternatively, specify the model type. If the specified model requires additional options, use ‘–gtr-params’ to specify those.

Default: “infer”

--gtr-params

GTR parameters for the model specified by the –gtr argument. The parameters should be feed as ‘key=value’ list of parameters. Example: ‘–gtr K80 –gtr-params kappa=0.2 pis=0.25,0.25,0.25,0.25’. See the exact definitions of the parameters in the GTR creation methods in treetime/nuc_models.py or treetime/aa_models.py

--aa

use aminoacid alphabet

Default: False

--zero-based

zero based mutation indexing

Default: False

-n

number of mutations/nodes that are printed to screen

Default: 10

--drms

TSV file containing DRM info. columns headers: GENOMIC_POSITION, ALT_BASE, DRUG, GENE, SUBSTITUTION

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

ancestral

Reconstructs ancestral sequences and maps mutations to the tree. The output consists of a file ‘ancestral.fasta’ with ancestral sequences and a tree ‘annotated_tree.nexus’ with mutations added as comments like A45G,G136T,…, number in SNPs used 1-based index by default. The inferred GTR model is written to stdout.

treetime ancestral [-h] --aln ALN [--vcf-reference VCF_REFERENCE]
                   [--tree TREE] [--gtr GTR]
                   [--gtr-params GTR_PARAMS [GTR_PARAMS ...]] [--aa]
                   [--marginal] [--keep-overhangs] [--zero-based]
                   [--reconstruct-tip-states] [--report-ambiguous]
                   [--verbose VERBOSE] [--outdir OUTDIR]

Named Arguments

--aln

alignment file (fasta)

--vcf-reference

only for vcf input: fasta file of the sequence the VCF was mapped to.

--tree

Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed)

--gtr

GTR model to use. ‘–gtr infer’ will infer a model from the data. Alternatively, specify the model type. If the specified model requires additional options, use ‘–gtr-params’ to specify those.

Default: “infer”

--gtr-params

GTR parameters for the model specified by the –gtr argument. The parameters should be feed as ‘key=value’ list of parameters. Example: ‘–gtr K80 –gtr-params kappa=0.2 pis=0.25,0.25,0.25,0.25’. See the exact definitions of the parameters in the GTR creation methods in treetime/nuc_models.py or treetime/aa_models.py

--aa

use aminoacid alphabet

Default: False

--marginal

marginal reconstruction of ancestral sequences

Default: False

--keep-overhangs

do not fill terminal gaps

Default: False

--zero-based

zero based mutation indexing

Default: False

--reconstruct-tip-states

overwrite ambiguous states on tips with the most likely inferred state

Default: False

--report-ambiguous

include transitions involving ambiguous states

Default: False

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

mugration

Reconstructs discrete ancestral states, for example geographic location, host, or similar. In addition to ancestral states, a GTR model of state transitions is inferred.

treetime mugration [-h] --tree TREE [--name-column NAME_COLUMN]
                   [--attribute ATTRIBUTE] --states STATES [--weights WEIGHTS]
                   [--confidence] [--pc PC] [--missing-data MISSING_DATA]
                   [--sampling-bias-correction SAMPLING_BIAS_CORRECTION]
                   [--verbose VERBOSE] [--outdir OUTDIR]

Named Arguments

--tree

Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed)

--name-column

label of the column to be used as taxon name

--attribute

attribute to reconstruct, e.g. country

--states

csv or tsv file with discrete characters. #name,country,continent taxon1,micronesia,oceania …

--weights

csv or tsv file with probabilities of that a randomly sampled sequence at equilibrium has a particular state. E.g. population of different continents or countries. E.g.: #country,weight micronesia,0.1 …

--confidence

output confidence of mugration inference

Default: False

--pc

pseudo-counts higher numbers will results in ‘flatter’ models

Default: 1.0

--missing-data

string indicating missing data

Default: “?”

--sampling-bias-correction

a rough estimate of how many more events would have been observed if sequences represented an even sample. This should be roughly the (1-sum_i p_i^2)/(1-sum_i t_i^2), where p_i are the equilibrium frequencies and t_i are apparent ones.(or rather the time spent in a particular state on the tree)

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

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.

treetime clock [-h] --tree TREE --dates DATES [--date-column DATE_COLUMN]
               [--name-column NAME_COLUMN] [--sequence-length SEQUENCE_LENGTH]
               [--aln ALN] [--vcf-reference VCF_REFERENCE]
               [--clock-filter CLOCK_FILTER] [--reroot REROOT [REROOT ...] |
               --keep-root] [--tip-slack TIP_SLACK] [--covariation]
               [--allow-negative-rate] [--plot-rtt PLOT_RTT]
               [--verbose VERBOSE] [--outdir OUTDIR]

Named Arguments

--tree

Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed)

--dates

csv file with dates for nodes with ‘node_name, date’ where date is float (as in 2012.15)

--date-column

label of the column to be used as sampling date

--name-column

label of the column to be used as taxon name

--sequence-length

length of the sequence, used to calculate expected variation in branch length. Not required if alignment is provided.

--aln

alignment file (fasta)

--vcf-reference

only for vcf input: fasta file of the sequence the VCF was mapped to.

--clock-filter

ignore tips that don’t follow a loose clock, ‘clock-filter=number of interquartile ranges from regression’. Default=3.0, set to 0 to switch off.

Default: 3

--reroot

Reroot the tree using root-to-tip regression. Valid choices are ‘min_dev’, ‘least-squares’, and ‘oldest’. ‘least-squares’ adjusts the root to minimize residuals of the root-to-tip vs sampling time regression, ‘min_dev’ minimizes variance of root-to-tip distances. ‘least-squares’ can be combined with –covariation to account for shared ancestry. Alternatively, you can specify a node name or a list of node names to be used as outgroup or use ‘oldest’ to reroot to the oldest node. By default, TreeTime will reroot using ‘least-squares’. Use –keep-root to keep the current root.

Default: “best”

--keep-root

don’t reroot the tree. Otherwise, reroot to minimize the the residual of the regression of root-to-tip distance and sampling time

Default: False

--tip-slack

excess variance associated with terminal nodes accounting for overdisperion of the molecular clock

Default: 3

--covariation

Account for covariation when estimating rates or rerooting using root-to-tip regression, default False.

Default: False

--allow-negative-rate

By default, rates are forced to be positive. For trees with little temporal signal it is advisable to remove this restriction to achieve essentially mid-point rooting.

Default: False

--plot-rtt

filename to save the plot to. Suffix will determine format (choices pdf, png, svg, default=pdf)

Default: “root_to_tip_regression.pdf”

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

version

print version

treetime version [-h]