treetime

optimize

Settings of treetime optimize (Optimize tree), with their flags, config keys, and defaults.

Optimize branch lengths and local topology improvements.

Inputs

  • Tree (required): Newick or Nexus
  • Alignment (required): Aligned FASTA
48 settings match

Input data

Alignment

--alignment
Value
FILE
Config key
alignment
Aligned FASTA input

Partition

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

Partition by

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

Rate category rule

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

Annotation

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

Tree

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

Segment trees

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

Segment alignments

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

Newick dialect

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

Allow missing sequences

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

Alphabet

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

Zero based

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

Rooting

Reroot method

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

Outgroup

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

Keep root

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

Branch lengths

Iterations

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

Tolerance

--tolerance Default: 0.1
Value
TOLERANCE
Config key
tolerance
Convergence threshold of the log-likelihood

Damping

--damping Default: 0
Value
DAMPING
Config key
damping
Damping of the branch length updates of the loop, from 0 (inclusive) to 1 (exclusive)

Initial branch lengths

--initial-branch-lengths Default: auto
Value
INITIAL_BRANCH_LENGTHS
Config key
initial_branch_lengths
Values
  • auto Estimate only the branches with a missing or invalid length, and keep the valid input lengths
  • always Estimate every branch length, replacing the input lengths
  • never Keep the input branch lengths; the run fails when a branch has a missing or invalid length
Initial branch lengths before the optimization of each branch

Optimizer

--optimizer Default: brent
Value
OPTIMIZER
Config key
optimizer
Values
  • brent Brent's method on sqrt(t)
  • newton Newton-Raphson on sqrt(t)
Optimizer of each branch length; both methods optimize sqrt(t) in place of the branch length t

No collapse short branches

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

No merge shared mutations

--no-merge-shared-mutations Default: off
Config key
no_merge_shared_mutations
Disable merging of polytomy siblings that share substitutions.

No hoist reversions

--no-hoist-reversions Default: off
Config key
no_hoist_reversions
Disable the reversion hoist in polytomies.

No indels

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

Substitution model

Substitution model

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

Model params

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

Partition rates

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

Gamma categories

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

Shared params

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

Ancestral reconstruction

Representation

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

Gap fill

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

Output

Output all

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

Newick annotations

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

Output tree Newick

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

Output tree nexus

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

Output tree auspice

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

Output tree MAT protobuf

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

Output tree MAT JSON

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

Output tree graph JSON

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

Output tree DOT

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

Output files

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

Divergence units

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

Output node data

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

Output model

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

Tree ordering

Topology order

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

Topology order tree

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

Topology order list

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

Topology order aggregate

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