Functions

treeknit

Intro

We suggest two sets of defaults for running TreeKnit. --better-trees will produce more accurately resolved trees (default for more than two trees). If you are interested in better inference of consistent clades, --better-MCCs (default for 2 trees). Use the flag --help-defaults with dummy arguments for more details (e.g. treeknit x y --help-defaults).

Arguments

• nwk_files: Newick files (requires 2 or more trees - note an ARG currently cannot be created for more than 2 trees)

Options

• -o, --outdir <arg>: directory for results; Example -o=treeknit_results
• -g, --gamma <arg>: value of γ; Example -g=2
• --seq-lengths <arg>: length of the sequences. Example: --seq-length "1500 2000"
• --n-mcmc-it <arg>: number of MCMC iterations per leaf; default 25
• --rounds <arg>: Number of times to run inference on input trees. If rounds > 1 MCCs will be re-inferred using resolved trees from the last iteration. (default: 1)
• --verbosity-level <arg>: set value of verbosity. Default 0. -v flag sets it to 1. Set to 2 for maximum verbosity (only useful for small trees). Set to -1 for no output at all

Flags

• --help-defaults: Print some information about the default settings --better-trees and -better-MCCs. Can only be used with (possibily dummy) arguments, e.g. treeknit x y --help-defaults.
• --better-trees: Use the --better-trees method (default for more than 2 trees)
• --better-MCCs: Use the --better-MCCs method (default for 2 trees)
• --naive: Naive inference (overrides -g).
• --no-resolve: Do not attempt to resolve trees before inferring pairwise MCCs.
• --liberal-resolve: Resolve output trees as much as possible using inferred MCCs, adding splits when order of coalescence and reassortment is unclear (coalescence is set at a time prior to reassortment)
• --resolve-all-rounds: Resolve trees before inferring pairwise MCCs in all rounds, overrides --no-resolve (default for 2 trees, for more than 2 trees default is to not resolve in the final round)
• --no-pre-resolve: Do not compatibly resolve all trees with each other before inferring MCCs (default is to pre-resolve)
• --no-likelihood: Do not use branch length likelihood test to sort between different MCCs
• --parallel: Run sequential TreeKnit with parallelization (only used for 3 or more trees)
• -v, --verbose: set verbosity to 1
• --auspice-view: return ouput files for auspice

run_treeknit!(trees, oa::OptArgs; naive=false) where T
run_treeknit!(trees; kwargs...)

Main TreeKnit run function.

Compute MCCs of all tree pairs in tree list trees. The order in which pairs are processed is the natural one given the order of trees: (1,2), (1,3) ... (K-1, K).

In the second form, the keyword arguments are passed to OptArgs.

Parameters:

• pre_resolve=true: input trees are resolved with each other prior to MCC computation.
• resolve=true: input trees are resolved in each pair-wise MCC computation, resolved trees are used as input trees for the next pair.
• naive: return naive MCCs of all tree pairs.
• strict: apply conservative resolution. If an MCC implies a coalescence event occured, but the order of reassortment and coalescence is ambiguous, more than one split could be added to the tree. In such an event strict resolve does not add a split, however liberal = (strict==false) resolution would choose one such order of events and add that respective split.
• parallel: parallelize MCC computation of tree pairs as much as possible.

naive_mccs(treelist)

Find sets of nodes which are:

• clades in all trees of treelist,
• all subclades of nodes are clades in all trees of treelist (both of these properties define consistency),
• maximal: adding a node to a set results it in not being a clade in at least one of the trees.

All the trees of treelist should share the same leaf nodes.

	runopt(t1::Tree, t2::Tree; kwargs...)
	runopt(oa::OptArgs, t1::Tree, t2::Tree)

Run optimization at constant γ. See ?Optargs for arguments. In the first form, keyword arguments are given to OptArgs.

resolve!(t1::Tree, t2::Tree, tn::Vararg{Tree}; tau=0.)

Resolve t1 using splits of t2 and inversely. Every split of t2 a tree that is compatible with t1 is introduced in t1 with branch length tau (and inversely). Return new splits in each tree.

If more than two trees are given, only introduce a split from ti in tree tj if the split is compatible with all trees.

resolve!(t1::Tree{T}, t2::Tree{T}, MCCs; tau = 0., strict=true)

Resolve t1 using t2 and t2 using t1, both using the list of MCCs. Return the list of resolved splits in each tree.

• MCCs: Vector{Vector{String}}. List of MCCs. Each MCC is a vector of leaf names.
• tau: New branches have a length tau.
• strict: if strict or liberal resolution should be used. If strict, only introduce unambiguous splits.