# 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``--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``--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]
```