optimize
Settings of treetime optimize (Optimize tree), with their flags, config keys, and defaults.
Optimize branch lengths and local topology improvements.
Eingaben
- Tree (erforderlich): Newick or Nexus
- Alignment (erforderlich): Aligned FASTA
Input data
Alignment
--alignment - Wert
FILE- Konfigurationsschlüssel
alignment
Each --alignment file is numbered by its position in the list (1, 2, ...) and is one partition, unless --partition entries of ancestral, optimize, or timetree split it into several. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file. Use - to read uncompressed input from standard input (stdin); - may appear at most once.
- Wert
ENTRY- Konfigurationsschlüssel
partition- Nicht kombinierbar mit
- --model --model-params --partition-by
- Beispiele
[{"name":"cp12","sites":["1-1500\\3","2-1500\\3"]},{"name":"cp3","sites":["3-1500\\3"],"model":"hky85","model_params":["kappa=4"]}]
--alignment file with its own substitution model; repeat the flag for each partitionWithout --partition, each --alignment file is one partition with the model of --model. An entry is a YAML or JSON map with the keys name (the name of the partition in outputs and messages), alignment (the number of its --alignment file, 1, 2, ...; required with two or more files), sites (a list of site ranges, numbered from 1: a, a-b, or a-b\k for every k-th site from a to b), model (the substitution model, default infer) and model_params (the key=value items of --model-params for that model). Each entry carries its own model, so --model and --model-params cannot be used together with --partition. Every alignment needs at least one entry, and every site belongs to exactly one entry. An entry without sites takes the sites that the other entries of its alignment leave; one entry per alignment can leave out sites. 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}".
- Wert
SCHEME- Konfigurationsschlüssel
partition_by- Werte
codon-positionsCodon positions 1, 2 and 3 of every CDS of `--annotation` as the partitions `cp1`, `cp2` and `cp3`, and the other sites as `noncoding`genesOne partition per CDS of `--annotation`, named by the CDS, and the other sites as `noncoding`rate-categoriesThe partitions `slow`, `medium` and `fast` from the number of changes at each site in a Fitch reconstruction on the input tree, by the rule of `--rate-category-rule`
- Nicht kombinierbar mit
- --partition
--alignment file from a scheme instead of --partition entriescodon-positions makes the partitions cp1, cp2 and cp3 from codon positions 1, 2 and 3 of the CDSs of --annotation, and noncoding from the other sites. genes makes one partition per CDS of --annotation, named by the CDS, and noncoding from the other sites. Both need one --annotation file per --alignment file, matched in list order, whose ##sequence-region runs 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-categories counts the changes at each site in a Fitch reconstruction on the input tree and puts the sites into the partitions slow, medium and fast by the rule of --rate-category-rule; it uses no annotation. Every partition gets the model of --model and --model-params; with the default infer, each partition fits its own model, subject to --shared-params. With two or more --alignment files, the partition names start with the number of the file, for example 2/cp1. A scheme needs the alphabet nuc and must make at least two partitions over all files.
- Wert
RULE- Konfigurationsschlüssel
rate_category_rule- Werte
change-counts`slow` for sites without changes, `medium` for one change, `fast` for two or moremedian-split`slow` for sites without changes; changed sites at or below the median count of the changed sites go to `medium`, sites above it to `fast`k-meansThe 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
--partition-by rate-categories by their change countschange-counts puts sites without changes into slow, sites with one change into medium, and sites with two or more changes into fast. median-split puts sites without changes into slow, and splits the changed sites at the median of their counts: at or below the median into medium, above it into fast. k-means splits 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.
Annotation
--annotation - Wert
FILE- Konfigurationsschlüssel
annotation
--alignment fileWith --partition-by codon-positions or genes, give one file per --alignment file, matched in list order: the scheme builds the partitions of each alignment from the CDSs of its annotation. In ancestral, the file also supplies the annotations of the augur node data and, without --cds-selection, the CDSs that --translations reconstructs; --translations takes one --alignment file 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 .zst reads a compressed file.
Tree
--tree - Wert
FILE- Konfigurationsschlüssel
tree
A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Segment trees
--segment-trees - Wert
FILE- Konfigurationsschlüssel
segment_trees
Every 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 .zst reads a compressed file.
Segment alignments
--segment-alignments - Wert
FILE- Konfigurationsschlüssel
segment_alignments
--segment-trees file, in the same orderUse instead of --alignment. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Wert
NEWICK_DIALECT- Konfigurationsschlüssel
newick_dialect- Werte
classic,plainclassic,beastclassic,nhxclassic,mrbayesenewick,plainenewick,beastenewick,nhxenewick,mrbayesrich,plainrich,beastrich,nhxrich,mrbayes
A dialect is a tree structure and an annotation convention, written as <structure>,<annotations>. The structure is classic (plain labels and branch lengths), enewick (hybrid nodes such as x#H1) or rich (eNewick with support and probability fields). The annotations are plain (comments are text), beast ([&key=value]), nhx ([&&NHX:key=value]) or mrbayes ([&B name value]). For example, enewick,beast reads networks with BEAST annotations and classic,nhx reads NHX trees. TreeTime reads trees only, so a network input is an error.
- Konfigurationsschlüssel
allow_missing_sequences
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.
- Wert
ALPHABET- Konfigurationsschlüssel
alphabet- Werte
nucaaaa-no-stop
nuc (default): nucleotides A, C, G and T, with the IUPAC ambiguity codes and N for an unknown base. aa: the 20 amino acids and the stop codon * as a 21st state, with X for an unknown residue. aa-no-stop: the 20 amino acids without a state for the stop codon.
- Konfigurationsschlüssel
zero_based
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.
Rooting
- Wert
REROOT- Konfigurationsschlüssel
reroot- Werte
min-devMinimizes the variance of root-to-tip distances over all tips; more robust than midpointmidpointRoots at the middle of the longest tip-to-tip path; uses only the two farthest tips
- Nicht kombinierbar mit
- --keep-root --outgroup
The 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.
- Wert
OUTGROUP- Konfigurationsschlüssel
outgroup- Nicht kombinierbar mit
- --keep-root --reroot
- Beispiele
["outgroup_tip"]
With one tip, the root is placed on the branch leading to that tip.
- Konfigurationsschlüssel
keep_root- Nicht kombinierbar mit
- --outgroup --reroot
Branch lengths
- Wert
N- Konfigurationsschlüssel
max_iter
Polytomy resolution and coalescent models of the time inference need at least 2 iterations.
- Wert
TOLERANCE- Konfigurationsschlüssel
tolerance
The 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.
- Wert
DAMPING- Konfigurationsschlüssel
damping
Iteration i updates each branch length b to b = b_new * (1 - d) + b_old * d, with d = max(damping^(i+1), 0.01). Higher values reduce oscillation; 0 switches damping off.
- Wert
INITIAL_BRANCH_LENGTHS- Konfigurationsschlüssel
initial_branch_lengths- Werte
autoEstimate only the branches with a missing or invalid length, and keep the valid input lengthsalwaysEstimate every branch length, replacing the input lengthsneverKeep the input branch lengths; the run fails when a branch has a missing or invalid length
- Wert
OPTIMIZER- Konfigurationsschlüssel
optimizer- Werte
brentBrent's method on sqrt(t)newtonNewton-Raphson on sqrt(t)
- Konfigurationsschlüssel
no_collapse_short_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.
- Konfigurationsschlüssel
no_merge_shared_mutations
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.
- Konfigurationsschlüssel
no_hoist_reversions
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.
- Konfigurationsschlüssel
no_indels
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.
Substitution model
- Wert
MODEL- Konfigurationsschlüssel
model- Werte
jc69k80f81hky85t92tn93jtt92inferInfer GTR parameters from data via Fitch parsimony substitution counts.
- Nicht kombinierbar mit
- --partition
infer infers a model from the data of each partition; each --alignment file is one partition. Alternatively, name the model type. If the named model takes parameters, use --model-params to set them. The model applies to every file. In commands with --partition, each entry carries its own model, so --model is an error next to entries.
- Wert
MODEL_PARAMS- Konfigurationsschlüssel
model_params- Nicht kombinierbar mit
- --partition
--model, given as space-separated key=value itemsThe parameters apply to the model of every partition; each --alignment file is one partition. In commands with --partition, each entry carries its own model and parameters, so --model-params is an error next to entries. Keys: mu (the overall substitution rate, every named model), kappa (the transition to transversion ratio of k80, hky85 and t92), kappa1 and kappa2 (the rate ratios of tn93), pi (the equilibrium frequencies of f81, hky85 and tn93: 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; also pis, Pi, Pis) and pi_GC (the GC content of t92, 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.
- Wert
PARTITION_RATES- Konfigurationsschlüssel
partition_rates- Werte
estimateEstimate one relative rate per partition, normalized to a site-weighted mean of 1.equalFix the relative rate of every partition at 1.
Each --alignment file is one partition, or each --partition entry 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. estimate fits the rate of each partition with the rest of its substitution model fixed (a partition with --model infer starts 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. equal fixes the rate of every partition at 1.
The setting applies only with two or more partitions.
- Wert
K- Konfigurationsschlüssel
gamma_categories
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 parsimony and not with --branch-length-mode input.
- Wert
SHARED_PARAMS- Konfigurationsschlüssel
shared_params- Werte
exchange-ratesShare the exchange rates W.frequenciesShare the equilibrium frequencies pi.gamma-shapeShare the gamma shape alpha.noneShare no model parameter.
exchange-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 genes or rate-categories, the partitions share exchange-rates and frequencies, and also gamma-shape with --gamma-categories, because genes of one genome share the mutation process and rate buckets differ only in speed. With --partition-by codon-positions, --partition entries, or one partition per --alignment file, they share nothing, because codon positions differ in their pattern of change. The setting applies only with two or more partitions whose model is infer.
Ancestral reconstruction
- Wert
REPRESENTATION- Konfigurationsschlüssel
representation- Werte
autoLet TreeTime choose the representation; it chooses sparsedenseProbabilities of every state at every alignment positionsparseOnly the variable positions
The 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.
- Wert
GAP_FILL- Konfigurationsschlüssel
gap_fill- Werte
only-terminalallnone
only-terminal (default, as in TreeTime 0.x): replace the leading and trailing gaps of each sequence with the unknown character of the alphabet (N or X). all: replace every gap with the unknown character. none: keep every gap.
Output
Output all
--output-all - Wert
DIR- Konfigurationsschlüssel
output_all
Writes the default outputs of the command as <dir>/<command>.<ext>. --output-selection restricts the outputs that the folder receives. The per-file flags (--output-*) override or supplement the files of the folder.
An output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails.
Every output path follows these rules. A path that ends in .gz, .bz2, .xz, or .zst writes a compressed file. The compression level is 2, unless the environment variable GZ_COMPRESSION, BZ2_COMPRESSION, XZ_COMPRESSION, or ZST_COMPRESSION sets another level. .gz, .xz, and .zst compress with all --jobs threads. .bz2 compresses with one thread and is much slower to write and to read than the other formats. The path - of a per-file flag writes the output uncompressed to standard output. Missing parent folders are created.
Table outputs choose the delimiter by the extension of their path: .tsv writes tabs and .csv commas, also before a compression suffix (dates.tsv.gz); - writes tabs to standard output. Default names use .tsv.
With several --alignment files, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data of ancestral, Auspice, UShER MAT, Nexus, and Newick with --newick-annotations other than plain. Files are numbered 1, 2, ... in the order of the --alignment list. Their default names carry the number after the command name (<dir>/<command>.1.<ext>), and the file name of a per-file flag for such an output must contain {alignment}, which is replaced by the number. Other tree outputs with {alignment} in their file name are also written once per file.
The outputs written once per CDS, such as the reconstructed amino-acid sequences, take the placeholder {cds} or %GENE in the file name of their per-file flag, which is replaced by the name of the CDS. The placeholder is required when more than one CDS is reconstructed; folder names are used as given.
- Wert
NEWICK_ANNOTATIONS- Konfigurationsschlüssel
newick_annotations- Werte
plainbeastnhx
plain, beast, or nhx.plain writes no comments. beast writes a comment such as [&mutations="A45G,G136T",date=2016.45] after each node, and nhx writes the same values as [&&NHX:key=value]. The comments hold the mutations on the branch above the node, its date, and its inferred trait value, as far as the command infers them. Nexus outputs always carry beast comments, which FigTree reads.
Output tree Newick
--output-tree-nwk - Wert
FILE- Konfigurationsschlüssel
output_tree_nwk
--newick-annotations sets the node comments.
Output tree nexus
--output-tree-nexus - Wert
FILE- Konfigurationsschlüssel
output_tree_nexus
The nodes carry BEAST comments ([&mutations="A45G,G136T",date=2016.45]).
Output tree auspice
--output-tree-auspice - Wert
FILE- Konfigurationsschlüssel
output_tree_auspice
Output tree MAT protobuf
--output-tree-mat-pb - Wert
FILE- Konfigurationsschlüssel
output_tree_mat_pb
Output tree MAT JSON
--output-tree-mat-json - Wert
FILE- Konfigurationsschlüssel
output_tree_mat_json
Output tree graph JSON
--output-tree-graph-json - Wert
FILE- Konfigurationsschlüssel
output_tree_graph_json
Output tree DOT
--output-tree-dot - Wert
FILE- Konfigurationsschlüssel
output_tree_dot
- Wert
OUTPUT_SELECTION- Konfigurationsschlüssel
output_selection- Werte
allnwknexusauspicemat-pbmat-jsongraph-jsondotnode-datamodel
--output-all.Restricts which outputs --output-all writes. Special value all expands to every output available for this command. Requires --output-all. Per-file flags are always honored regardless of this selection.
A selected output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails. An output that the settings rule out fails in both forms, for example the sequences of timetree --branch-length-mode input.
- Wert
DIVERGENCE_UNITS- Konfigurationsschlüssel
divergence_units- Werte
mutations-per-sitemutations
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. mutations requires reconstructed sequences, so it does not work with input branch lengths (--branch-length-mode=input).
Output node data
--output-node-data - Wert
FILE- Konfigurationsschlüssel
output_node_data
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
--output-model - Wert
FILE- Konfigurationsschlüssel
output_model
Tree ordering
- Wert
TOPOLOGY_ORDER- Konfigurationsschlüssel
topology_order- Werte
keepdescendant-countdescendant-count-reverseheightheight-reversedivergencedivergence-reverselabellabel-reversetarget-ordertarget-order-reverse
Topology order tree
--topology-order-tree - Wert
FILE- Konfigurationsschlüssel
topology_order_tree- Nicht kombinierbar mit
- --topology-order-list
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-list, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Topology order list
--topology-order-list - Wert
FILE- Konfigurationsschlüssel
topology_order_list- Nicht kombinierbar mit
- --topology-order-tree
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-tree, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Wert
TOPOLOGY_ORDER_AGGREGATE- Konfigurationsschlüssel
topology_order_aggregate- Werte
meanmedian