treetime

timetree

Settings of treetime timetree (Time tree), with their flags, config keys, and defaults.

Infer a time tree and estimate the clock rate from sampling dates.

Inputs

  • Tree (required): Newick or Nexus
  • Metadata (required): CSV, TSV or SSV table
  • Alignment (recommended): Aligned FASTA
81 settings match

Input data

Alignment

--alignment
Value
FILE
Config key
alignment
Aligned FASTA input

Partition

--partition Default: none
Value
ENTRY
Config key
partition
Cannot be combined with
--model --model-params --partition-by
Examples
  • [{"name":"cp12","sites":["1-1500\\3","2-1500\\3"]},{"name":"cp3","sites":["3-1500\\3"],"model":"hky85","model_params":["kappa=4"]}]
One partition: a set of sites of one --alignment file with its own substitution model; repeat the flag for each partition

Partition by

--partition-by Default: not set
Value
SCHEME
Config key
partition_by
Values
  • codon-positions Codon positions 1, 2 and 3 of every CDS of `--annotation` as the partitions `cp1`, `cp2` and `cp3`, and the other sites as `noncoding`
  • genes One partition per CDS of `--annotation`, named by the CDS, and the other sites as `noncoding`
  • rate-categories The partitions `slow`, `medium` and `fast` from the number of changes at each site in a Fitch reconstruction on the input tree, by the rule of `--rate-category-rule`
Cannot be combined with
--partition
Build the partitions of each --alignment file from a scheme instead of --partition entries

Rate category rule

--rate-category-rule Default: change-counts
Value
RULE
Config key
rate_category_rule
Values
  • change-counts `slow` for sites without changes, `medium` for one change, `fast` for two or more
  • median-split `slow` for sites without changes; changed sites at or below the median count of the changed sites go to `medium`, sites above it to `fast`
  • k-means The three groups of change counts with the smallest sum of squared deviations from their group means (exact one-dimensional k-means), named by increasing mean count
Rule that sorts the sites into the partitions of --partition-by rate-categories by their change counts

Annotation

--annotation
Value
FILE
Config key
annotation
Genome annotation (GFF3) with the coordinates of the CDSs of an --alignment file

Tree

--tree
Value
FILE
Config key
tree
Tree in Newick format

Segment trees

--segment-trees
Value
FILE
Config key
segment_trees
Trees of the genome segments, one Newick or Nexus file per segment, merged into one graph by node name

Segment alignments

--segment-alignments
Value
FILE
Config key
segment_alignments
Aligned FASTA input of the genome segments, one file per --segment-trees file, in the same order

Newick dialect

--newick-dialect Default: classic,beast
Value
NEWICK_DIALECT
Config key
newick_dialect
Values
  • classic,plain
  • classic,beast
  • classic,nhx
  • classic,mrbayes
  • enewick,plain
  • enewick,beast
  • enewick,nhx
  • enewick,mrbayes
  • rich,plain
  • rich,beast
  • rich,nhx
  • rich,mrbayes
Newick dialect of the tree inputs (the tree and the reference topology)

Allow missing sequences

--allow-missing-sequences Default: off
Config key
allow_missing_sequences
Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.

Metadata

--metadata
Value
FILE
Config key
metadata
Metadata table (CSV or TSV) with one row per sample

Metadata id columns

--metadata-id-columns Default: strain name accession
Value
COLUMN
Config key
metadata_id_columns
Candidate column name(s) holding the taxon identifier that links metadata to tree tips

Metadata delimiters

--metadata-delimiters Default: , \t ;
Value
CHAR
Config key
metadata_delimiters
Candidate field delimiter(s) for the metadata table

Date column

--date-column Default: not set
Value
COLUMN
Config key
date_column
Label of the column to be used as sampling date (auto-detected when omitted)

Date format

--date-format Default: %Y-%m-%d
Value
FORMAT
Config key
date_format
Format used to parse string sampling dates (numeric, ISO, and uncertain dates parse regardless)

Sequence length

--sequence-length Default: not set
Value
N
Config key
sequence_length
Length of the sequences, used to calculate the expected variation of the branch lengths

Alphabet

