Detailed command line documentation

usage: TreeTime: Maximum Likelihood Phylodynamics

Named Arguments

--tree

Name of file containing the tree in newick, nexus, or phylip format, the branch length of the tree should be in units of average number of nucleotide or protein substitutions per site. If no file is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed).

--rng-seed

random number generator seed for treetime

--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-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 using the marginal posterior distribution, if –time-marginal is False (default) inferred divergence times will still be calculated using the jointly most likely tree configuration.

Default: False

--time-marginal

Possible choices: false, true, assign, always, only-final, never

For ‘false’ or ‘never’, TreeTime uses the jointly most likely values for the divergence times. For ‘true’ and ‘always’, it uses the marginal inference mode at every round of optimization, for ‘only-final’ (or ‘assign’ for compatibility with previous versions) only uses the marginal distribution in the final round.

Default: “false”

--keep-polytomies

Don’t resolve polytomies using temporal information.

Default: False

--stochastic-resolve

Resolve polytomies using a random coalescent tree.

Default: False

--greedy-resolve

Resolve polytomies greedily. Currently default, but will switched to stochastic-resolve in future versions.

Default: True

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

--gen-per-year

number of generations per year - used for estimating N_e in coalescent models

Default: 50.0

--n-branches-posterior

add posterior LH to coalescent model: use the posterior probability distributions of divergence times for estimating the number of branches when calculating the coalescent mergerrate or use inferred time before present (default).

Default: False

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

--clock-filter

ignore tips that don’t follow a loose clock, ‘clock-filter=number of interquartile ranges from regression (method=`residual`)’ or z-score of local clock deviation (method=`local`). Default=4.0, set to 0 to switch off.

Default: 4.0

--clock-filter-method

Possible choices: residual, local

Use residuals from global clock (residual, default) or local clock deviation (clock) to filter out tips that don’t follow the clock

Default: “residual”

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

--custom-gtr

filename of pre-defined custom GTR model in standard TreeTime format

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

--method-anc

Possible choices: parsimony, fitch, probabilistic, ml

method used for reconstructing ancestral sequences, default is ‘probabilistic’

Default: “probabilistic”

--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] [--rng-seed RNG_SEED] [--const CONST]
                   [--rescale RESCALE] [--detailed] [--gtr GTR]
                   [--gtr-params GTR_PARAMS [GTR_PARAMS ...]] [--aa]
                   [--custom-gtr CUSTOM_GTR] [--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, the branch length of the tree should be in units of average number of nucleotide or protein substitutions per site. If no file is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed).

--rng-seed

random number generator seed for treetime

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

--custom-gtr

filename of pre-defined custom GTR model in standard TreeTime format

--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] [--rng-seed RNG_SEED] [--gtr GTR]
                   [--gtr-params GTR_PARAMS [GTR_PARAMS ...]] [--aa]
                   [--custom-gtr CUSTOM_GTR] [--marginal] [--keep-overhangs]
                   [--zero-based] [--reconstruct-tip-states]
                   [--report-ambiguous]
                   [--method-anc {parsimony,fitch,probabilistic,ml}]
                   [--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, the branch length of the tree should be in units of average number of nucleotide or protein substitutions per site. If no file is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed).

--rng-seed

random number generator seed for treetime

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

--custom-gtr

filename of pre-defined custom GTR model in standard TreeTime format

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

--method-anc

Possible choices: parsimony, fitch, probabilistic, ml

method used for reconstructing ancestral sequences, default is ‘probabilistic’

Default: “probabilistic”

--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 [--rng-seed RNG_SEED]
                   [--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, the branch length of the tree should be in units of average number of nucleotide or protein substitutions per site. If no file is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed).

--rng-seed

random number generator seed for treetime

--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 [--rng-seed RNG_SEED] [--dates DATES]
               [--name-column NAME_COLUMN] [--date-column DATE_COLUMN]
               [--sequence-length SEQUENCE_LENGTH] [--aln ALN]
               [--vcf-reference VCF_REFERENCE] [--clock-filter CLOCK_FILTER]
               [--clock-filter-method {residual,local}]
               [--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, the branch length of the tree should be in units of average number of nucleotide or protein substitutions per site. If no file is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed).

