Command-line reference
Every command, flag, and default of the treetime command-line program.
This page is generated from the help text of the
treetimeprogram. Report issues at https://github.com/neherlab/treetime/issues
This document contains the automatically generated reference documentation for command-line arguments of the latest version of TreeTime CLI.
If you have TreeTime CLI installed, you can type treetime --help to read the latest documentation for your installed version of TreeTime. To generate this document in markdown format, run treetime help-markdown > reference.md
Command Overview:
treetime↴treetime timetree↴treetime ancestral↴treetime clock↴treetime mugration↴treetime homoplasy↴treetime optimize↴treetime prune↴treetime pipeline↴treetime schema↴treetime schema write↴treetime completions↴treetime help-markdown↴
treetime
Maximum-likelihood phylodynamic inference
Repository: https://github.com/neherlab/treetime Publication: https://academic.oup.com/ve/article/4/1/vex042/4794731
Usage:
treetime [OPTIONS] <COMMAND>Exit status: 0 on success, 1 on failure, 2 on a usage error (invalid flags or config file)
Subcommands:
timetree— Infer a time-scaled tree from a tree, the sampling dates of its tips, and optionally an alignmentancestral— Reconstruct ancestral sequences and map the mutations to the branches of a treeclock— Fit a molecular clock by root-to-tip regression, and reroot the tree for the best clock signalmugration— Reconstruct the ancestral states of a discrete trait, such as location or host, and fit a model of its changeshomoplasy— Reconstruct ancestral sequences and count homoplasies, mutations that occur more than once in a treeoptimize— Optimize the branch lengths of a tree for the likelihood of an alignmentprune— Collapse short branches and branches without mutations, and remove named nodes from a treepipeline— Run several analysis commands in order from one config fileschema— Write the JSON schemas of the config files and of the TreeTime data typescompletions— Print the shell completions of TreeTimehelp-markdown— Print the command-line reference in Markdown
Options:
-
--verbosity <VERBOSITY>— Verbosity level of the console outputDefault value:
warnPossible values:
off,error,warn,info,debug,trace -
--silent— Disable all console output, as--verbosity=offdoes -
-v,--verbose— Make the console output more verbose; repeat the flag (-vv) for more -
-q,--quiet— Make the console output quieter; repeat the flag (-qq) for less -
--no-progress— Disable the progress bar -
--color <WHEN>— When to color error messages, help, and the log:autocolors them when the output is a terminal and theNO_COLORenvironment variable is not setDefault value:
autoPossible values:
auto,always,never
treetime timetree
Infer a time-scaled tree from a tree, the sampling dates of its tips, and optionally an alignment
Usage:
treetime timetree --tree <FILE> --metadata <FILE> [(--alignment <FILE>)... | --sequence-length <N>] (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime timetree --config <FILE> [OPTIONS]Examples:
treetime timetree -t tree.nwk -m metadata.tsv -a aln.fasta.xz -O resultstreetime timetree -t tree.nwk -m metadata.tsv --sequence-length 10700 --coalescent opt --confidence -O resultstreetime timetree --config timetree.yaml -O resultsOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-a,--alignment <FILE>— Aligned FASTA inputEach
--alignmentfile is numbered by its position in the list (1, 2, …) and is one partition, unless--partitionentries ofancestral,optimize, ortimetreesplit it into several. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin);-may appear at most once. -
--partition <ENTRY>— One partition: a set of sites of one--alignmentfile with its own substitution model; repeat the flag for each partitionWithout
--partition, each--alignmentfile is one partition with the model of--model. An entry is a YAML or JSON map with the keysname(the name of the partition in outputs and messages),alignment(the number of its--alignmentfile, 1, 2, …; required with two or more files),sites(a list of site ranges, numbered from 1:a,a-b, ora-b\kfor every k-th site from a to b),model(the substitution model, defaultinfer) andmodel_params(thekey=valueitems of--model-paramsfor that model). Each entry carries its own model, so--modeland--model-paramscannot be used together with--partition. Every alignment needs at least one entry, and every site belongs to exactly one entry. An entry withoutsitestakes the sites that the other entries of its alignment leave; one entry per alignment can leave outsites. Write site ranges in single quotes or without quotes, because YAML reads a backslash in double quotes as an escape. Example:--partition "{name: cp1, sites: ['101-1600\3']}" --partition "{name: cp2, sites: ['102-1600\3']}" --partition "{name: cp3, sites: ['103-1600\3'], model: hky85, model_params: ['kappa=4']}" --partition "{name: noncoding}". -
--partition-by <SCHEME>— Build the partitions of each--alignmentfile from a scheme instead of--partitionentriescodon-positionsmakes the partitionscp1,cp2andcp3from codon positions 1, 2 and 3 of the CDSs of--annotation, andnoncodingfrom the other sites.genesmakes one partition per CDS of--annotation, named by the CDS, andnoncodingfrom the other sites. Both need one--annotationfile per--alignmentfile, matched in list order, whose##sequence-regionruns from 1 to the length of its alignment, because annotation positions are alignment columns only for an alignment on that reference. Where CDSs overlap, the longest CDS owns the shared sites and gives them their codon positions; a CDS whose sites all belong to longer CDSs gets no partition.rate-categoriescounts the changes at each site in a Fitch reconstruction on the input tree and puts the sites into the partitionsslow,mediumandfastby the rule of--rate-category-rule; it uses no annotation. Every partition gets the model of--modeland--model-params; with the defaultinfer, each partition fits its own model, subject to--shared-params. With two or more--alignmentfiles, the partition names start with the number of the file, for example2/cp1. A scheme needs the alphabetnucand must make at least two partitions over all files.Possible values:
codon-positions: Codon positions 1, 2 and 3 of every CDS of--annotationas the partitionscp1,cp2andcp3, and the other sites asnoncodinggenes: One partition per CDS of--annotation, named by the CDS, and the other sites asnoncodingrate-categories: The partitionsslow,mediumandfastfrom the number of changes at each site in a Fitch reconstruction on the input tree, by the rule of--rate-category-rule
-
--rate-category-rule <RULE>— Rule that sorts the sites into the partitions of--partition-by rate-categoriesby their change countschange-countsputs sites without changes intoslow, sites with one change intomedium, and sites with two or more changes intofast.median-splitputs sites without changes intoslow, and splits the changed sites at the median of their counts: at or below the median intomedium, above it intofast.k-meanssplits all counts into the three groups with the smallest sum of squared deviations from their means, named by increasing mean count. Empty partitions are left out.[default: change-counts]
Possible values:
change-counts:slowfor sites without changes,mediumfor one change,fastfor two or moremedian-split:slowfor sites without changes; changed sites at or below the median count of the changed sites go tomedium, sites above it tofastk-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
-
--annotation <FILE>— Genome annotation (GFF3) with the coordinates of the CDSs of an--alignmentfileWith
--partition-by codon-positionsorgenes, give one file per--alignmentfile, matched in list order: the scheme builds the partitions of each alignment from the CDSs of its annotation. Inancestral, the file also supplies the annotations of the augur node data and, without--cds-selection, the CDSs that--translationsreconstructs;--translationstakes one--alignmentfile and one annotation file. TreeTime reads the coding regions from the CDS rows, which need strand+or-and phase 0, 1 or 2. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-trees <FILE>— Trees of the genome segments, one Newick or Nexus file per segment, merged into one graph by node nameEvery node of every tree needs a name, unique within its tree; a name that occurs in several trees is one node of the graph. A node that a segment only passes through stays in that segment’s tree as a node with one child. An edge shared by several trees gets the mean of their branch lengths. Use instead of
--tree, together with--segment-alignments. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-alignments <FILE>— Aligned FASTA input of the genome segments, one file per--segment-treesfile, in the same orderUse instead of
--alignment. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
--allow-missing-sequences— Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.Without this flag the run aborts when more than one third of the tips lack a sequence, because the alignment may not belong to the tree. Useful for per-CDS translations, where some samples have no peptide for a given CDS.
-
-m,--metadata <FILE>— Metadata table (CSV or TSV) with one row per sample--metadata-id-columnsnames 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.zstreads a compressed file. -
--metadata-id-columns <COLUMN>— Candidate column name(s) holding the taxon identifier that links metadata to tree tipsThe first listed column that is present in the header is used. Matching is case-insensitive.
Default values:
strain,name,accession -
--metadata-delimiters <CHAR>— Candidate field delimiter(s) for the metadata tableThe delimiter actually present in the file is used. Defaults to comma, tab, and semicolon.
Default values:
,,,; -
--date-column <COLUMN>— Label of the column to be used as sampling date (auto-detected when omitted) -
--date-format <FORMAT>— Format used to parse string sampling dates (numeric, ISO, and uncertain dates parse regardless)Default value:
%Y-%m-%d -
--sequence-length <N>— Length of the sequences, used to calculate the expected variation of the branch lengthsRequired without
--alignment, and applies only then: with an alignment, the run takes the length from the alignment. -
--alphabet <ALPHABET>— Alphabet of the sequencesnuc(default): nucleotides A, C, G and T, with the IUPAC ambiguity codes andNfor an unknown base.aa: the 20 amino acids and the stop codon*as a 21st state, withXfor an unknown residue.aa-no-stop: the 20 amino acids without a state for the stop codon.Possible values:
nuc,aa,aa-no-stop -
--zero-based— Report sequence positions counted from 0 instead of 1.Applies to the mutations in the comments of Newick and Nexus trees and to the positions of the homoplasy report. Auspice JSON, augur node data, and UShER MAT outputs count from 1, as their formats require. An input table with positions, such as
--drms, is always counted from 1. -
--clock-rate <CLOCK_RATE>— Fixed rate of the molecular clock, in substitutions per site per yearWithout this setting, the run estimates the rate.
-
--clock-std-dev <CLOCK_STD_DEV>— Standard deviation of the provided clock rate estimateApplies only with
--confidence, whose date intervals include the clock rate uncertainty. -
--relax <SLACK>— Use an autocorrelated relaxed clock with the given prior strengths, for example--relax 1.0 0.5SLACK is the strength of the Gaussian prior on the rate deviation of each branch, and COUPLING the strength of the coupling of the rates of parent and child branches. Values around 1.0 give weak priors; larger values constrain the rate deviations more strongly. A COUPLING of 0 (
--relax 1.0 0) gives an uncorrelated clock. -
--clock-filter <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.0 switches the filter off.
Default value:
4 -
--allow-negative-rate— Allow negative clock rates.By default, rates are forced to be positive. For trees with little temporal signal, removing this restriction gives essentially mid-point rooting.
-
--prune-filtered-tips— Remove the tips that the clock filter flags from the tree.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.
-
--prune-undated-tips— Remove the tips without a usable date from the tree.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).
-
--keep-tips <NAME>— Names of tips that stay in the tree when —prune-filtered-tips or —prune-undated-tips removes tipsAccepts 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 <FILE>— File with names of tips that stay in the tree when —prune-filtered-tips or —prune-undated-tips removes tips, one name per lineSurrounding 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.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--reroot <REROOT>— Method that chooses the root of the treeleast-squaresandoldestuse the sampling dates;min-devandmidpointuse 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.Possible values:
least-squares: Minimizes the residuals of the root-to-tip regression on the sampling datesmin-dev: Minimizes the variance of root-to-tip distances over all tips; more robust than midpointoldest: Roots at the middle of the branch above the oldest dated tipmidpoint: Roots at the middle of the longest tip-to-tip path; uses only the two farthest tips
-
--outgroup <OUTGROUP>— Root the tree on the branch above the most recent common ancestor of the named tipsWith one tip, the root is placed on the branch leading to that tip.
-
--keep-root— Keep the root of the input tree instead of rerooting it -
--branch-length-mode <BRANCH_LENGTH_MODE>— How the branch lengths of the time inference are obtainedautokeeps the input branch lengths without an alignment, and also when the longest input branch is longer than 0.1 substitutions per site, because the re-estimated branch lengths are accurate only at short evolutionary distances; otherwise it re-estimates them asmarginaldoes. When no input branch has a length,autochoosesmarginal. The run logs the choice.Default value:
autoPossible values:
auto:inputwithout an alignment or when the longest input branch is longer than 0.1 substitutions per site,marginalotherwiseinput: Keep the branch lengths of the input treemarginal: Estimate the branch lengths from the alignment by marginal ancestral reconstruction
-
--max-iter <N>— Maximum number of iterations of the inference loopPolytomy resolution and coalescent models of the time inference need at least 2 iterations.
Default value:
2 -
--confidence— Estimate the 90% intervals of the node datesRuns a final marginal round of the time inference after the iterations and writes the 90% interval of every dated node. The intervals include the clock rate uncertainty when one is known:
--clock-std-devfor a given rate, or the Gaussian estimate of an estimated rate. The rate uncertainty is added by inferring the dates again at the rate plus and minus one standard deviation and combining both parts in quadrature. -
--max-grid-points <N>— Largest number of points of one probability grid during time inferenceA run stops with an error when a grid would need more points. The value bounds single grids, not the total memory of a run. When unset, the run takes the limit of the app or server that runs it, otherwise 1000000.
-
--keep-polytomies— Keep the polytomies of the input treeWithout this flag, each polytomy is resolved into binary mergers by the node dates. The resolution is stochastic: the run logs the seed it draws, and
--seedreproduces the run. -
--cross-parent-messages— On a graph of segment trees, include the messages from the other parents in the message to a parentA node with several parents sends each parent its subtree by default, and one sweep of message passing suffices. With this flag, the message to a parent also carries the messages that the other parents sent in the previous sweep, and the sweeps repeat until the node times settle. Applies only with
--segment-trees. -
--no-collapse-short-branches— Disable collapsing of short internal branches.By default, before the time inference, internal edges shorter than 0.1/L (L is the number of sites of all alignments) with no substitution in the marginal reconstruction are contracted, as in optimize and TreeTime 0.x. The substitutions of a contracted edge move to its child edges, and the nodes it joined become one polytomy. Edges above internal nodes with a date are kept. When set, such edges are kept.
-
--coalescent <TC|opt|skyline>— 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 oneA time is a positive number directly followed by the unit y (years), w (weeks) or d (days). A time scale in substitutions per site is converted to years with the clock rate of each iteration. Without this setting the node times have no coalescent prior.
-
--model-params <MODEL_PARAMS>— Parameters for the model selected by--model, given as space-separatedkey=valueitemsThe parameters apply to the model of every partition; each
--alignmentfile is one partition. In commands with--partition, each entry carries its own model and parameters, so--model-paramsis an error next to entries. Keys:mu(the overall substitution rate, every named model),kappa(the transition to transversion ratio ofk80,hky85andt92),kappa1andkappa2(the rate ratios oftn93),pi(the equilibrium frequencies off81,hky85andtn93: comma-separated numbers, one frequency per state of the alphabet in its order, for example A, C, G and T for nucleotides, normalized to sum 1; alsopis,Pi,Pis) andpi_GC(the GC content oft92, between 0 and 1). A key left out keeps its default. Example:--model hky85 --model-params kappa=0.2 pis=0.25,0.25,0.25,0.25. -
--model <MODEL>— Substitution model to useinferinfers a model from the data of each partition; each--alignmentfile is one partition. Alternatively, name the model type. If the named model takes parameters, use--model-paramsto set them. The model applies to every file. In commands with--partition, each entry carries its own model, so--modelis an error next to entries.[default: infer]
Possible values:
infer: Infer GTR parameters from data via Fitch parsimony substitution countsjc69k80f81hky85t92tn93jtt92
-
--partition-rates <PARTITION_RATES>— Relative substitution rates of the partitionsEach
--alignmentfile is one partition, or each--partitionentry when there are entries. With two or more partitions, all partitions share the branch lengths, and each partition has one relative rate that scales them for the sites of that partition.estimatefits the rate of each partition with the rest of its substitution model fixed (a partition with--model inferstarts from its fitted rate), then divides all rates by their mean weighted by the number of sites of each partition, so that this mean is 1. The branch lengths are then expected substitutions per site, averaged over all sites of all partitions.equalfixes the rate of every partition at 1.The setting applies only with two or more partitions.
[default: estimate]
Possible values:
estimate: Estimate one relative rate per partition, normalized to a site-weighted mean of 1equal: Fix the relative rate of every partition at 1
-
--gamma-categories <K>— Number of discrete gamma rate categories of each partition (2 or more)Sites of one partition evolve at different speeds. With this setting, every partition gets K rate categories of equal probability whose rates are the means of K equal-probability slices of a gamma distribution with mean 1 and shape alpha (Yang 1994). The likelihood of a site is the mean of its likelihoods under the K rates, and the ancestral states are weighted by the probability of each rate at the site. Each partition estimates its own alpha by maximum likelihood between 0.02 and 100, unless the partitions share
gamma-shape(--shared-params). Without the setting, all sites of a partition share one rate. Memory grows about K-fold, runtime more: with 4 categories, optimize on the example datasets takes 7 to 25 times as long, most on large trees in sparse mode. 4 categories are the common choice. The setting applies to marginal reconstructions only: not with--method-anc parsimonyand not with--branch-length-mode input. -
--shared-params <SHARED_PARAMS>— Model parameters that the partitions with an inferred model share, as a comma-separated listexchange-rates: one set of exchange rates W for all these partitions. Each partition scales W so that its rate matrix has mean rate 1 under its own frequencies, so with different frequencies the stored W of the partitions differ by a factor.frequencies: one set of equilibrium frequencies.gamma-shape: one gamma shape alpha; needs--gamma-categories.none: every partition fits its own model; stands alone. The fit of the shared parameters uses the substitutions of all sharing partitions together. A partition with a named model keeps the parameters of its model. Every partition keeps its own relative rate (--partition-rates), and all partitions share the tree and the branch lengths.Default: with
--partition-by genesorrate-categories, the partitions shareexchange-ratesandfrequencies, and alsogamma-shapewith--gamma-categories, because genes of one genome share the mutation process and rate buckets differ only in speed. With--partition-by codon-positions,--partitionentries, or one partition per--alignmentfile, they share nothing, because codon positions differ in their pattern of change. The setting applies only with two or more partitions whose model isinfer.Possible values:
exchange-rates: Share the exchange rates Wfrequencies: Share the equilibrium frequencies pigamma-shape: Share the gamma shape alphanone: Share no model parameter
-
--representation <REPRESENTATION>— Representation of the sequences on the treeThe dense representation stores the probabilities of every state at every alignment position of each node; the sparse representation stores only the variable positions. Dense is more accurate when branches are long and many sites change, but uses more memory.
[default: auto]
Possible values:
auto: Let TreeTime choose the representation; it chooses sparsedense: Probabilities of every state at every alignment positionsparse: Only the variable positions
-
--gap-fill <GAP_FILL>— How to handle the gap characters of the input sequencesonly-terminal(default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (NorX).all: replace every gap with the unknown character.none: keep every gap.Default value:
only-terminalPossible values:
only-terminal,all,none -
--include-leaves— Emit reconstructed leaf (tip) sequences in addition to internal nodes -
--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— Include branch mutations from or to the fully ambiguous state (Nfor nucleotides,Xfor amino acids).By default these mutations are omitted from the branch mutations of the Newick and Nexus annotations, the Auspice JSON, and the
mutsandaa_mutslists of augur node data. Other ambiguity codes, such asKorR, are always reported. The flag does not affect the MAT outputs, which storeNas missing data and never contain these mutations. -
--impute-missing-data— Resolve ambiguous and unknown tip states (Nand IUPAC codes such asR) to the most likely inferred state.Gaps are left as deletions, because they are inferred structure, not missing data. Changes that involve ambiguous characters on terminal branches then disappear from the branch mutations. Only defined for marginal reconstruction; a no-op with a warning under
--method-anc=parsimony. -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,node-data,model,sequences,clock-model,rtt,dates,tracelog,coalescent,coalescent-json -
--no-indels— Disable indel (insertion and deletion) contributions to branch-length optimization and branch-length distributions.When set, branch-length optimization uses the substitution-only likelihood, and the branch distributions of the time inference exclude the Poisson indel term. This matches standard phylogenetic tools (RAxML, IQ-TREE, PhyML, BEAST) and TreeTime 0.x. By default, indels count.
-
--divergence-units <DIVERGENCE_UNITS>— Units of the divergence values in the augur node data and Auspice outputs.mutations-per-site(default): branch divergence as substitutions per site.mutations: count of reconstructed substitutions per branch that change the state: gaps,N, and ambiguity codes compatible with the parent state do not count.mutationsrequires reconstructed sequences, so it does not work with input branch lengths (--branch-length-mode=input).Default value:
mutations-per-sitePossible values:
mutations-per-site,mutations -
--output-node-data <FILE>— Path to output augur-compatible node data JSON.Contains per-node dates, branch lengths, clock model parameters, confidence intervals, and divergence metrics. The output is compatible with augur export v2 —node-data for Nextstrain pipeline integration.
-
--output-model <FILE>— Path to output the fitted substitution models as JSON -
--output-sequences <FILE>— Path to output the nucleotide sequences of the nodes as FASTA.Holds the reconstructed sequences of the internal nodes, and of the tips with
--include-leavesor--reconstruct-tip-states;--impute-missing-dataresolves ambiguous tip states. -
--output-clock-model <FILE>— Path to output clock model JSON -
--output-rtt <FILE>— Path to output the root-to-tip regression table.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-dates <FILE>— 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 <FILE>— Path to output the convergence values of every iteration as a table -
--output-coalescent <FILE>— Path to output the coalescent time scale as a table (one row per skyline segment).Written when a coalescent prior is set with
--coalescent. A fixed time scale writes one band-less segment over the tree span. -
--output-coalescent-json <FILE>— Path to output the coalescent time scale as a rich JSON document (inputs + segments).Written when a coalescent model is set.
-
--ambiguity-threshold <AMBIGUITY_THRESHOLD>— Report every state whose posterior probability is at most this far below the probability of the most likely state.The value is a difference of probabilities from 0 to 1. With 0, the report names only the states that tie with the most likely state. RAxML-NG uses 0.5 divided by the number of states, for example 0.125 for nucleotides. The report is off when the value is not set.
The reconstructed FASTA writes a position with more than one reported state as the IUPAC code of these states, or
Nfor all four nucleotides. Internal nodes have a report at every position, leaves only at the positions that--impute-missing-dataimputes. -
--ambiguity-outputs <AMBIGUITY_OUTPUTS>— List of the outputs that carry the ambiguity report.Without this list, every output of the run that can carry the report carries it. Requires
--ambiguity-threshold.Possible values:
sequences: Reconstructed nucleotide FASTA
-
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
--seed <SEED>— Random seedWithout a seed, a run with a random step draws one and logs it, so the run can be reproduced.
-
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread -
--n-skyline <N>— Number of grid points of the skyline coalescent modelApplies only to
--coalescent skyline. Sets how many piecewise linear segments model Tc(t) over time. Must be at least 2.[default: 20]
-
--skyline-stiffness <SKYLINE_STIFFNESS>— Smoothing stiffness of the skyline coalescent modelPenalizes log-fold-changes of the coalescent time scale Tc between adjacent skyline segments: with z = ln Tc, the objective adds
(stiffness/2) * Σ (ln(Tc_{i+1}/Tc_i))^2. Because it acts on log Tc, the stiffness is dimensionless and scale-independent. Larger values enforce a smoother Tc(t). Applies only to--coalescent skyline.[default: 2.0]
-
--coalescent-confidence <COALESCENT_CONFIDENCE>— Width of the bands of the coalescent time scale Tc, in standard deviationsApplies only to the inferred coalescent priors (
--coalescent optand--coalescent skyline). The band spansTc * exp(±confidence * σ), whereσis the standard deviation ofln Tcfrom the coalescent likelihood curvature. A fixed time scale is not inferred and therefore has no band.[default: 2.0]
-
--gen-per-year <GEN_PER_YEAR>— Generations per year, to convert the coalescent time scale Tc into an effective population sizeThe coalescent output reports an effective population size
N_e = Tc * gen_per_year. Tc is already in calendar years, so this factor rescales it into generation units, the standard axis of a skyline plot. Only affects the reportedN_e; it does not enter the inference. Applies only with--coalescent.[default: 50.0]
treetime ancestral
Reconstruct ancestral sequences and map the mutations to the branches of a tree
With marginal reconstruction, each branch of the Nexus trees, and of the Newick trees with --newick-annotations beast or nhx, carries its mutations as a comment, like A45G,G136T, with 1-based positions.
Usage:
treetime ancestral --tree <FILE> (--alignment <FILE>)... (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime ancestral --config <FILE> [OPTIONS]Examples:
treetime ancestral -t tree.nwk -a aln.fasta.xz -O resultstreetime ancestral -t tree.nwk -a ha.fasta.xz -a na.fasta.xz --reconstruct-tip-states --output-sequences 'sequences-{alignment}.fasta'treetime ancestral -t tree.nwk -a aln.fasta.xz --annotation genome.gff3 --translations 'translations/{cds}.fasta' -O resultsOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-a,--alignment <FILE>— Aligned FASTA inputEach
--alignmentfile is numbered by its position in the list (1, 2, …) and is one partition, unless--partitionentries ofancestral,optimize, ortimetreesplit it into several. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin);-may appear at most once. -
--partition <ENTRY>— One partition: a set of sites of one--alignmentfile with its own substitution model; repeat the flag for each partitionWithout
--partition, each--alignmentfile is one partition with the model of--model. An entry is a YAML or JSON map with the keysname(the name of the partition in outputs and messages),alignment(the number of its--alignmentfile, 1, 2, …; required with two or more files),sites(a list of site ranges, numbered from 1:a,a-b, ora-b\kfor every k-th site from a to b),model(the substitution model, defaultinfer) andmodel_params(thekey=valueitems of--model-paramsfor that model). Each entry carries its own model, so--modeland--model-paramscannot be used together with--partition. Every alignment needs at least one entry, and every site belongs to exactly one entry. An entry withoutsitestakes the sites that the other entries of its alignment leave; one entry per alignment can leave outsites. Write site ranges in single quotes or without quotes, because YAML reads a backslash in double quotes as an escape. Example:--partition "{name: cp1, sites: ['101-1600\3']}" --partition "{name: cp2, sites: ['102-1600\3']}" --partition "{name: cp3, sites: ['103-1600\3'], model: hky85, model_params: ['kappa=4']}" --partition "{name: noncoding}". -
--partition-by <SCHEME>— Build the partitions of each--alignmentfile from a scheme instead of--partitionentriescodon-positionsmakes the partitionscp1,cp2andcp3from codon positions 1, 2 and 3 of the CDSs of--annotation, andnoncodingfrom the other sites.genesmakes one partition per CDS of--annotation, named by the CDS, andnoncodingfrom the other sites. Both need one--annotationfile per--alignmentfile, matched in list order, whose##sequence-regionruns from 1 to the length of its alignment, because annotation positions are alignment columns only for an alignment on that reference. Where CDSs overlap, the longest CDS owns the shared sites and gives them their codon positions; a CDS whose sites all belong to longer CDSs gets no partition.rate-categoriescounts the changes at each site in a Fitch reconstruction on the input tree and puts the sites into the partitionsslow,mediumandfastby the rule of--rate-category-rule; it uses no annotation. Every partition gets the model of--modeland--model-params; with the defaultinfer, each partition fits its own model, subject to--shared-params. With two or more--alignmentfiles, the partition names start with the number of the file, for example2/cp1. A scheme needs the alphabetnucand must make at least two partitions over all files.Possible values:
codon-positions: Codon positions 1, 2 and 3 of every CDS of--annotationas the partitionscp1,cp2andcp3, and the other sites asnoncodinggenes: One partition per CDS of--annotation, named by the CDS, and the other sites asnoncodingrate-categories: The partitionsslow,mediumandfastfrom the number of changes at each site in a Fitch reconstruction on the input tree, by the rule of--rate-category-rule
-
--rate-category-rule <RULE>— Rule that sorts the sites into the partitions of--partition-by rate-categoriesby their change countschange-countsputs sites without changes intoslow, sites with one change intomedium, and sites with two or more changes intofast.median-splitputs sites without changes intoslow, and splits the changed sites at the median of their counts: at or below the median intomedium, above it intofast.k-meanssplits all counts into the three groups with the smallest sum of squared deviations from their means, named by increasing mean count. Empty partitions are left out.[default: change-counts]
Possible values:
change-counts:slowfor sites without changes,mediumfor one change,fastfor two or moremedian-split:slowfor sites without changes; changed sites at or below the median count of the changed sites go tomedium, sites above it tofastk-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
-
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-trees <FILE>— Trees of the genome segments, one Newick or Nexus file per segment, merged into one graph by node nameEvery node of every tree needs a name, unique within its tree; a name that occurs in several trees is one node of the graph. A node that a segment only passes through stays in that segment’s tree as a node with one child. An edge shared by several trees gets the mean of their branch lengths. Use instead of
--tree, together with--segment-alignments. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-alignments <FILE>— Aligned FASTA input of the genome segments, one file per--segment-treesfile, in the same orderUse instead of
--alignment. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
--allow-missing-sequences— Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.Without this flag the run aborts when more than one third of the tips lack a sequence, because the alignment may not belong to the tree. Useful for per-CDS translations, where some samples have no peptide for a given CDS.
-
--alphabet <ALPHABET>— Alphabet of the sequencesnuc(default): nucleotides A, C, G and T, with the IUPAC ambiguity codes andNfor an unknown base.aa: the 20 amino acids and the stop codon*as a 21st state, withXfor an unknown residue.aa-no-stop: the 20 amino acids without a state for the stop codon.Possible values:
nuc,aa,aa-no-stop -
--zero-based— Report sequence positions counted from 0 instead of 1.Applies to the mutations in the comments of Newick and Nexus trees and to the positions of the homoplasy report. Auspice JSON, augur node data, and UShER MAT outputs count from 1, as their formats require. An input table with positions, such as
--drms, is always counted from 1. -
--annotation <FILE>— Genome annotation (GFF3) with the coordinates of the CDSs of an--alignmentfileWith
--partition-by codon-positionsorgenes, give one file per--alignmentfile, matched in list order: the scheme builds the partitions of each alignment from the CDSs of its annotation. Inancestral, the file also supplies the annotations of the augur node data and, without--cds-selection, the CDSs that--translationsreconstructs;--translationstakes one--alignmentfile and one annotation file. TreeTime reads the coding regions from the CDS rows, which need strand+or-and phase 0, 1 or 2. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--translations <FILE>— Path template of the amino-acid alignments, one FASTA file per CDSThe template must contain a CDS placeholder, which is replaced by each name of
--cds-selection, or by each CDS of--annotationwithout--cds-selection. The placeholder is{cds}or%GENE. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--cds-selection <CDS>— Names of the CDSs to reconstruct from--translationsWithout this setting, the run reconstructs every CDS of
--annotation. -
--model-params <MODEL_PARAMS>— Parameters for the model selected by--model, given as space-separatedkey=valueitemsThe parameters apply to the model of every partition; each
--alignmentfile is one partition. In commands with--partition, each entry carries its own model and parameters, so--model-paramsis an error next to entries. Keys:mu(the overall substitution rate, every named model),kappa(the transition to transversion ratio ofk80,hky85andt92),kappa1andkappa2(the rate ratios oftn93),pi(the equilibrium frequencies off81,hky85andtn93: comma-separated numbers, one frequency per state of the alphabet in its order, for example A, C, G and T for nucleotides, normalized to sum 1; alsopis,Pi,Pis) andpi_GC(the GC content oft92, between 0 and 1). A key left out keeps its default. Example:--model hky85 --model-params kappa=0.2 pis=0.25,0.25,0.25,0.25. -
--model <MODEL>— Substitution model to useinferinfers a model from the data of each partition; each--alignmentfile is one partition. Alternatively, name the model type. If the named model takes parameters, use--model-paramsto set them. The model applies to every file. In commands with--partition, each entry carries its own model, so--modelis an error next to entries.[default: infer]
Possible values:
infer: Infer GTR parameters from data via Fitch parsimony substitution countsjc69k80f81hky85t92tn93jtt92
-
--gamma-categories <K>— Number of discrete gamma rate categories of each partition (2 or more)Sites of one partition evolve at different speeds. With this setting, every partition gets K rate categories of equal probability whose rates are the means of K equal-probability slices of a gamma distribution with mean 1 and shape alpha (Yang 1994). The likelihood of a site is the mean of its likelihoods under the K rates, and the ancestral states are weighted by the probability of each rate at the site. Each partition estimates its own alpha by maximum likelihood between 0.02 and 100, unless the partitions share
gamma-shape(--shared-params). Without the setting, all sites of a partition share one rate. Memory grows about K-fold, runtime more: with 4 categories, optimize on the example datasets takes 7 to 25 times as long, most on large trees in sparse mode. 4 categories are the common choice. The setting applies to marginal reconstructions only: not with--method-anc parsimonyand not with--branch-length-mode input. -
--shared-params <SHARED_PARAMS>— Model parameters that the partitions with an inferred model share, as a comma-separated listexchange-rates: one set of exchange rates W for all these partitions. Each partition scales W so that its rate matrix has mean rate 1 under its own frequencies, so with different frequencies the stored W of the partitions differ by a factor.frequencies: one set of equilibrium frequencies.gamma-shape: one gamma shape alpha; needs--gamma-categories.none: every partition fits its own model; stands alone. The fit of the shared parameters uses the substitutions of all sharing partitions together. A partition with a named model keeps the parameters of its model. Every partition keeps its own relative rate (--partition-rates), and all partitions share the tree and the branch lengths.Default: with
--partition-by genesorrate-categories, the partitions shareexchange-ratesandfrequencies, and alsogamma-shapewith--gamma-categories, because genes of one genome share the mutation process and rate buckets differ only in speed. With--partition-by codon-positions,--partitionentries, or one partition per--alignmentfile, they share nothing, because codon positions differ in their pattern of change. The setting applies only with two or more partitions whose model isinfer.Possible values:
exchange-rates: Share the exchange rates Wfrequencies: Share the equilibrium frequencies pigamma-shape: Share the gamma shape alphanone: Share no model parameter
-
--aa-model <AA_MODEL>— Substitution model of the amino-acid sequences, as--modelfor the nucleotidesThe default
infer, as in augur, infers the model from the data of each CDS.Default value:
inferPossible values:
infer: Infer an amino-acid GTR from the data over the stop-inclusive alphabet. Matches augurjtt92: Jones-Taylor-Thornton 1992 empirical 20-amino-acid model (no stop codon). Stop codons and any other out-of-alphabet characters in the input are mapped to the unknown stateX
-
--method-anc <METHOD_ANC>— Method used for reconstructing ancestral sequences, which places the mutations on the branchesDefault value:
marginalPossible values:
marginal,parsimony -
--representation <REPRESENTATION>— Representation of the sequences on the treeThe dense representation stores the probabilities of every state at every alignment position of each node; the sparse representation stores only the variable positions. Dense is more accurate when branches are long and many sites change, but uses more memory.
[default: auto]
Possible values:
auto: Let TreeTime choose the representation; it chooses sparsedense: Probabilities of every state at every alignment positionsparse: Only the variable positions
-
--sample-from-profile <SAMPLE_FROM_PROFILE>— How to pick ancestral states from the marginal posterior profile.‘argmax’: most likely state at every node (deterministic, default). ‘root’: sample from the posterior at the root only, argmax elsewhere (as augur’s
sample_from_profile='root'). ‘all’: sample from the posterior at every node.Only affects marginal reconstruction (
--method-anc=marginal). Use--seedfor reproducible draws.Default value:
argmaxPossible values:
argmax,root,all -
--gap-fill <GAP_FILL>— How to handle the gap characters of the input sequencesonly-terminal(default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (NorX).all: replace every gap with the unknown character.none: keep every gap.Default value:
only-terminalPossible values:
only-terminal,all,none -
--aa-root-sequence <FILE>— FASTA file with one amino-acid reference sequence of the root per CDSThe root
aa_mutsof augur node data list the differences between this reference and the inferred root, and always omitXand gaps. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,node-data,model,sequences,translations -
--output-node-data <FILE>— Path to output augur-compatible node data JSON.Contains per-node nucleotide mutations, reconstructed sequences, the alignment mask, genome annotations, and the reference (root) sequence. The output is compatible with augur export v2 —node-data for Nextstrain pipeline integration.
-
--output-model <FILE>— Path to output the fitted substitution models as JSON -
--output-sequences <FILE>— Path to output the nucleotide sequences of the nodes as FASTA.Holds the reconstructed sequences of the internal nodes, and of the tips with
--include-leavesor--reconstruct-tip-states;--impute-missing-dataresolves ambiguous tip states. -
--output-translations <FILE>— Path to output the amino-acid sequences of the nodes as FASTA, one file per CDSHolds the reconstructed sequence of every node, internal nodes included.
-
--ambiguity-threshold <AMBIGUITY_THRESHOLD>— Report every state whose posterior probability is at most this far below the probability of the most likely state.The value is a difference of probabilities from 0 to 1. With 0, the report names only the states that tie with the most likely state. RAxML-NG uses 0.5 divided by the number of states, for example 0.125 for nucleotides. The report is off when the value is not set.
A sequence output writes a position with more than one reported state as the ambiguity code of these states: an IUPAC code for nucleotides,
B,Z, orJfor amino acids, otherwiseNorX. Internal nodes have a report at every position, leaves only at the positions that--impute-missing-dataimputes. Nodes whose sequence--sample-from-profiledraws have no report. The setting applies only when a marginal reconstruction runs (--method-anc marginal, or the amino-acid reconstruction of--translations), because Fitch parsimony computes no posterior. -
--ambiguity-outputs <AMBIGUITY_OUTPUTS>— List of the outputs that carry the ambiguity report.Without this list, every output of the run that can carry the report carries it. Requires
--ambiguity-threshold.Possible values:
sequences: Reconstructed nucleotide FASTAtranslations: Reconstructed amino-acid FASTA of each CDSnode-data: Node sequences in the augur node data
-
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
--seed <SEED>— Random seedWithout a seed, a run with a random step draws one and logs it, so the run can be reproduced.
-
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread -
--include-leaves— Emit reconstructed leaf (tip) sequences in addition to internal nodes -
--impute-missing-data— Resolve ambiguous and unknown tip states (Nand IUPAC codes such asR) to the most likely inferred state.Gaps are left as deletions, because they are inferred structure, not missing data. Changes that involve ambiguous characters on terminal branches then disappear from the branch mutations. Only defined for marginal reconstruction; a no-op with a warning under
--method-anc=parsimony. -
--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— Include branch mutations from or to the fully ambiguous state (Nfor nucleotides,Xfor amino acids).By default these mutations are omitted from the branch mutations of the Newick and Nexus annotations, the Auspice JSON, and the
mutsandaa_mutslists of augur node data. Other ambiguity codes, such asKorR, are always reported. The flag does not affect the MAT outputs, which storeNas missing data and never contain these mutations.
treetime clock
Fit a molecular clock by root-to-tip regression, and reroot the tree for the best clock signal
The regression quantifies how clock-like the tree is. Unless --keep-root is given, the run reroots the tree to maximize the clock signal.
Usage:
treetime clock --tree <FILE> --metadata <FILE> (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime clock --config <FILE> [OPTIONS]Examples:
treetime clock -t tree.nwk -m metadata.tsv -O resultstreetime clock -t tree.nwk -m metadata.tsv --keep-root --output-rtt rtt.tsvOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
-m,--metadata <FILE>— Metadata table (CSV or TSV) with one row per sample--metadata-id-columnsnames 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.zstreads a compressed file. -
--metadata-id-columns <COLUMN>— Candidate column name(s) holding the taxon identifier that links metadata to tree tipsThe first listed column that is present in the header is used. Matching is case-insensitive.
Default values:
strain,name,accession -
--metadata-delimiters <CHAR>— Candidate field delimiter(s) for the metadata tableThe delimiter actually present in the file is used. Defaults to comma, tab, and semicolon.
Default values:
,,,; -
--date-column <COLUMN>— Label of the column to be used as sampling date (auto-detected when omitted) -
--date-format <FORMAT>— Format used to parse string sampling dates (numeric, ISO, and uncertain dates parse regardless)Default value:
%Y-%m-%d -
--clock-filter <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.0 switches the filter off.
Default value:
4 -
--allow-negative-rate— Allow negative clock rates.By default, rates are forced to be positive. For trees with little temporal signal, removing this restriction gives essentially mid-point rooting.
-
--prune-filtered-tips— Remove the tips that the clock filter flags from the tree.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.
-
--prune-undated-tips— Remove the tips without a usable date from the tree.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).
-
--keep-tips <NAME>— Names of tips that stay in the tree when —prune-filtered-tips or —prune-undated-tips removes tipsAccepts 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 <FILE>— File with names of tips that stay in the tree when —prune-filtered-tips or —prune-undated-tips removes tips, one name per lineSurrounding 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.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--reroot <REROOT>— Method that chooses the root of the treeleast-squaresandoldestuse the sampling dates;min-devandmidpointuse 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.Possible values:
least-squares: Minimizes the residuals of the root-to-tip regression on the sampling datesmin-dev: Minimizes the variance of root-to-tip distances over all tips; more robust than midpointoldest: Roots at the middle of the branch above the oldest dated tipmidpoint: Roots at the middle of the longest tip-to-tip path; uses only the two farthest tips
-
--outgroup <OUTGROUP>— Root the tree on the branch above the most recent common ancestor of the named tipsWith one tip, the root is placed on the branch leading to that tip.
-
--keep-root— Keep the root of the input tree instead of rerooting it -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,clock-model,rtt,rtt-chart -
--output-clock-model <FILE>— Path to output clock model JSON -
--output-rtt <FILE>— Path to output the root-to-tip regression table.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-rtt-chart <FILE>— Path to output the root-to-tip regression 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,.pngor.pdf. -
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime mugration
Reconstruct the ancestral states of a discrete trait, such as location or host, and fit a model of its changes
Usage:
treetime mugration --tree <FILE> --metadata <FILE> --attribute <COLUMN> (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime mugration --config <FILE> [OPTIONS]Examples:
treetime mugration -t tree.nwk -m metadata.tsv --attribute country -O resultstreetime mugration -t tree.nwk -m metadata.tsv --attribute country --weights weights.tsv --confidence -O resultsOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
-m,--metadata <FILE>— Metadata table (CSV or TSV) with one row per sample--metadata-id-columnsnames 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.zstreads a compressed file. -
--metadata-id-columns <COLUMN>— Candidate column name(s) holding the taxon identifier that links metadata to tree tipsThe first listed column that is present in the header is used. Matching is case-insensitive.
Default values:
strain,name,accession -
--metadata-delimiters <CHAR>— Candidate field delimiter(s) for the metadata tableThe delimiter actually present in the file is used. Defaults to comma, tab, and semicolon.
Default values:
,,,; -
--attribute <COLUMN>— Metadata column with the discrete trait to reconstruct, for examplecountry -
--weights <FILE>— Table (CSV or TSV) with the equilibrium probability of each stateThe weight of a state is the probability that a randomly sampled sequence at equilibrium has the state, for example the population of each country. The first column holds the state and the second its weight, such as the row
micronesia,0.1under the headercountry,weight. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--lat-longs <FILE>— Table with the coordinates of the trait values, which give the Auspice tree a mapThe format of augur’s
--lat-longs: one location per line,<resolution> <name> <latitude> <longitude>, with the fields separated by tabs, or by white space in a line without a tab.<resolution>is the--attributename, and<name>a value of the trait; both match in lower case. A later line for the same location replaces an earlier one, and lines that start with#are skipped. Latitudes are in -90 to 90 degrees, longitudes in -180 to 180 degrees. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--missing-data <MISSING_DATA>— Value of the trait column that marks missing dataDefault value:
? -
--pc <PC>— Pseudo-count of the substitution model fit. Higher values give flatter modelsDefault value:
1 -
--missing-weights-threshold <MISSING_WEIGHTS_THRESHOLD>— Largest fraction of the trait values that may have no weight in the--weightsfileDefault value:
0.5 -
--model-iterations <N>— Number of iterations of the refinement of the substitution model from the dataDefault value:
5 -
--sampling-bias-correction <SAMPLING_BIAS_CORRECTION>— Correction for biased sampling: a rough estimate of how many more state changes the tree would show if the samples were an even sample of the populationThe run multiplies the fitted rate of the substitution model by this factor, for example 2.5 for an estimate of 2.5 times more changes. Without this setting, the run applies no correction.
-
--smooth-initial-pi— Smooth the initial equilibrium frequencies with the pseudo-count before the first reconstruction passBy default, the initial model takes the frequencies of
--weightsas they are, and the pseudo-count applies only to the fits of the model. This setting flattens the prior of the first pass. It affects only models with--weights. -
--filter-uninformative-root— Exclude a near-uniform root posterior from the prior of the equilibrium frequenciesBy default, the most likely state of the root always enters the prior. This setting leaves out a root whose posterior carries no phylogenetic signal, which removes a bias at ambiguous roots that depends on the order of the states.
-
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,node-data,model,trait-probabilities,traits -
--confidence— Write the probability of every state at every nodeAdds the
trait-probabilitiestable to the outputs of--output-all, also when--output-selectionlists other outputs. Without--output-all, give the file with--output-trait-probabilities. -
--output-node-data <FILE>— Path to output augur-compatible node data JSON.Contains per-node discrete trait assignments, confidence profiles, entropy, the inferred substitution model, and branch state-change labels. The output is compatible with augur export v2 —node-data for Nextstrain pipeline integration.
-
--output-model <FILE>— Path to output the fitted substitution models as JSON -
--output-traits <FILE>— Path to output the inferred trait state of every node as a table -
--output-trait-probabilities <FILE>— Path to output the state probabilities of every node as a table -
--ambiguity-threshold <AMBIGUITY_THRESHOLD>— Report every state whose posterior probability is at most this far below the probability of the most likely state.The value is a difference of probabilities from 0 to 1. With 0, the report names only the states that tie with the most likely state. RAxML-NG uses 0.5 divided by the number of states, for example 0.125 for nucleotides. The report is off when the value is not set.
A trait output names the reported states of a node with more than one reported state, joined by
|in the order of the state names, for exampleAmerican Samoa|Samoa. A node with one reported state has an empty cell in the traits table and no field in the JSON outputs. -
--ambiguity-outputs <AMBIGUITY_OUTPUTS>— List of the outputs that carry the ambiguity report.Without this list, every output of the run that can carry the report carries it. Requires
--ambiguity-threshold.Possible values:
traits: Extra column<attribute>_ambiguousin the traits tablenode-data: Extra node field<attribute>_ambiguousin the augur node dataauspice: Extra node attribute<attribute>_ambiguousin the Auspice JSON
-
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime homoplasy
Reconstruct ancestral sequences and count homoplasies, mutations that occur more than once in a tree
An excess of homoplasies can point to contamination, recombination, culture adaptation, or similar processes.
Usage:
treetime homoplasy --tree <FILE> --alignment <FILE> (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime homoplasy --config <FILE> [OPTIONS]Examples:
treetime homoplasy -t tree.nwk -a aln.fasta.xz -O resultstreetime homoplasy -t tree.nwk -a aln.fasta.xz --drms drms.tsv --detailed --output-homoplasy-report report.txtOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-a,--alignment <FILE>— Aligned FASTA inputEach
--alignmentfile is numbered by its position in the list (1, 2, …) and is one partition, unless--partitionentries ofancestral,optimize, ortimetreesplit it into several. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin);-may appear at most once. -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
--allow-missing-sequences— Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.Without this flag the run aborts when more than one third of the tips lack a sequence, because the alignment may not belong to the tree. Useful for per-CDS translations, where some samples have no peptide for a given CDS.
-
--alphabet <ALPHABET>— Alphabet of the sequencesnuc(default): nucleotides A, C, G and T, with the IUPAC ambiguity codes andNfor an unknown base.aa: the 20 amino acids and the stop codon*as a 21st state, withXfor an unknown residue.aa-no-stop: the 20 amino acids without a state for the stop codon.Possible values:
nuc,aa,aa-no-stop -
--zero-based— Report sequence positions counted from 0 instead of 1.Applies to the mutations in the comments of Newick and Nexus trees and to the positions of the homoplasy report. Auspice JSON, augur node data, and UShER MAT outputs count from 1, as their formats require. An input table with positions, such as
--drms, is always counted from 1. -
--model-params <MODEL_PARAMS>— Parameters for the model selected by--model, given as space-separatedkey=valueitemsThe parameters apply to the model of every partition; each
--alignmentfile is one partition. In commands with--partition, each entry carries its own model and parameters, so--model-paramsis an error next to entries. Keys:mu(the overall substitution rate, every named model),kappa(the transition to transversion ratio ofk80,hky85andt92),kappa1andkappa2(the rate ratios oftn93),pi(the equilibrium frequencies off81,hky85andtn93: comma-separated numbers, one frequency per state of the alphabet in its order, for example A, C, G and T for nucleotides, normalized to sum 1; alsopis,Pi,Pis) andpi_GC(the GC content oft92, between 0 and 1). A key left out keeps its default. Example:--model hky85 --model-params kappa=0.2 pis=0.25,0.25,0.25,0.25. -
--model <MODEL>— Substitution model to useinferinfers a model from the data of each partition; each--alignmentfile is one partition. Alternatively, name the model type. If the named model takes parameters, use--model-paramsto set them. The model applies to every file. In commands with--partition, each entry carries its own model, so--modelis an error next to entries.[default: infer]
Possible values:
infer: Infer GTR parameters from data via Fitch parsimony substitution countsjc69k80f81hky85t92tn93jtt92
-
--method-anc <METHOD_ANC>— Method used for reconstructing ancestral sequences, which places the mutations on the branchesDefault value:
marginalPossible values:
marginal,parsimony -
--representation <REPRESENTATION>— Representation of the sequences on the treeThe dense representation stores the probabilities of every state at every alignment position of each node; the sparse representation stores only the variable positions. Dense is more accurate when branches are long and many sites change, but uses more memory.
[default: auto]
Possible values:
auto: Let TreeTime choose the representation; it chooses sparsedense: Probabilities of every state at every alignment positionsparse: Only the variable positions
-
--sample-from-profile <SAMPLE_FROM_PROFILE>— How to pick ancestral states from the marginal posterior profile.‘argmax’: most likely state at every node (deterministic, default). ‘root’: sample from the posterior at the root only, argmax elsewhere (as augur’s
sample_from_profile='root'). ‘all’: sample from the posterior at every node.Only affects marginal reconstruction (
--method-anc=marginal). Use--seedfor reproducible draws.Default value:
argmaxPossible values:
argmax,root,all -
--gap-fill <GAP_FILL>— How to handle the gap characters of the input sequencesonly-terminal(default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (NorX).all: replace every gap with the unknown character.none: keep every gap.Default value:
only-terminalPossible values:
only-terminal,all,none -
--impute-missing-data— Resolve ambiguous and unknown tip states (Nand IUPAC codes such asR) to the most likely inferred state.Gaps are left as deletions, because they are inferred structure, not missing data. Changes that involve ambiguous characters on terminal branches then disappear from the branch mutations. Only defined for marginal reconstruction; a no-op with a warning under
--method-anc=parsimony. -
--const <N>— Number of constant sites that the alignment leaves out.Added to the alignment length to give the number of sites of the genome, which sets the number of sites without mutations and the rate of the Poisson comparison.
Default value:
0 -
--rescale <RESCALE>— Factor that multiplies every branch length of the input tree.Use it when the tree is not in substitutions per site, for example
--rescale=0.001for a tree in substitutions per thousand sites. Scales the reconstruction, the tree outputs, and the reported tree lengths.Default value:
1 -
--detailed— Add the mutations on terminal branches and the taxa that carry recurrent mutations to the report.The statistics JSON always contains them.
-
--drms <FILE>— TSV file of drug resistance mutations (DRM) that annotates the report.Columns:
GENOMIC_POSITION(counted from 1),ALT_BASE,DRUG,GENE,SUBSTITUTION. A mutation at a listed position gets the gene and the drug, and the substitution when its derived base is a listedALT_BASE. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
-n,--num-mut <N>— Number of rows of each list in the report.The statistics JSON always contains the complete lists.
Default value:
10 -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,homoplasy-stats,homoplasy-report -
--output-homoplasy-stats <FILE>— Path to output homoplasy statistics JSON.Contains the counts, histograms, Poisson comparison, and complete ranked lists of the report, for substitutions, changes involving ambiguous characters, and insertions and deletions.
-
--output-homoplasy-report <FILE>— Path to output homoplasy report text.The run also logs the report at info level (
-v). -
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
--seed <SEED>— Random seedWithout a seed, a run with a random step draws one and logs it, so the run can be reproduced.
-
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime optimize
Optimize the branch lengths of a tree for the likelihood of an alignment
Usage:
treetime optimize --tree <FILE> (--alignment <FILE>)... (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime optimize --config <FILE> [OPTIONS]Examples:
treetime optimize -t tree.nwk -a aln.fasta.xz -O resultstreetime optimize -t tree.nwk -a aln.fasta.xz --model hky85 --reroot min-dev --output-tree-nwk optimized.nwkOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-a,--alignment <FILE>— Aligned FASTA inputEach
--alignmentfile is numbered by its position in the list (1, 2, …) and is one partition, unless--partitionentries ofancestral,optimize, ortimetreesplit it into several. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin);-may appear at most once. -
--partition <ENTRY>— One partition: a set of sites of one--alignmentfile with its own substitution model; repeat the flag for each partitionWithout
--partition, each--alignmentfile is one partition with the model of--model. An entry is a YAML or JSON map with the keysname(the name of the partition in outputs and messages),alignment(the number of its--alignmentfile, 1, 2, …; required with two or more files),sites(a list of site ranges, numbered from 1:a,a-b, ora-b\kfor every k-th site from a to b),model(the substitution model, defaultinfer) andmodel_params(thekey=valueitems of--model-paramsfor that model). Each entry carries its own model, so--modeland--model-paramscannot be used together with--partition. Every alignment needs at least one entry, and every site belongs to exactly one entry. An entry withoutsitestakes the sites that the other entries of its alignment leave; one entry per alignment can leave outsites. Write site ranges in single quotes or without quotes, because YAML reads a backslash in double quotes as an escape. Example:--partition "{name: cp1, sites: ['101-1600\3']}" --partition "{name: cp2, sites: ['102-1600\3']}" --partition "{name: cp3, sites: ['103-1600\3'], model: hky85, model_params: ['kappa=4']}" --partition "{name: noncoding}". -
--partition-by <SCHEME>— Build the partitions of each--alignmentfile from a scheme instead of--partitionentriescodon-positionsmakes the partitionscp1,cp2andcp3from codon positions 1, 2 and 3 of the CDSs of--annotation, andnoncodingfrom the other sites.genesmakes one partition per CDS of--annotation, named by the CDS, andnoncodingfrom the other sites. Both need one--annotationfile per--alignmentfile, matched in list order, whose##sequence-regionruns from 1 to the length of its alignment, because annotation positions are alignment columns only for an alignment on that reference. Where CDSs overlap, the longest CDS owns the shared sites and gives them their codon positions; a CDS whose sites all belong to longer CDSs gets no partition.rate-categoriescounts the changes at each site in a Fitch reconstruction on the input tree and puts the sites into the partitionsslow,mediumandfastby the rule of--rate-category-rule; it uses no annotation. Every partition gets the model of--modeland--model-params; with the defaultinfer, each partition fits its own model, subject to--shared-params. With two or more--alignmentfiles, the partition names start with the number of the file, for example2/cp1. A scheme needs the alphabetnucand must make at least two partitions over all files.Possible values:
codon-positions: Codon positions 1, 2 and 3 of every CDS of--annotationas the partitionscp1,cp2andcp3, and the other sites asnoncodinggenes: One partition per CDS of--annotation, named by the CDS, and the other sites asnoncodingrate-categories: The partitionsslow,mediumandfastfrom the number of changes at each site in a Fitch reconstruction on the input tree, by the rule of--rate-category-rule
-
--rate-category-rule <RULE>— Rule that sorts the sites into the partitions of--partition-by rate-categoriesby their change countschange-countsputs sites without changes intoslow, sites with one change intomedium, and sites with two or more changes intofast.median-splitputs sites without changes intoslow, and splits the changed sites at the median of their counts: at or below the median intomedium, above it intofast.k-meanssplits all counts into the three groups with the smallest sum of squared deviations from their means, named by increasing mean count. Empty partitions are left out.[default: change-counts]
Possible values:
change-counts:slowfor sites without changes,mediumfor one change,fastfor two or moremedian-split:slowfor sites without changes; changed sites at or below the median count of the changed sites go tomedium, sites above it tofastk-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
-
--annotation <FILE>— Genome annotation (GFF3) with the coordinates of the CDSs of an--alignmentfileWith
--partition-by codon-positionsorgenes, give one file per--alignmentfile, matched in list order: the scheme builds the partitions of each alignment from the CDSs of its annotation. Inancestral, the file also supplies the annotations of the augur node data and, without--cds-selection, the CDSs that--translationsreconstructs;--translationstakes one--alignmentfile and one annotation file. TreeTime reads the coding regions from the CDS rows, which need strand+or-and phase 0, 1 or 2. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-trees <FILE>— Trees of the genome segments, one Newick or Nexus file per segment, merged into one graph by node nameEvery node of every tree needs a name, unique within its tree; a name that occurs in several trees is one node of the graph. A node that a segment only passes through stays in that segment’s tree as a node with one child. An edge shared by several trees gets the mean of their branch lengths. Use instead of
--tree, together with--segment-alignments. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--segment-alignments <FILE>— Aligned FASTA input of the genome segments, one file per--segment-treesfile, in the same orderUse instead of
--alignment. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
--allow-missing-sequences— Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.Without this flag the run aborts when more than one third of the tips lack a sequence, because the alignment may not belong to the tree. Useful for per-CDS translations, where some samples have no peptide for a given CDS.
-
--alphabet <ALPHABET>— Alphabet of the sequencesnuc(default): nucleotides A, C, G and T, with the IUPAC ambiguity codes andNfor an unknown base.aa: the 20 amino acids and the stop codon*as a 21st state, withXfor an unknown residue.aa-no-stop: the 20 amino acids without a state for the stop codon.Possible values:
nuc,aa,aa-no-stop -
--zero-based— Report sequence positions counted from 0 instead of 1.Applies to the mutations in the comments of Newick and Nexus trees and to the positions of the homoplasy report. Auspice JSON, augur node data, and UShER MAT outputs count from 1, as their formats require. An input table with positions, such as
--drms, is always counted from 1. -
--reroot <REROOT>— Method that chooses the root of the tree from the branch lengthsThe tree is rerooted once, on the branch lengths after the initial guess, and every tip counts. Without this setting, the input root stays. The rerooting methods that need dates (
least-squares,oldest) are available where the inputs have dates.Possible values:
min-dev: Minimizes the variance of root-to-tip distances over all tips; more robust than midpointmidpoint: Roots at the middle of the longest tip-to-tip path; uses only the two farthest tips
-
--outgroup <OUTGROUP>— Root the tree on the branch above the most recent common ancestor of the named tipsWith one tip, the root is placed on the branch leading to that tip.
-
--keep-root— Keep the root of the input tree instead of rerooting it -
--max-iter <N>— Maximum number of iterations of the inference loopPolytomy resolution and coalescent models of the time inference need at least 2 iterations.
Default value:
10 -
--tolerance <TOLERANCE>— Convergence threshold of the log-likelihoodThe loop stops when successive log-likelihoods differ by less than this value, or when it detects a 2-cycle with an amplitude below this value.
Default value:
0.1 -
--damping <DAMPING>— Damping of the branch length updates of the loop, from 0 (inclusive) to 1 (exclusive)Iteration i updates each branch length b to
b = b_new * (1 - d) + b_old * d, withd = max(damping^(i+1), 0.01). Higher values reduce oscillation; 0 switches damping off.Default value:
0 -
--initial-branch-lengths <INITIAL_BRANCH_LENGTHS>— Initial branch lengths before the optimization of each branchDefault value:
autoPossible values:
auto: Estimate only the branches with a missing or invalid length, and keep the valid input lengthsalways: Estimate every branch length, replacing the input lengthsnever: Keep the input branch lengths; the run fails when a branch has a missing or invalid length
-
--optimizer <OPTIMIZER>— Optimizer of each branch length; both methods optimize sqrt(t) in place of the branch length tDefault value:
brentPossible values:
brent: Brent’s method on sqrt(t)newton: Newton-Raphson on sqrt(t)
-
--no-collapse-short-branches— Disable collapsing of short internal branches.By default the optimize loop contracts every internal edge whose optimized length is zero, unless an indel on the edge enters the likelihood and needs a positive length. After the loop, internal edges shorter than 0.1/L (L is the number of sites of all alignments) with no substitution in the marginal reconstruction are contracted too. The substitutions and indels of a contracted edge move to its child edges, and the nodes it joined become one polytomy. When set, such edges are kept in the output tree.
-
--no-merge-shared-mutations— Disable merging of polytomy siblings that share substitutions.By default, sibling branches in a polytomy that carry identical substitutions are grouped under a new internal node. The step and the flag apply only to the sparse representation.
-
--no-hoist-reversions— Disable the reversion hoist in polytomies.By default, when a child branch carries the exact reversion of a substitution on the node’s parent branch, a new node is inserted that groups the node with that child, removing one mutation per reverted position. When set, those reversions are left in place. The step and the flag apply only to the sparse representation.
-
--model-params <MODEL_PARAMS>— Parameters for the model selected by--model, given as space-separatedkey=valueitemsThe parameters apply to the model of every partition; each
--alignmentfile is one partition. In commands with--partition, each entry carries its own model and parameters, so--model-paramsis an error next to entries. Keys:mu(the overall substitution rate, every named model),kappa(the transition to transversion ratio ofk80,hky85andt92),kappa1andkappa2(the rate ratios oftn93),pi(the equilibrium frequencies off81,hky85andtn93: comma-separated numbers, one frequency per state of the alphabet in its order, for example A, C, G and T for nucleotides, normalized to sum 1; alsopis,Pi,Pis) andpi_GC(the GC content oft92, between 0 and 1). A key left out keeps its default. Example:--model hky85 --model-params kappa=0.2 pis=0.25,0.25,0.25,0.25. -
--model <MODEL>— Substitution model to useinferinfers a model from the data of each partition; each--alignmentfile is one partition. Alternatively, name the model type. If the named model takes parameters, use--model-paramsto set them. The model applies to every file. In commands with--partition, each entry carries its own model, so--modelis an error next to entries.[default: infer]
Possible values:
infer: Infer GTR parameters from data via Fitch parsimony substitution countsjc69k80f81hky85t92tn93jtt92
-
--partition-rates <PARTITION_RATES>— Relative substitution rates of the partitionsEach
--alignmentfile is one partition, or each--partitionentry when there are entries. With two or more partitions, all partitions share the branch lengths, and each partition has one relative rate that scales them for the sites of that partition.estimatefits the rate of each partition with the rest of its substitution model fixed (a partition with--model inferstarts from its fitted rate), then divides all rates by their mean weighted by the number of sites of each partition, so that this mean is 1. The branch lengths are then expected substitutions per site, averaged over all sites of all partitions.equalfixes the rate of every partition at 1.The setting applies only with two or more partitions.
[default: estimate]
Possible values:
estimate: Estimate one relative rate per partition, normalized to a site-weighted mean of 1equal: Fix the relative rate of every partition at 1
-
--gamma-categories <K>— Number of discrete gamma rate categories of each partition (2 or more)Sites of one partition evolve at different speeds. With this setting, every partition gets K rate categories of equal probability whose rates are the means of K equal-probability slices of a gamma distribution with mean 1 and shape alpha (Yang 1994). The likelihood of a site is the mean of its likelihoods under the K rates, and the ancestral states are weighted by the probability of each rate at the site. Each partition estimates its own alpha by maximum likelihood between 0.02 and 100, unless the partitions share
gamma-shape(--shared-params). Without the setting, all sites of a partition share one rate. Memory grows about K-fold, runtime more: with 4 categories, optimize on the example datasets takes 7 to 25 times as long, most on large trees in sparse mode. 4 categories are the common choice. The setting applies to marginal reconstructions only: not with--method-anc parsimonyand not with--branch-length-mode input. -
--shared-params <SHARED_PARAMS>— Model parameters that the partitions with an inferred model share, as a comma-separated listexchange-rates: one set of exchange rates W for all these partitions. Each partition scales W so that its rate matrix has mean rate 1 under its own frequencies, so with different frequencies the stored W of the partitions differ by a factor.frequencies: one set of equilibrium frequencies.gamma-shape: one gamma shape alpha; needs--gamma-categories.none: every partition fits its own model; stands alone. The fit of the shared parameters uses the substitutions of all sharing partitions together. A partition with a named model keeps the parameters of its model. Every partition keeps its own relative rate (--partition-rates), and all partitions share the tree and the branch lengths.Default: with
--partition-by genesorrate-categories, the partitions shareexchange-ratesandfrequencies, and alsogamma-shapewith--gamma-categories, because genes of one genome share the mutation process and rate buckets differ only in speed. With--partition-by codon-positions,--partitionentries, or one partition per--alignmentfile, they share nothing, because codon positions differ in their pattern of change. The setting applies only with two or more partitions whose model isinfer.Possible values:
exchange-rates: Share the exchange rates Wfrequencies: Share the equilibrium frequencies pigamma-shape: Share the gamma shape alphanone: Share no model parameter
-
--representation <REPRESENTATION>— Representation of the sequences on the treeThe dense representation stores the probabilities of every state at every alignment position of each node; the sparse representation stores only the variable positions. Dense is more accurate when branches are long and many sites change, but uses more memory.
[default: auto]
Possible values:
auto: Let TreeTime choose the representation; it chooses sparsedense: Probabilities of every state at every alignment positionsparse: Only the variable positions
-
--gap-fill <GAP_FILL>— How to handle the gap characters of the input sequencesonly-terminal(default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (NorX).all: replace every gap with the unknown character.none: keep every gap.Default value:
only-terminalPossible values:
only-terminal,all,none -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot,node-data,model -
--no-indels— Disable indel (insertion and deletion) contributions to branch-length optimization and branch-length distributions.When set, branch-length optimization uses the substitution-only likelihood, and the branch distributions of the time inference exclude the Poisson indel term. This matches standard phylogenetic tools (RAxML, IQ-TREE, PhyML, BEAST) and TreeTime 0.x. By default, indels count.
-
--divergence-units <DIVERGENCE_UNITS>— Units of the divergence values in the augur node data and Auspice outputs.mutations-per-site(default): branch divergence as substitutions per site.mutations: count of reconstructed substitutions per branch that change the state: gaps,N, and ambiguity codes compatible with the parent state do not count.mutationsrequires reconstructed sequences, so it does not work with input branch lengths (--branch-length-mode=input).Default value:
mutations-per-sitePossible values:
mutations-per-site,mutations -
--output-node-data <FILE>— Path to output augur-compatible node data JSON.Contains per-node optimized branch lengths (divergence, substitutions per site) and the input alignment and tree paths. The output is compatible with augur export v2 —node-data.
-
--output-model <FILE>— Path to output the fitted substitution models as JSON -
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime prune
Collapse short branches and branches without mutations, and remove named nodes from a tree
Usage:
treetime prune --tree <FILE> [--alignment <FILE>]... (-O <DIR> | --output-* <FILE>) [OPTIONS]treetime prune --config <FILE> [OPTIONS]Examples:
treetime prune -t tree.nwk --collapse-short 1e-6 --output-tree-nwk pruned.nwktreetime prune -t tree.nwk -a aln.fasta.xz --collapse-empty --merge-shared-mutations -O resultstreetime prune -t tree.nwk --remove-file outliers.txt --output-tree-nwk pruned.nwkOptions:
-
--config <FILE>— Config file (YAML or JSON) with the settings of the commandCommand-line flags take precedence over the file. A relative path in the file resolves from the folder of the file, and from the working directory for standard input; a relative path in a flag resolves from the working directory. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
--dry-run— Print the effective settings as a config file and list the planned output files, then stop without reading inputs or writing files -
-a,--alignment <FILE>— Aligned FASTA inputEach
--alignmentfile is numbered by its position in the list (1, 2, …) and is one partition, unless--partitionentries ofancestral,optimize, ortimetreesplit it into several. A path that ends in.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin);-may appear at most once. -
-t,--tree <FILE>— Tree in Newick formatA path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. -
--newick-dialect <NEWICK_DIALECT>— Newick dialect of the tree inputs (the tree and the reference topology)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 asx#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,beastreads networks with BEAST annotations andclassic,nhxreads NHX trees. TreeTime reads trees only, so a network input is an error.Default value:
classic,beastPossible 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 -
--allow-missing-sequences— Treat tree tips that have no sequence in the alignment as fully ambiguous (missing data) instead of aborting.Without this flag the run aborts when more than one third of the tips lack a sequence, because the alignment may not belong to the tree. Useful for per-CDS translations, where some samples have no peptide for a given CDS.
-
--alphabet <ALPHABET>— Alphabet of the sequencesnuc(default): nucleotides A, C, G and T, with the IUPAC ambiguity codes andNfor an unknown base.aa: the 20 amino acids and the stop codon*as a 21st state, withXfor an unknown residue.aa-no-stop: the 20 amino acids without a state for the stop codon.Possible values:
nuc,aa,aa-no-stop -
--zero-based— Report sequence positions counted from 0 instead of 1.Applies to the mutations in the comments of Newick and Nexus trees and to the positions of the homoplasy report. Auspice JSON, augur node data, and UShER MAT outputs count from 1, as their formats require. An input table with positions, such as
--drms, is always counted from 1. -
--gap-fill <GAP_FILL>— How to handle the gap characters of the input sequencesonly-terminal(default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (NorX).all: replace every gap with the unknown character.none: keep every gap.Default value:
only-terminalPossible values:
only-terminal,all,none -
--collapse-short <LEN>— Collapse branches shorter than this lengthRemoves each internal branch with a length below LEN and attaches the children of its node to the parent node.
-
--collapse-empty— Collapse branches without mutationsRemoves each internal branch that has no mutation or other state transition mapped to it.
Requires —alignment
-
--merge-shared-mutations— Merge branches in polytomies that share identical mutationsWhen sibling branches in a polytomy (node with >2 children) carry identical substitutions, they are grouped under a new internal node. The shared mutations move to the new branch (parent to new node), and only unique mutations remain on children’s edges. Reduces tree builder artifacts from arbitrary binary resolution of polytomies.
Requires —alignment
-
--remove <NAME>— Names of nodes to remove from the treeAccepts several names, separated by commas or spaces.
-
--remove-file <FILE>— File with names of nodes to remove from the tree, one name per lineSurrounding whitespace is trimmed and empty lines are ignored. A path that ends in
.gz,.bz2,.xz, or.zstreads a compressed file. Use-to read uncompressed input from standard input (stdin). -
-O,--output-all <DIR>— Folder that receives the default outputs of the commandWrites the default outputs of the command as
<dir>/<command>.<ext>.--output-selectionrestricts 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.zstwrites a compressed file. The compression level is 2, unless the environment variableGZ_COMPRESSION,BZ2_COMPRESSION,XZ_COMPRESSION, orZST_COMPRESSIONsets another level..gz,.xz, and.zstcompress with all--jobsthreads..bz2compresses 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:
.tsvwrites tabs and.csvcommas, also before a compression suffix (dates.tsv.gz);-writes tabs to standard output. Default names use.tsv.With several
--alignmentfiles, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data ofancestral, Auspice, UShER MAT, Nexus, and Newick with--newick-annotationsother thanplain. Files are numbered 1, 2, … in the order of the--alignmentlist. 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%GENEin 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. -
--newick-annotations <NEWICK_ANNOTATIONS>— Node comments of the Newick outputs:plain,beast, ornhx.plainwrites no comments.beastwrites a comment such as[&mutations="A45G,G136T",date=2016.45]after each node, andnhxwrites 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 carrybeastcomments, which FigTree reads.Default value:
plainPossible values:
plain,beast,nhx -
--output-tree-nwk <FILE>— Path to output Newick tree file.--newick-annotationssets the node comments. -
--output-tree-nexus <FILE>— Path to output Nexus tree file.The nodes carry BEAST comments (
[&mutations="A45G,G136T",date=2016.45]). -
--output-tree-auspice <FILE>— Path to output Auspice v2 JSON tree file -
--output-tree-mat-pb <FILE>— Path to output UShER MAT protobuf tree file -
--output-tree-mat-json <FILE>— Path to output UShER MAT JSON tree file -
--output-tree-graph-json <FILE>— Path to output internal graph JSON tree file -
--output-tree-dot <FILE>— Path to output Graphviz DOT tree file -
-s,--output-selection <OUTPUT_SELECTION>— List of outputs to produce with--output-all.Restricts which outputs
--output-allwrites. Special valueallexpands 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.Possible values:
all,nwk,nexus,auspice,mat-pb,mat-json,graph-json,dot -
--topology-order <TOPOLOGY_ORDER>— Canonical topology ordering presetPossible values:
keep,descendant-count,descendant-count-reverse,height,height-reverse,divergence,divergence-reverse,label,label-reverse,target-order,target-order-reverse -
--topology-order-tree <FILE>— Tree whose leaf order sets the target orderUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-list <FILE>— File with leaf names in the target order, one name per lineUsed by
--topology-order target-orderandtarget-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.zstreads a compressed file. -
--topology-order-aggregate <TOPOLOGY_ORDER_AGGREGATE>— Aggregate used to map a subtree to a target-order positionDefault value:
meanPossible values:
mean,median -
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime pipeline
Run several analysis commands in order from one config file
The config file (JSON or YAML) lists named steps, each an analysis command with its arguments. The steps run one after another on one dataset, in one process; a step may reference the outputs of an earlier step with {{ steps.<name>.outputs.<selection> }}. Use --dry-run to print the resolved plan without running anything, and --steps to run only some steps.
Usage:
treetime pipeline --config <FILE> [-O <DIR>] [OPTIONS]Examples:
treetime pipeline --config pipeline.yaml -O resultstreetime pipeline --config pipeline.yaml --steps clock,timetree -O resultstreetime pipeline --config pipeline.yaml --dry-runOptions:
-
--config <FILE>— Pipeline configuration file (JSON or YAML) describing an ordered list of steps.A relative path in the file resolves from the folder of the file, and from the working directory when the file is read from standard input (
-). -
-O,--output-all <DIR>— Folder of the outputs: each step writes into a subfolder named after the step. Takes precedence over the top-leveloutput_allof the pipeline file. A relative path resolves from the working directory -
--steps <STEPS>— Run only these named steps, in the pipeline’s list order.A referenced upstream step that is not selected must already have its outputs on disk.
-
--dry-run— Resolve and print the plan (steps, inputs, outputs) without running any step -
-j,--jobs <N>— Number of threads of the run. Without this flag, the run uses every available CPU thread
treetime schema
Write the JSON schemas of the config files and of the TreeTime data types
Usage:
treetime schema <COMMAND>Subcommands:
write— Write the JSON schema of a config file, or of every config file and TreeTime data type
treetime schema write
Write the JSON schema of a config file, or of every config file and TreeTime data type
Usage:
treetime schema write [--for <TARGET>] [-o <PATH>] [OPTIONS]Examples:
treetime schema write --for timetree -o timetree.schema.jsontreetime schema write --for all -o schemasOptions:
-
--for <TARGET>— Config file or data type of the schema;allwrites every schema into the folder of-oDefault value:
allPossible values:
all,version-info,progress-event,error-response,pipeline,timetree,optimize,prune,ancestral,homoplasy,clock,mugration -
-o,--output <PATH>— Output file, or-for standard output; with--for all, the output folder (default: the working folder) -
--dry-run— Print the files that the command would write, then stop without writing them
treetime completions
Print the shell completions of TreeTime
Write the output to the completions file of your shell; the documentation of the shell names its location.
Usage:
treetime completions [SHELL] [OPTIONS]Examples:
treetime completions bash > ~/.local/share/bash-completion/completions/treetimetreetime completions zsh > ~/.zfunc/_treetimeArguments:
-
<SHELL>— Name of the shell to generate appropriate completionsDefault value:
bashPossible values:
bash,elvish,fish,fig,powershell,zsh
treetime help-markdown
Print the command-line reference in Markdown
Usage:
treetime help-markdown [OPTIONS] > <FILE>Examples:
treetime help-markdown > reference.mdtreetime help-markdown | less
This document was generated automatically by
clap-markdown.