--alphabet Default: not set
Value
ALPHABET
Config key
alphabet
Values
  • nuc
  • aa
  • aa-no-stop
Alphabet of the sequences

Zero based

--zero-based Default: off
Config key
zero_based
Report sequence positions counted from 0 instead of 1.

Molecular clock

Clock rate

--clock-rate Default: not set
Value
CLOCK_RATE
Config key
clock_rate
Examples
  • 0.001
Fixed rate of the molecular clock, in substitutions per site per year

Clock rate std. dev.

--clock-std-dev Default: not set
Value
CLOCK_STD_DEV
Config key
clock_std_dev
Standard deviation of the provided clock rate estimate

Relaxed clock (slack, coupling)

--relax Default: none
Value
SLACK COUPLING
Config key
relax
Examples
  • [1,0]
Use an autocorrelated relaxed clock with the given prior strengths, for example --relax 1.0 0.5

Clock filter

--clock-filter Default: 4
Value
CLOCK_FILTER
Config key
clock_filter
Ignore tips that do not follow a loose clock: the number of interquartile ranges from the root-to-tip regression beyond which a tip is an outlier.

Allow negative rate

--allow-negative-rate Default: off
Config key
allow_negative_rate
Allow negative clock rates.

Prune filtered tips

--prune-filtered-tips Default: off
Config key
prune_filtered_tips
Remove the tips that the clock filter flags from the tree.

Prune undated tips

--prune-undated-tips Default: off
Config key
prune_undated_tips
Remove the tips without a usable date from the tree.

Keep tips

--keep-tips Default: none
Value
NAME
Config key
keep_tips
Names of tips that stay in the tree when --prune-filtered-tips or --prune-undated-tips removes tips

Keep tips file

--keep-tips-file
Value
FILE
Config key
keep_tips_file
File with names of tips that stay in the tree when --prune-filtered-tips or --prune-undated-tips removes tips, one name per line

Rooting

Reroot method

--reroot Default: not set
Value
REROOT
Config key
reroot
Values
  • least-squares Minimizes the residuals of the root-to-tip regression on the sampling dates
  • min-dev Minimizes the variance of root-to-tip distances over all tips; more robust than midpoint
  • oldest Roots at the middle of the branch above the oldest dated tip
  • midpoint Roots at the middle of the longest tip-to-tip path; uses only the two farthest tips
Cannot be combined with
--keep-root --outgroup
Method that chooses the root of the tree

Outgroup

--outgroup Default: none
Value
OUTGROUP
Config key
outgroup
Cannot be combined with
--keep-root --reroot
Examples
  • ["outgroup_tip"]
Root the tree on the branch above the most recent common ancestor of the named tips

Keep root

--keep-root Default: off
Config key
keep_root
Cannot be combined with
--outgroup --reroot
Keep the root of the input tree instead of rerooting it.

Branch lengths

Branch length mode

--branch-length-mode Default: auto
Value
BRANCH_LENGTH_MODE
Config key
branch_length_mode
Values
  • auto `input` without an alignment or when the longest input branch is longer than 0.1 substitutions per site, `marginal` otherwise
  • input Keep the branch lengths of the input tree
  • marginal Estimate the branch lengths from the alignment by marginal ancestral reconstruction
How the branch lengths of the time inference are obtained

Iterations

--max-iter Default: 2
Value
N
Config key
max_iter
Maximum number of iterations of the inference loop

No collapse short branches

--no-collapse-short-branches Default: off
Config key
no_collapse_short_branches
Disable collapsing of short internal branches.

No indels

--no-indels Default: off
Config key
no_indels
Disable indel (insertion and deletion) contributions to branch-length optimization and branch-length distributions.

Dating

Confidence

--confidence Default: off
Config key
confidence
Estimate the 90% intervals of the node dates

Max grid points

--max-grid-points Default: not set
Value
N
Config key
max_grid_points
Examples
  • 1000000
Largest number of points of one probability grid during time inference

Cross parent messages

--cross-parent-messages Default: off
Config key
cross_parent_messages
On a graph of segment trees, include the messages from the other parents in the message to a parent

Polytomies

Keep polytomies

--keep-polytomies Default: off
Config key
keep_polytomies
Keep the polytomies of the input tree