--rng-seed

random number generator seed for treetime

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

--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 (method=`residual`)’ or z-score of local clock deviation (method=`local`). Default=4.0, set to 0 to switch off.

Default: 4.0

--clock-filter-method

Possible choices: residual, local

Use residuals from global clock (residual, default) or local clock deviation (clock) to filter out tips that don’t follow the clock

Default: “residual”

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

arg

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 arg [-h] [--rng-seed RNG_SEED] --trees TREES TREES --alignments
             ALIGNMENTS ALIGNMENTS --mccs MCCS [--clock-rate CLOCK_RATE]
             [--clock-std-dev CLOCK_STD_DEV]
             [--branch-length-mode {auto,input,joint,marginal}] [--confidence]
             [--time-marginal {false,true,assign,always,only-final,never}]
             [--keep-polytomies] [--stochastic-resolve] [--greedy-resolve]
             [--relax RELAX RELAX] [--max-iter MAX_ITER]
             [--coalescent COALESCENT] [--n-skyline N_SKYLINE]
             [--gen-per-year GEN_PER_YEAR] [--n-branches-posterior]
             [--plot-tree PLOT_TREE] [--plot-rtt PLOT_RTT] [--tip-labels]
             [--no-tip-labels] [--dates DATES] [--name-column NAME_COLUMN]
             [--date-column DATE_COLUMN] [--sequence-length SEQUENCE_LENGTH]
             [--aln ALN] [--vcf-reference VCF_REFERENCE] [--keep-overhangs]
             [--zero-based] [--reconstruct-tip-states] [--report-ambiguous]
             [--method-anc {parsimony,fitch,probabilistic,ml}]
             [--clock-filter CLOCK_FILTER]
             [--clock-filter-method {residual,local}]
             [--reroot REROOT [REROOT ...] | --keep-root]
             [--tip-slack TIP_SLACK] [--covariation] [--verbose VERBOSE]
             [--outdir OUTDIR]

Named Arguments

--rng-seed

random number generator seed for treetime

--trees

--alignments

--mccs

--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 using the marginal posterior distribution, if –time-marginal is False (default) inferred divergence times will still be calculated using the jointly most likely tree configuration.

Default: False

--time-marginal

Possible choices: false, true, assign, always, only-final, never

For ‘false’ or ‘never’, TreeTime uses the jointly most likely values for the divergence times. For ‘true’ and ‘always’, it uses the marginal inference mode at every round of optimization, for ‘only-final’ (or ‘assign’ for compatibility with previous versions) only uses the marginal distribution in the final round.

Default: “false”

--keep-polytomies

Don’t resolve polytomies using temporal information.

Default: False

--stochastic-resolve

Resolve polytomies using a random coalescent tree.

Default: False

--greedy-resolve

Resolve polytomies greedily. Currently default, but will switched to stochastic-resolve in future versions.

Default: True

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

--gen-per-year

number of generations per year - used for estimating N_e in coalescent models

Default: 50.0

--n-branches-posterior

add posterior LH to coalescent model: use the posterior probability distributions of divergence times for estimating the number of branches when calculating the coalescent mergerrate or use inferred time before present (default).

Default: False

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

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

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

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

--method-anc

Possible choices: parsimony, fitch, probabilistic, ml

method used for reconstructing ancestral sequences, default is ‘probabilistic’

Default: “probabilistic”

--clock-filter

ignore tips that don’t follow a loose clock, ‘clock-filter=number of interquartile ranges from regression (method=`residual`)’ or z-score of local clock deviation (method=`local`). Default=4.0, set to 0 to switch off.

Default: 4.0

--clock-filter-method

Possible choices: residual, local

Use residuals from global clock (residual, default) or local clock deviation (clock) to filter out tips that don’t follow the clock

Default: “residual”

--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 overdispersion of the molecular clock

Default: 3

--covariation

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

Default: False

--verbose

verbosity of output 0-6

Default: 1

--outdir

directory to write the output to

version

print version

treetime version [-h]