treetime

ancestral

Settings of treetime ancestral (Ancestral sequences), with their flags, config keys, and defaults.

Infer ancestral sequences and mutations on each branch.

Inputs

  • Tree (required): Newick or Nexus
  • Alignment (required): Aligned FASTA
49 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

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.

Annotation

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

Translations

--translations
Value
FILE
Config key
translations
Path template of the amino-acid alignments, one FASTA file per CDS

CDS selection

--cds-selection Default: none
Value
CDS
Config key
cds_selection
Names of the CDSs to reconstruct from --translations

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

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

Amino-acid model

--aa-model Default: infer
Value
AA_MODEL
Config key
aa_model
Values
  • infer Infer an amino-acid GTR from the data over the stop-inclusive alphabet. Matches augur.
  • jtt92 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 state `X`.
Substitution model of the amino-acid sequences, as --model for the nucleotides

Ancestral reconstruction

Ancestral method

--method-anc Default: marginal
Value
METHOD_ANC
Config key
method_anc
Values
  • marginal
  • parsimony
Method used for reconstructing ancestral sequences, which places the mutations on the branches

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

Sample from profile

--sample-from-profile Default: argmax
Value
SAMPLE_FROM_PROFILE
Config key
sample_from_profile
Values
  • argmax
  • root
  • all
How to pick ancestral states from the marginal posterior profile.

Gap fill

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

Include leaves

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

Reconstruct tip states

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

Report ambiguous

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

Impute missing data

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

Amino-acid root sequence

--aa-root-sequence
Value
FILE
Config key
aa_root_sequence
FASTA file with one amino-acid reference sequence of the root per CDS

Output

Output all

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

Newick annotations

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

Output tree Newick

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

Output tree nexus

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

Output tree auspice

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

Output tree MAT protobuf

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

Output tree MAT JSON

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

Output tree graph JSON

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

Output tree DOT

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

Output files

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

Output node data

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

Output model

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

Output sequences

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

Output translations

--output-translations
Value
FILE
Config key
output_translations
Path to output the amino-acid sequences of the nodes as FASTA, one file per CDS

Ambiguity threshold

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

Ambiguity outputs

--ambiguity-outputs Default: none
Value
AMBIGUITY_OUTPUTS
Config key
ambiguity_outputs
Values
  • sequences Reconstructed nucleotide FASTA
  • translations Reconstructed amino-acid FASTA of each CDS
  • node-data Node sequences in the augur node data
List of the outputs that carry the ambiguity report.

Tree ordering

Topology order

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

Topology order tree

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

Topology order list

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

Topology order aggregate

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

Reproducibility

Seed

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