Coalescent prior

Coalescent prior

--coalescent Default: not set
Value
TC|opt|skyline
Config key
coalescent
Values
  • opt
  • skyline
Examples
  • 0.01
Coalescent prior: a fixed time scale in substitutions per site (as in TreeTime 0.x and augur, for example 0.01) or as a time (10y, 26w, 90d); opt fits a constant time scale; skyline fits a piecewise-constant one

Skyline grid points

--n-skyline Default: 20
Value
N
Config key
n_skyline
Number of grid points of the skyline coalescent model

Skyline stiffness

--skyline-stiffness Default: 2
Value
SKYLINE_STIFFNESS
Config key
skyline_stiffness
Smoothing stiffness of the skyline coalescent model

Coalescent confidence

--coalescent-confidence Default: 2
Value
COALESCENT_CONFIDENCE
Config key
coalescent_confidence
Width of the bands of the coalescent time scale Tc, in standard deviations

Gen per year

--gen-per-year Default: 50
Value
GEN_PER_YEAR
Config key
gen_per_year
Generations per year, to convert the coalescent time scale Tc into an effective population size

Substitution model

Substitution model

--model Default: infer
Value
MODEL
Config key
model
Values
  • jc69
  • k80
  • f81
  • hky85
  • t92
  • tn93
  • jtt92
  • infer Infer GTR parameters from data via Fitch parsimony substitution counts.
Cannot be combined with
--partition
Substitution model to use

Model params

--model-params Default: none
Value
MODEL_PARAMS
Config key
model_params
Cannot be combined with
--partition
Parameters for the model selected by --model, given as space-separated key=value items

Partition rates

--partition-rates Default: estimate
Value
PARTITION_RATES
Config key
partition_rates
Values
  • estimate Estimate one relative rate per partition, normalized to a site-weighted mean of 1.
  • equal Fix the relative rate of every partition at 1.
Relative substitution rates of the partitions

Gamma categories

--gamma-categories Default: not set
Value
K
Config key
gamma_categories
Number of discrete gamma rate categories of each partition (2 or more)

Shared params

--shared-params Default: none
Value
SHARED_PARAMS
Config key
shared_params
Values
  • exchange-rates Share the exchange rates W.
  • frequencies Share the equilibrium frequencies pi.
  • gamma-shape Share the gamma shape alpha.
  • none Share no model parameter.
Model parameters that the partitions with an inferred model share, as a comma-separated list

Ancestral reconstruction

Representation

--representation Default: auto
Value
REPRESENTATION
Config key
representation
Values
  • auto Let TreeTime choose the representation; it chooses sparse
  • dense Probabilities of every state at every alignment position
  • sparse Only the variable positions
Representation of the sequences on the tree

Gap fill

--gap-fill Default: only-terminal
Value
GAP_FILL
Config key
gap_fill
Values
  • only-terminal
  • all
  • none
How to handle the gap characters of the input sequences

Include leaves

--include-leaves Default: off
Config key
include_leaves
Emit reconstructed leaf (tip) sequences in addition to internal nodes.

Reconstruct tip states

--reconstruct-tip-states Default: off
Config key
reconstruct_tip_states
Same as --include-leaves --impute-missing-data: emit tip sequences with ambiguous and unknown states resolved to the most likely inferred state.

Report ambiguous

--report-ambiguous Default: off
Config key
report_ambiguous
Include branch mutations from or to the fully ambiguous state (N for nucleotides, X for amino acids).

Impute missing data

--impute-missing-data Default: off
Config key
impute_missing_data
Resolve ambiguous and unknown tip states (N and IUPAC codes such as R) to the most likely inferred state.

Output

Output all

--output-all
Value
DIR
Config key
output_all
Folder that receives the default outputs of the command

Newick annotations

--newick-annotations Default: plain
Value
NEWICK_ANNOTATIONS
Config key
newick_annotations
Values
  • plain
  • beast
  • nhx
Node comments of the Newick outputs: plain, beast, or nhx.

Output tree Newick

--output-tree-nwk
Value
FILE
Config key
output_tree_nwk
Path to output Newick tree file.

Output tree nexus

--output-tree-nexus
Value
FILE
Config key
output_tree_nexus
Path to output Nexus tree file.

