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
Input data
Alignment
--alignment - Value
FILE- Config key
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.
- 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"]}]
--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}".
- Value
SCHEME- Config key
partition_by- Values
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`
- Cannot be combined with
- --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.
- Value
RULE- Config key
rate_category_rule- Values
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.
Tree
--tree - Value
FILE- Config key
tree
A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Segment trees
--segment-trees - Value
FILE- Config key
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 - Value
FILE- Config key
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.
- Value
NEWICK_DIALECT- Config key
newick_dialect- Values
classic,plainclassic,beastclassic,nhxclassic,mrbayesenewick,plainenewick,beastenewick,nhxenewick,mrbayesrich,plainrich,beastrich,nhxrich,mrbayes
A dialect is a tree structure and an annotation convention, written as <structure>,<annotations>. The structure is classic (plain labels and branch lengths), enewick (hybrid nodes such as x#H1) or rich (eNewick with support and probability fields). The annotations are plain (comments are text), beast ([&key=value]), nhx ([&&NHX:key=value]) or mrbayes ([&B name value]). For example, enewick,beast reads networks with BEAST annotations and classic,nhx reads NHX trees. TreeTime reads trees only, so a network input is an error.
- Config key
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.
- Value
ALPHABET- Config key
alphabet- Values
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.
- Config key
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.
Annotation
--annotation - Value
FILE- Config key
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.
Translations
--translations - Value
FILE- Config key
translations
The template must contain a CDS placeholder, which is replaced by each name of --cds-selection, or by each CDS of --annotation without --cds-selection. The placeholder is {cds} or %GENE. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Value
CDS- Config key
cds_selection
--translationsWithout this setting, the run reconstructs every CDS of --annotation.
Substitution model
- Value
MODEL- Config key
model- Values
jc69k80f81hky85t92tn93jtt92inferInfer GTR parameters from data via Fitch parsimony substitution counts.
- Cannot be combined with
- --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.
- Value
MODEL_PARAMS- Config key
model_params- Cannot be combined with
- --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.
- Value
K- Config key
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.
- Value
SHARED_PARAMS- Config key
shared_params- Values
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.
- Value
AA_MODEL- Config key
aa_model- Values
inferInfer an amino-acid GTR from the data over the stop-inclusive alphabet. Matches augur.jtt92Jones-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`.
--model for the nucleotidesThe default infer, as in augur, infers the model from the data of each CDS.
Ancestral reconstruction
- Value
METHOD_ANC- Config key
method_anc- Values
marginalparsimony
- Value
REPRESENTATION- Config key
representation- Values
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.
- Value
SAMPLE_FROM_PROFILE- Config key
sample_from_profile- Values
argmaxrootall
'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 --seed for reproducible draws.
- Value
GAP_FILL- Config key
gap_fill- Values
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.
- Config key
include_leaves
- Config key
reconstruct_tip_states
--include-leaves --impute-missing-data: emit tip sequences with ambiguous and unknown states resolved to the most likely inferred state.- Config key
report_ambiguous
N for nucleotides, X for amino acids).By default these mutations are omitted from the branch mutations of the Newick and Nexus annotations, the Auspice JSON, and the muts and aa_muts lists of augur node data. Other ambiguity codes, such as K or R, are always reported. The flag does not affect the MAT outputs, which store N as missing data and never contain these mutations.
- Config key
impute_missing_data
N and IUPAC codes such as R) 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.
Amino-acid root sequence
--aa-root-sequence - Value
FILE- Config key
aa_root_sequence
The root aa_muts of augur node data list the differences between this reference and the inferred root, and always omit X and gaps. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Output
Output all
--output-all - Value
DIR- Config key
output_all
Writes the default outputs of the command as <dir>/<command>.<ext>. --output-selection restricts the outputs that the folder receives. The per-file flags (--output-*) override or supplement the files of the folder.
An output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails.
Every output path follows these rules. A path that ends in .gz, .bz2, .xz, or .zst writes a compressed file. The compression level is 2, unless the environment variable GZ_COMPRESSION, BZ2_COMPRESSION, XZ_COMPRESSION, or ZST_COMPRESSION sets another level. .gz, .xz, and .zst compress with all --jobs threads. .bz2 compresses with one thread and is much slower to write and to read than the other formats. The path - of a per-file flag writes the output uncompressed to standard output. Missing parent folders are created.
Table outputs choose the delimiter by the extension of their path: .tsv writes tabs and .csv commas, also before a compression suffix (dates.tsv.gz); - writes tabs to standard output. Default names use .tsv.
With several --alignment files, the outputs that carry sequence positions are written once per file: reconstructed sequences, the augur node data of ancestral, Auspice, UShER MAT, Nexus, and Newick with --newick-annotations other than plain. Files are numbered 1, 2, ... in the order of the --alignment list. Their default names carry the number after the command name (<dir>/<command>.1.<ext>), and the file name of a per-file flag for such an output must contain {alignment}, which is replaced by the number. Other tree outputs with {alignment} in their file name are also written once per file.
The outputs written once per CDS, such as the reconstructed amino-acid sequences, take the placeholder {cds} or %GENE in the file name of their per-file flag, which is replaced by the name of the CDS. The placeholder is required when more than one CDS is reconstructed; folder names are used as given.
- Value
NEWICK_ANNOTATIONS- Config key
newick_annotations- Values
plainbeastnhx
plain, beast, or nhx.plain writes no comments. beast writes a comment such as [&mutations="A45G,G136T",date=2016.45] after each node, and nhx writes the same values as [&&NHX:key=value]. The comments hold the mutations on the branch above the node, its date, and its inferred trait value, as far as the command infers them. Nexus outputs always carry beast comments, which FigTree reads.
Output tree Newick
--output-tree-nwk - Value
FILE- Config key
output_tree_nwk
--newick-annotations sets the node comments.
Output tree nexus
--output-tree-nexus - Value
FILE- Config key
output_tree_nexus
The nodes carry BEAST comments ([&mutations="A45G,G136T",date=2016.45]).
Output tree auspice
--output-tree-auspice - Value
FILE- Config key
output_tree_auspice
Output tree MAT protobuf
--output-tree-mat-pb - Value
FILE- Config key
output_tree_mat_pb
Output tree MAT JSON
--output-tree-mat-json - Value
FILE- Config key
output_tree_mat_json
Output tree graph JSON
--output-tree-graph-json - Value
FILE- Config key
output_tree_graph_json
Output tree DOT
--output-tree-dot - Value
FILE- Config key
output_tree_dot
- Value
OUTPUT_SELECTION- Config key
output_selection- Values
allnwknexusauspicemat-pbmat-jsongraph-jsondotnode-datamodelsequencestranslations
--output-all.Restricts which outputs --output-all writes. Special value all expands to every output available for this command. Requires --output-all. Per-file flags are always honored regardless of this selection.
A selected output that the run has no data for is skipped without a message, for example the substitution model of a run that fits none. A per-file flag for such an output fails. An output that the settings rule out fails in both forms, for example the sequences of timetree --branch-length-mode input.
Output node data
--output-node-data - Value
FILE- Config key
output_node_data
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
--output-model - Value
FILE- Config key
output_model
Output sequences
--output-sequences - Value
FILE- Config key
output_sequences
Holds the reconstructed sequences of the internal nodes, and of the tips with --include-leaves or --reconstruct-tip-states; --impute-missing-data resolves ambiguous tip states.
Output translations
--output-translations - Value
FILE- Config key
output_translations
Holds the reconstructed sequence of every node, internal nodes included.
- Value
AMBIGUITY_THRESHOLD- Config key
ambiguity_threshold
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, or J for amino acids, otherwise N or X. Internal nodes have a report at every position, leaves only at the positions that --impute-missing-data imputes. Nodes whose sequence --sample-from-profile draws 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.
- Value
AMBIGUITY_OUTPUTS- Config key
ambiguity_outputs- Values
sequencesReconstructed nucleotide FASTAtranslationsReconstructed amino-acid FASTA of each CDSnode-dataNode sequences in the augur node data
Without this list, every output of the run that can carry the report carries it. Requires --ambiguity-threshold.
Tree ordering
- Value
TOPOLOGY_ORDER- Config key
topology_order- Values
keepdescendant-countdescendant-count-reverseheightheight-reversedivergencedivergence-reverselabellabel-reversetarget-ordertarget-order-reverse
Topology order tree
--topology-order-tree - Value
FILE- Config key
topology_order_tree- Cannot be combined with
- --topology-order-list
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-list, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
Topology order list
--topology-order-list - Value
FILE- Config key
topology_order_list- Cannot be combined with
- --topology-order-tree
Used by --topology-order target-order and target-order-reverse. Without this flag and --topology-order-tree, the leaf order of the input tree is the target order. A path that ends in .gz, .bz2, .xz, or .zst reads a compressed file.
- Value
TOPOLOGY_ORDER_AGGREGATE- Config key
topology_order_aggregate- Values
meanmedian
Reproducibility
- Value
SEED- Config key
seed
Without a seed, a run with a random step draws one and logs it, so the run can be reproduced.