vine [Variational Inference with Node Embedding] ================================================ .. code-block:: console vine [OPTIONS] alignment.fa > trees.nwk Infer a posterior distribution of phylogenetic trees using a neighbor-joining- or UPGMA-based variational approximation. By default, outputs trees sampled from approximate posterior, with one Newick-formatted tree per line. If the --nj-only option is selected, a single tree will be estimated by NJ (or UPGMA) and output. The --ultrametric option forces use of UPGMA rather than NJ. Supports analysis of either DNA alignments or mutation matrices from CRISPR-based cell lineage barcoding experiments. Initial pairwise distances may be specified either via the alignment/mutation matrix (the default) or by providing a starting distance matrix (--distances) or starting tree (--tree). Variational optimization is by stochastic gradient ascent using the Adam algorithm. By default, an embedding in a Euclidean space is used, but a hyperbolic geometry can be used instead by selecting the --hyperbolic option. By default, the ELBO is estimated using a Taylor approximation but Monte Carlo estimation can be activated using --montecarlo. Typical Commands ---------------- .. code-block:: console For DNA: vine myalignment.fa --logfile log --hky85 > samples.nwk For CRISPR: vine mymatrix.tsv --format CRISPR --logfile log > samples-crispr.nwk Main Options ------------ ``--help, -h`` Display this help message and exit. ``--version, -x`` Display the current version number and exit. ``--dimensionality, -D `` Set dimensionality of the space in which taxa are represented to . Higher values will allow for richer representations of phylogenies but typically take more time to converge. Embedding can be in either a Euclidean (the default) or a hyperbolic (see --hyperbolic) space. If this option is not used, a default value of will be estimated from the number of taxa in the data set and reported to the terminal. ``--format, -i FASTA|SS|PHYLIP|MPM|MAF|CRISPR`` Format of alignment (default is to guess format from file contents). CRISPR format must be specified explicitly. Note that CRISPR forces --ultrametric. ``--hky85, -k`` Use the HKY85 substitution model for likelihood calculations (default is Jukes Cantor). The transition-transversion rate ratio (kappa) will be estimated from the data. ``--gtr, -g`` Use the general time reversible model (GTR) for likelihood calculations. All free parameters will be estimated from the data. ``--dgamma, -K `` Use Yang's discrete gamma model for rate variation across sites, with rate categories. Can be used with DNA substitution models only (not CRISPR). ``--logfile, -l `` Output log with core variational inference metrics to specified file. ``--log-all, -a`` (for use with --logfile) Include full set of parameter estimates in logfile. ``--silent, -X`` Omit updates on progress to terminal. ``--parallel, -j `` Enable parallel threads to accelerate likelihood calculations. Default is 1 (no multithreading). Requires OpenMP. ``--mean, -m `` Output a single tree reflecting the mean of the approximate posterior distribution to the specified file. ``--nexus, -u `` Output complete trees in NEXUS format to the specified file (one tree per sample, or the single NJ/UPGMA tree if --nj-only is used). Unlike --labeled-trees, does not require --migration and does not annotate nodes with cell-state labels. ``--nsamples, -s `` Number of samples to output (default 100) after convergence. ``--seed, -q `` Set the random number generator seed. The default is -1, which selects a time-based seed. ``--nj-only, -0`` Simply estimate and output a single tree using the neighbor-joining algorithm; do not follow with variational inference. If --ultrametric is selected will use UPGMA instead of NJ. ``--treeprior, -P GAMMA|YULE`` Assume a simple prior distribution over tree topologies and branch lengths, based on either a Yule model (integrating over rates) or a Gamma model for total branch length (using a mild shape parameter and an empirical Bayes estimator for expected tree length). Can be used with or without --relclock. ``--relclock, -L`` Assume a relaxed local clock, with lognormally distributed clock rates per branch. Imposes a mild Gaussian prior on log s, where s is the standard deviation of the lognormal clock rates. Can be used with or without --treeprior. ``--ultrametric, -C`` Forces estimated trees to be ultrametric, by using the UPGMA algorithm instead of the neighbor-joining algorithm. On by default with -i CRISPR. ``--crispr-modtype, -Y SITEWISE|GLOBAL`` (default SITEWISE) Model type for CRISPR mutations. May be GLOBAL (single rate matrix across all sites) or SITEWISE (separate rate matrix per site). Use SITEWISE for comparison with LAML or GLOBAL for comparison with TiDeTree. ``--crispr-mutprior, -p UNIF|EMPIRICAL`` (default UNIF) Mutation-rate priors for CRISPR model. May be UNIF (uniform distribution for all edits) or EMPIRICAL (use relative frequencies at tips of tree). Whether distribution is applied across all sites or separately for each one depends on --crispr-modtype. ``--mcmc, -J`` Obtain final samples by MCMC, for a better approximation of the true posterior distribution. Sampling is carried out in the embedding space, starting at the mean of the approximate posterior from variational inference. Burn-in and proposal parameters are adaptively determined. ``--thin, -Q `` (For use with --mcmc) Thinning interval for MCMC sampling after warmup (default 10). ``--embedding, -V `` Output a representation of the final embedding, after convergence of variational inference. Output is a tab-delimited file with a row for each taxon, with the taxon name in the first column followed by one column per embedding dimension. Values represent estimated means of the multivariate normal distribution. Can be used with --nj-only to output the initial embedding without variational inference. Optimization ------------ ``--learnrate, -r `` Set learning rate for Adam algorithm to (default 0.05). ``--miniter, -M `` Set minimum number of iterations before convergence to (default 200). Larger values will lead to longer convergence times but may find better solutions. ``--niterconv, -c `` Set number of iterations over which to average when assessing convergence to (default 50). Larger values will lead to longer convergence times but may find better solutions. ``--montecarlo, -y`` Estimate ELBO by Monte Carlo sampling instead of using a Taylor approximation. ``--batchsize, -b `` (for use with --montecarlo) Set mini-batch size for Monte Carlo estimation to (default 10). Here the minibatch size is the number of phylogenetic trees sampled from the approximate posterior for each update of the variational parameters. Initialization -------------- ``--distances, -d `` Use distance matrix from . In this case, alignment.fa will be ignored ``--names, -n [namelist]`` Specify names for taxa in comma-separated list. For use with --distances. ``--tree, -t `` Obtain pairwise distances from specified tree, rather than from a distance matrix or the alignment. Alterative to --distances. ``--treemodel, -T `` Use the specified PHAST tree model for initialization and likelihood calculations. Overrides use of JC69 or HKY85 substitution models. Covariance ---------- ``--posterior, -A`` Convenience option that selects the recommended combination of options for optimizing the posterior approximation, equivalent to --covar DIST --radial-flow --planar-flow --var-reg 1 (see Siepel et al., Nature Methods, under revision). Not compatible with --hyperbolic. ``--covar, -S CONST|DIAG|DIST|LOWR`` (default CONST) Parameterization to use for covariance matrix for the multivariate normal variational distribution. DIAG assumes no covariance between points but free variance at each point ( \* d.o.f.). CONST is like DIAG but all points have the same variance (1 d.o.f.). DIST assumes a cov. matrix proportional to the (initial) (double centered) distance matrix for the taxa, which can be shown to be the expected structure for Brownian motion along the branches of an unrooted tree (1 d.o.f.). LOWR instead assumes a generally parameterized low-rank approximation of the full covariance matrix ( \* d.o.f. see --rank). ``--rank, -W `` (default 3) For use with --covar LOWR. Rank of low-rank approximation of covariance matrix. ``--radial-flow, -F`` Add a radial-flow layer on top of the multivariate normal variational distribution, to capture radial nonlinearities in the posterior distribution. Estimates a single center point in dimensions as well as a scale parameter alpha and strength parameter beta describing the manner in which points are pulled radially toward the center. This option is currently not compatible with --hyperbolic. ``--planar-flow, -Z`` Add a planar-flow layer on top of the multivariate normal variational distribution, to accommodate directional skew and curvature. Estimates two vectors in dimensions plus an intercept term to define a hyperplane toward which the posterior can be pulled. Can be used in combination with --radial-flow but is not compatible with --hyperbolic. ``--var-reg, -v `` The variance of the approximate posterior tends to shrink so a regularizer is used to keep it from collapsing. (For most parameterizations, an L2 penalty is appiled to the log variance). This option can be used to alter the default penalty by a multiplicative factor. Use values > 1 to inflate the variance further or values between 0 and 1 to give it more latitude to shrink (tends to improve the ELBO). A value of zero will disable regularization. (default = 0) Hyperbolic Geometry ------------------- ``--hyperbolic, -H`` Use an embedding of the taxa in a hyperbolic space rather than a Euclidean one. Taxa are situated on a D-dimensional hyperboloid such that the (D+1)-dimensional Lorentz inner product is fixed at -1, as described in Macaulay et al. PLOS Computational Biology 19(4):e1011084 (2023). The distances between points are computed using the arcosh function and scaled according to the specified curvature (see --negcurvature). ``--negcurvature, -w, `` (for use with --hyperbolic) Set the negative curvature of the hyperbolic embedding space to (default 1). A larger value causes the space to be more curved and stretches how far apart the points occur. As discussed by Macaulay et al. PLOS Computational Biology 19(4):e1011084 (2023), larger values help to ensure additivity of distances but may restrict exploration of topologies. As approaches zero, the space approaches a Euclidean space. Cell-State Modeling ------------------- ``--migration, -G `` (for use with -i CRISPR) Model a migration process among cell states along the branches of the phylogeny, simultaneously with the mutation process (see Staklinski et al., bioRxiv 2025). File must contain a list of exactly the same cell labels as the mutation matrix, each followed by a single string indicating its tissue or other cell state (comma delimited file with two columns per line). ``--migration-rate-prior, -I `` Set the mean of the exponential prior on each migration rate (default 1). A value of 0 disables the prior. ``--primary, -1 `` Consider designated state to be "primary" and force it to be the state at the root of the tree. If the specified state is not present in the migration table, the state space is expanded to include it. Useful when the source state is known, as in models of cancer metastasis. ``--sample-graphs, -O `` Sample cell-state migration graphs and output to specified file in dot format, with one graph per line. Number of graphs equals with one sampled graph per sampled tree. State labels are sampled at interior nodes of each sampled tree using an inside-outside algorithm. ``--labeled-trees, -B `` Output complete trees with cell-state-labeled nodes in nexus format. Samples will be aligned one-to-one with both main output trees and sampled graphs. ``--consensus-graph, -E `` Output edgewise consensus migration-event probabilities in CSV format. Events are labeled as SOURCE_DEST_k (for example LL_RW_1, LL_RW_2), where k is the multiedge encounter index for that directed source-destination pair within each tree. Probabilities are normalized by the total number of sampled trees. Diagnostics ----------- ``--out-dists, -o `` Output distance matrix to . In case of --nj-only, will simply output initial matrix estimated from alignment. Otherwise will represent posterior mean values of distances after convergence of variational algorithm. ``--dist-embedding, -e`` (use with --out-dists) Calculate a distance matrix based on the initial embedding of points. Can be compared with input distances to evaluate fidelity of various embedding schemes. Experimental/Little Used ------------------------ ``--natural-grad, -N`` During stochastic gradient ascent, use approximate natural gradient scale by multiplying each gradient by the corresponding approximate inverse Fisher information. ``--upweight-kld, -U `` The variational objective function (ELBO) is the difference between an expected log likelihood and a KL divergence from a standard multivariate normal prior, but for most data sets the LL strongly dominates. This option will upweight the KLD by the specified factor and therefore push the approximate posterior toward simpler solutions (mean values closer to zero, covariance matrix closer to identity). Use a logfile for guidance. ``--random-start, -R`` Initialize variational inference randomly rather than from initial distance matrix (the default)