Output tree auspice

--output-tree-auspice
Value
FILE
Config key
output_tree_auspice
Path to output Auspice v2 JSON tree file.

Output tree MAT protobuf

--output-tree-mat-pb
Value
FILE
Config key
output_tree_mat_pb
Path to output UShER MAT protobuf tree file.

Output tree MAT JSON

--output-tree-mat-json
Value
FILE
Config key
output_tree_mat_json
Path to output UShER MAT JSON tree file.

Output tree graph JSON

--output-tree-graph-json
Value
FILE
Config key
output_tree_graph_json
Path to output internal graph JSON tree file.

Output tree DOT

--output-tree-dot
Value
FILE
Config key
output_tree_dot
Path to output Graphviz DOT tree file.

Output files

--output-selection Default: none
Value
OUTPUT_SELECTION
Config key
output_selection
Values
  • all
  • nwk
  • nexus
  • auspice
  • mat-pb
  • mat-json
  • graph-json
  • dot
  • node-data
  • model
  • sequences
  • clock-model
  • rtt
  • dates
  • tracelog
  • coalescent
  • coalescent-json
List of outputs to produce with --output-all.

Divergence units

--divergence-units Default: mutations-per-site
Value
DIVERGENCE_UNITS
Config key
divergence_units
Values
  • mutations-per-site
  • mutations
Units of the divergence values in the augur node data and Auspice outputs.

Output node data

--output-node-data
Value
FILE
Config key
output_node_data
Path to output augur-compatible node data JSON.

Output model

--output-model
Value
FILE
Config key
output_model
Path to output the fitted substitution models as JSON.

Output sequences

--output-sequences
Value
FILE
Config key
output_sequences
Path to output the nucleotide sequences of the nodes as FASTA.

Output clock model

--output-clock-model
Value
FILE
Config key
output_clock_model
Path to output clock model JSON.

Output root-to-tip

--output-rtt
Value
FILE
Config key
output_rtt
Path to output the root-to-tip regression table.

Output dates

--output-dates
Value
FILE
Config key
output_dates
Path to output node dates TSV: calendar date and numeric date of every node, with the bounds of the 90% max posterior region with --confidence.

Output tracelog

--output-tracelog
Value
FILE
Config key
output_tracelog
Path to output the convergence values of every iteration as a table

Output coalescent

--output-coalescent
Value
FILE
Config key
output_coalescent
Path to output the coalescent time scale as a table (one row per skyline segment).

Output coalescent JSON

--output-coalescent-json
Value
FILE
Config key
output_coalescent_json
Path to output the coalescent time scale as a rich JSON document (inputs + segments).

Ambiguity threshold

--ambiguity-threshold Default: not set
Value
AMBIGUITY_THRESHOLD
Config key
ambiguity_threshold
Report every state whose posterior probability is at most this far below the probability of the most likely state.

Ambiguity outputs

--ambiguity-outputs Default: none
Value
AMBIGUITY_OUTPUTS
Config key
ambiguity_outputs
Values
  • sequences Reconstructed nucleotide FASTA
List of the outputs that carry the ambiguity report.

Tree ordering

Topology order

--topology-order Default: not set
Value
TOPOLOGY_ORDER
Config key
topology_order
Values
  • keep
  • descendant-count
  • descendant-count-reverse
  • height
  • height-reverse
  • divergence
  • divergence-reverse
  • label
  • label-reverse
  • target-order
  • target-order-reverse
Canonical topology ordering preset.

Topology order tree

--topology-order-tree
Value
FILE
Config key
topology_order_tree
Cannot be combined with
--topology-order-list
Tree whose leaf order sets the target order

Topology order list

--topology-order-list
Value
FILE
Config key
topology_order_list
Cannot be combined with
--topology-order-tree
File with leaf names in the target order, one name per line

Topology order aggregate

--topology-order-aggregate Default: mean
Value
TOPOLOGY_ORDER_AGGREGATE
Config key
topology_order_aggregate
Values
  • mean
  • median
Aggregate used to map a subtree to a target-order position.

Reproducibility

Seed

--seed Default: not set
Value
SEED
Config key
seed
Random seed