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