clock
Settings of treetime clock (Clock signal), with their flags, config keys, and defaults.
Infer the clock rate, assess the temporal signal and flag outliers using root-to-tip regression.
Inputs
- Tree (required): Newick or Nexus
- Metadata (required): CSV, TSV or SSV table
Input data
Tree
--tree - Value
FILE- Config key
tree
A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Value
NEWICK_DIALECT- Config key
newick_dialect- Values
classic,plainclassic,beastclassic,nhxclassic,mrbayesenewick,plainenewick,beastenewick,nhxenewick,mrbayesrich,plainrich,beastrich,nhxrich,mrbayes
A dialect is a tree structure and an annotation convention, written as <structure>,<annotations>. The structure is classic (plain labels and branch lengths), enewick (hybrid nodes such as x#H1) or rich (eNewick with support and probability fields). The annotations are plain (comments are text), beast ([&key=value]), nhx ([&&NHX:key=value]) or mrbayes ([&B name value]). For example, enewick,beast reads networks with BEAST annotations and classic,nhx reads NHX trees. TreeTime reads trees only, so a network input is an error.
Metadata
--metadata - Value
FILE- Config key
metadata
--metadata-id-columns names the column that links a row to a tree tip. The other columns hold the data of the sample, such as its sampling date or its traits. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Value
COLUMN- Config key
metadata_id_columns
The first listed column that is present in the header is used. Matching is case-insensitive.
- Value
CHAR- Config key
metadata_delimiters
The delimiter actually present in the file is used. Defaults to comma, tab, and semicolon.
- Value
COLUMN- Config key
date_column
- Value
FORMAT- Config key
date_format
Molecular clock
- Value
CLOCK_FILTER- Config key
clock_filter
0 switches the filter off.
- Config key
allow_negative_rate
By default, rates are forced to be positive. For trees with little temporal signal, removing this restriction gives essentially mid-point rooting.
- Config key
prune_filtered_tips
The clock filter flags a tip and leaves it in the tree by default. With this flag, the run removes the flagged tips after the filter: timetree before the time inference, and clock before the final clock fit. Every output leaves the removed tips out, and a run warning names them. The tips that --keep-tips and --keep-tips-file name stay in the tree, flagged. Requires the clock filter (--clock-filter above 0).
augur refine with a clock filter (--clock-filter-iqd) removes the flagged tips and also the tips without a usable date. To remove the same tips, add --prune-undated-tips.
- Config key
prune_undated_tips
A tip has no usable date when the metadata gives no date for it, or a value that is not a date, a numeric date, or a date range. Such a tip stays in the tree by default: timetree infers its date from the tree, and the clock fit leaves it out. With this flag, the run removes these tips: timetree before the time inference, and clock before the final clock fit. Every output leaves the removed tips out, and a run warning names them. The tips that --keep-tips and --keep-tips-file name stay in the tree.
Together with --prune-filtered-tips, the run removes the same tips as augur refine with a clock filter (--clock-filter-iqd).
- Value
NAME- Config key
keep_tips
Accepts several names, separated by commas or spaces. A kept flagged tip stays flagged: the clock fit leaves it out, and timetree dates it from the tree, as it dates a kept tip without a usable date. Names that match no tip are ignored.
Keep tips file
--keep-tips-file - Value
FILE- Config key
keep_tips_file
Surrounding whitespace is trimmed and empty lines are ignored. Names that match no tip are ignored, so the file can list samples of several datasets. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file. Use - to read uncompressed input from standard input (stdin).
Rooting
- Value
REROOT- Config key
reroot- Values
least-squaresMinimizes the residuals of the root-to-tip regression on the sampling datesmin-devMinimizes the variance of root-to-tip distances over all tips; more robust than midpointoldestRoots at the middle of the branch above the oldest dated tipmidpointRoots at the middle of the longest tip-to-tip path; uses only the two farthest tips
- Cannot be combined with
- --keep-root --outgroup
least-squares and oldest use the sampling dates; min-dev and midpoint use only the branch lengths, root once on the input branch lengths, and count every tip. Without a rooting setting the tree is rerooted by least-squares. Use --outgroup to root on named tips, or --keep-root to keep the input root.
- Value
OUTGROUP- Config key
outgroup- Cannot be combined with
- --keep-root --reroot
- Examples
["outgroup_tip"]
With one tip, the root is placed on the branch leading to that tip.
- Config key
keep_root- Cannot be combined with
- --outgroup --reroot
Output
Output all
--output-all - Value
DIR- Config key
output_all
Writes the default outputs of the command as <dir>/<command>.<ext>. --output-selection restricts the outputs that the folder receives. The per-file flags (--output-*) override or supplement the files of the folder.
An output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails.
Every output path follows these rules. A path that ends in .gz, .bz2, .xz, or .zst writes a compressed file. The compression level is 2, unless the environment variable GZ_COMPRESSION, BZ2_COMPRESSION, XZ_COMPRESSION, or ZST_COMPRESSION sets another level. .gz, .xz, and .zst compress with all --jobs threads. .bz2 compresses with one thread and is much slower to write and to read than the other formats. The path - of a per-file flag writes the output uncompressed to standard output. Missing parent folders are created.
Table outputs choose the delimiter by the extension of their path: .tsv writes tabs and .csv commas, also before a compression suffix (dates.tsv.gz); - writes tabs to standard output. Default names use .tsv.
With several --alignment files, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data of ancestral, Auspice, UShER MAT, Nexus, and Newick with --newick-annotations other than plain. Files are numbered 1, 2, ... in the order of the --alignment list. Their default names carry the number after the command name (<dir>/<command>.1.<ext>), and the file name of a per-file flag for such an output must contain {alignment}, which is replaced by the number. Other tree outputs with {alignment} in their file name are also written once per file.
The outputs written once per CDS, such as the reconstructed amino-acid sequences, take the placeholder {cds} or %GENE in the file name of their per-file flag, which is replaced by the name of the CDS. The placeholder is required when more than one CDS is reconstructed; folder names are used as given.
- Value
NEWICK_ANNOTATIONS- Config key
newick_annotations- Values
plainbeastnhx
plain, beast, or nhx.plain writes no comments. beast writes a comment such as [&mutations="A45G,G136T",date=2016.45] after each node, and nhx writes the same values as [&&NHX:key=value]. The comments hold the mutations on the branch above the node, its date, and its inferred trait value, as far as the command infers them. Nexus outputs always carry beast comments, which FigTree reads.
Output tree Newick
--output-tree-nwk - Value
FILE- Config key
output_tree_nwk
--newick-annotations sets the node comments.
Output tree nexus
--output-tree-nexus - Value
FILE- Config key
output_tree_nexus
The nodes carry BEAST comments ([&mutations="A45G,G136T",date=2016.45]).
Output tree auspice
--output-tree-auspice - Value
FILE- Config key
output_tree_auspice
Output tree MAT protobuf
--output-tree-mat-pb - Value
FILE- Config key
output_tree_mat_pb
Output tree MAT JSON
--output-tree-mat-json - Value
FILE- Config key
output_tree_mat_json
Output tree graph JSON
--output-tree-graph-json - Value
FILE- Config key
output_tree_graph_json
Output tree DOT
--output-tree-dot - Value
FILE- Config key
output_tree_dot
- Value
OUTPUT_SELECTION- Config key
output_selection- Values
allnwknexusauspicemat-pbmat-jsongraph-jsondotclock-modelrttrtt-chart
--output-all.Restricts which outputs --output-all writes. Special value all expands to every output available for this command. Requires --output-all. Per-file flags are always honored regardless of this selection.
A selected output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails. An output that the settings rule out fails in both forms, for example the sequences of timetree --branch-length-mode input.
Output clock model
--output-clock-model - Value
FILE- Config key
output_clock_model
Output root-to-tip
--output-rtt - Value
FILE- Config key
output_rtt
One row per sample: the date the regression used, the root-to-tip distance it regressed on, the date the clock model predicts from that distance, and whether the clock filter excluded the sample.
Output root-to-tip chart
--output-rtt-chart - Value
FILE- Config key
output_rtt_chart
The chart plots the root-to-tip divergence of each dated sample against its date, with the least-squares fit, its extrapolation to the root, and the samples that the clock filter excluded. It states the clock rate, the root date and R² of the fit. The extension chooses the image format: .svg, .png or .pdf.
Tree ordering
- Value
TOPOLOGY_ORDER- Config key
topology_order- Values
keepdescendant-countdescendant-count-reverseheightheight-reversedivergencedivergence-reverselabellabel-reversetarget-ordertarget-order-reverse
Topology order tree
--topology-order-tree - Value
FILE- Config key
topology_order_tree- Cannot be combined with
- --topology-order-list
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-list, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Topology order list
--topology-order-list - Value
FILE- Config key
topology_order_list- Cannot be combined with
- --topology-order-tree
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-tree, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Value
TOPOLOGY_ORDER_AGGREGATE- Config key
topology_order_aggregate- Values
meanmedian