compareTrees
compareTrees [OPTIONS] estimate.nwk reference.nwk > output.txt
Compare two collections of phylogenetic trees representing samples from two posterior (or other) distributions over tree space – for example, samples from a variational approximation and from an MCMC reference run. By default, reports the topology-based mean split KL divergence. Additional comparison metrics can be requested with options.
(1) Mean split KL: the mean per-split Bernoulli KL divergence between the two samples’ posterior distributions over clade splits. For each non-trivial clade split observed in either estimate.nwk or reference.nwk, treats inclusion of the split as a Bernoulli variable with posterior inclusion probability estimated from the corresponding sample, and computes KL(p_est(s) || p_ref(s)). The reported value is the average over the union of splits observed in either sample (Laplace-smoothed so no split has probability exactly 0 or 1). This approximates the KL divergence between the two posterior distributions over tree topology, and remains well-behaved even when the two samples share few or no exact topologies, unlike the full-topology KL divergence -sum p(tau) log (p(tau)/q(tau)).
(2) Mean pairwise-distance KL (enabled by –pairwise-dist-kl): for each leaf pair, a Gaussian(mean, sd) is fit to its raw tree distance across each sample. The reported value is the mean Gaussian KL divergence over leaf pairs with nonzero variance in both samples.
(3) Mean embedding KL (enabled by –embed-dist-kl): each tree is independently embedded into a low-dimensional Euclidean space via classical multidimensional scaling on its cophenetic distances – the same closed-form procedure vine itself uses to initialize its variational posterior (see vine’s –dist-embedding option). Pairwise Euclidean distances between the embedded leaves are computed for each tree (these are invariant to the arbitrary rotation/reflection/translation of each independent embedding, so no alignment across trees is needed). A Gaussian(mean, sd) is fit to each leaf pair’s embedded distance across the sample, and the reported value is the mean Gaussian KL divergence over all leaf pairs.
Both input files must contain one Newick tree per line, sampled over the same set of taxa.
Options
--pairwise-dist-kl, -pAlso compute the mean Gaussian KL divergence between the raw pairwise leaf-distance distributions. This comparison is disabled by default.
--embed-dist-kl, -eAlso compute the mean embedding-distance KL divergence. This comparison is disabled by default.
--dim, -d <n>Embedding dimensionality used for the embedding KL divergence. Defaults to the same formula vine uses when –dimensionality is not specified (based on the number of taxa).
--nthreads, -n <n>Number of threads used by OpenBLAS for the eigendecompositions underlying the embedding KL divergence. Defaults to 1, matching vine’s own default.
--help, -hPrint this help message and exit.