veryfasttree(1)

NAME
VeryFastTree - Speeding up the estimation of phylogenetic trees for large alignments through parallelization and vectorization strategies

DESCRIPTION
VeryFastTree is a highly efficient implementation inspired by the FastTree-2 tool, designed to expedite the inference of approximately-maximum-likelihood phylogenetic trees from nucleotide or protein sequence alignments. It is an optimized implementation designed to accelerate the estimation of phylogenies for large alignments. By leveraging parallelization and vectorization strategies, VeryFastTree significantly improves the performance and scalability of phylogenetic analysis, allowing it to construct phylogenetic trees in a fraction of the time previously required.

Maintaining the integrity of FastTree-2, VeryFastTree retains the same phases, methods, and heuristics used for estimating phylogenetic trees. This ensures that the topological accuracy of the trees produced by VeryFastTree remains equivalent to that of FastTree-2. Moreover, unlike the parallel version of FastTree-2, VeryFastTree guarantees deterministic results, eliminating any potential variations in the output.

To facilitate a seamless transition for users, VeryFastTree adopts the exact same command line arguments as FastTree-2. This means that by simply substituting FastTree-2 with VeryFastTree, and using the same set of options, users can significantly enhance the overall performance of their phylogenetic analyses. VeryFastTree is more accurate than PhyML 3 with default settings, and much more accurate than the distance-matrix methods that are traditionally used for large alignments. VeryFastTree uses the Jukes-Cantor or generalized time-reversible (GTR) models of nucleotide evolution and the JTT (Jones-Taylor-Thornton 1992) model of amino acid evolution. To account for the varying rates of evolution across sites, VeryFastTree uses a single rate for each site (the "CAT" approximation). To quickly estimate the reliability of each split in the tree, VeryFastTree computes local support values with the Shimodaira-Hasegawa test (these are the same as PhyML 3's "SH-like local supports").

SYNOPSIS

VeryFastTree protein_alignment > tree

VeryFastTree -nt nucleotide_alignment > tree

VeryFastTree -nt -gtr < nucleotide_alignment > tree

accepts alignments in NEXUS, Fasta, Fastq or Phylip interleaved formats compressed with ZLib and libBZ2.

  Common options:

-quiet to suppress reporting information

-nopr to suppress progress indicator

-log logfile -- save intermediate trees, settings, and model details

-fastest -- speed up the neighbor joining phase & reduce memory usage (recommended for >50,000 sequences)

-n <number> to analyze multiple alignments (phylip format only) (use for global bootstrap, with seqboot and CompareToBootstrap.pl)

-nosupport to not compute support values

-intree newick_file to set the starting tree(s)

-intree1 newick_file to use this starting tree for all the alignments (for faster global bootstrap on huge alignments)

-pseudo to use pseudocounts (recommended for highly gapped sequences)

-gtr -- generalized time-reversible model (nucleotide alignments only)

-wag -- Whelan-And-Goldman 2001 model (amino acid alignments only)

sequence names and quote names in the output tree (fasta input only; VeryFastTree will not be able to read these trees back in

-noml -- to turn off maximum-likelihood

-nome -- to turn off minimum-evolution NNIs and SPRs (recommended if running additional ML NNIs with -intree)

-nome -mllen with -intree to optimize branch lengths for a fixed topology

-cat # to specify the number of rate categories of sites (default 20) or -nocat to use constant rates

-gamma -- after optimizing the tree under the CAT approximation, rescale the lengths to optimize the Gamma20 likelihood

-constraints constraintAlignment to constrain the topology search constraintAlignment should have 1s or 0s to indicates splits -threads <number> (Env:OMP_NUM_THREADS) number of threads (n) used in the parallel execution

-double-precision -- to use double precision arithmetic. Therefore, it is equivalent to compile FastTree-2 with -DUSE_DOUBLE.

-ext name to speed up computations enabling the vector extensions. Available: AUTO(default), NONE, SSE, SSE3 , AVX, AVX2, AVX512 or CUDA

-expert -- see more options

  Detailed usage for VeryFastTree:
VeryFastTree [-nt] [-n 100] [-quote] [-pseudo | -pseudo 1.0] [-boot 1000 | -nosupport] [-intree starting_trees_file | -intree1 starting_tree_file] [-quiet | -nopr] [-nni 10] [-spr 2] [-noml | -mllen | -mlnni 10] [-mlacc 2] [-cat 20 | -nocat] [-gamma] [-slow | -fastest] [-2nd | -no2nd] [-slownni] [-seed 1253] [-top | -notop] [-topm 1.0 [-close 0.75] [-refresh 0.8]] [-gtr] [-gtrrates ac ag at cg ct gt] [-gtrfreq A C G T] [ -lg | -wag | -trans transitionmatrixfile ] [-matrix Matrix | -nomatrix] [-nj | -bionj] [ -constraints constraintAlignment [ -constraintWeight 100.0 ] ] [-log logfile] [ alignment_file ] [ -threads 1 ] [ -threads-level 3 [ -threads-ptw 20 ] [-threads-verbose] [ -double-precision ] [ -ext AUTO ] [ -fastexp 0 ] [ -disk-computing ] [ -disk-computing-path ./ ] [ -disk-dynamic-limit inf ] [ -relative-progress ] [ -out output_newick_file | > newick_tree]

or

VeryFastTree [-nt] [-matrix Matrix | -nomatrix] [-rawdist] -makematrix [alignment] [-n 100] > phylip_distance_matrix

VeryFastTree supports NEXUS, Fasta, Fastq or Phylip interleaved formats

VeryFastTree supports files compressed with ZLib and libBZ2

By default VeryFastTree expects protein alignments, use -nt for nucleotides

VeryFastTree reads standard input if no alignment file is given

  Input/output options:

-out file print tree in output file instead of stdout

-n <number> read in multiple alignments in. This only works with phylip interleaved format. For example, you can use it with the output from phylip's seqboot. If you use -n, VeryFastTree will write 1 tree per line to standard output.

-nt -- nucleotides instead of protein alignments

-intree newickfile read the starting tree in from newickfile. Any branch lengths in the starting trees are ignored.

-intree with -n will read a separate starting tree for each alignment.

-intree1 newickfile read the same starting tree for each alignment

-verbose lvl level of details during normal operation

-quiet -- do not write to standard error during normal operation (no progress indicator, no options summary, no likelihood values, etc.)

-nopr -- do not write the progress indicator to stderr

-log logfile -- save intermediate trees so you can extract the trees and restart long-running jobs if they crash -log also reports the per-site rates (1 means slowest category)

-quote -- quote sequence names in the output and allow spaces, commas, parentheses, and colons in them but not ' characters (fasta files only)

  Distances:

    Default: For protein sequences, log-corrected distances and an amino acid dissimilarity matrix derived from BLOSUM45 or for nucleotide sequences, Jukes-Cantor distances

    To specify a different matrix, use -matrix FilePrefix or -nomatrix

    Use -rawdist to turn the log-correction off or to use %different instead of Jukes-Cantor (These options affect minimum-evolution computations only; use -trans to affect maximum-likelihoood computations)

-makematrix -- print distance matrix

-rawdist -- to turn the log-correction off

-matrix file to turn the log-correction off

-nomatrix -- to turn the log-correction off

-pseudo [weight] Use pseudocounts to estimate distances between sequences with little or no overlap. (Off by default.) Recommended if analyzing the alignment has sequences with little or no overlap. If the weight is not specified, it is 1.0

  Topology refinement:

    By default, VeryFastTree tries to improve the tree with up to 4*log2(N) rounds of minimum-evolution nearest-neighbor interchanges (NNI), where N is the number of unique sequences, 2 rounds of subtree-prune-regraft (SPR) moves (also min. evo.), and up to 2*log(N) rounds of maximum-likelihood NNIs.

-nni <number> to set the number of rounds of min. evo. NNIs

-spr <number> to set the rounds of SPRs

-noml -- to turn off both min-evo NNIs and SPRs (useful if refining an approximately maximum-likelihood tree with further NNIs)

-sprlength <number> set the maximum length of a SPR move (default 10)

-mlnni <number> to set the number of rounds of maximum-likelihood NNIs

-mlacc <number> Use -mlacc 2 or -mlacc 3 to always optimize all 5 branches at each NNI, and to optimize all 5 branches in 2 or 3 rounds

-mllen -- to optimize branch lengths without ML NNIs. Use -mllen -nome with -intree to optimize branch lengths on a fixed topology

-approxml,-mlapprox -- approximate posterior distributions for a.a.s

-slownni -- to optimize branch lengths without ML NNIs.

  Maximum likelihood model options:

-lg -- Le-Gascuel 2008 model instead of (default) Jones-Taylor-Thorton 1992 model (a.a. only)

-wag -- Whelan-And-Goldman 2001 model instead of (default) Jones-Taylor-Thorton 1992 model (a.a. only)

-gtr -- generalized time-reversible instead of (default) Jukes-Cantor (nt only)

-gtrrates rates set the gtr rates

-gtrfreq seqs set the gtr frequences

-cat # -- specify the number of rate categories of sites (default 20)

-nocat -- no CAT model (just 1 category)

-trans filename use the transition matrix from filename.This is supported for amino acid alignments only.The file must be tab-delimited with columns in the order ARNDCQEGHILKMFPSTWYV*.The additional column named * is for the stationary distribution.Each row must have a row name in the same order ARNDCQEGHILKMFPSTWYV

-gamma -- after the final round of optimizing branch lengths with the CAT model, report the likelihood under the discrete gamma model with the same number of categories. VeryFastTree uses the same branch lengths but optimizes the gamma shape parameter and the scale of the lengths. The final tree will have rescaled lengths. Used with -log, this also generates per-site likelihoods for use with CONSEL, see GammaLogToPaup.pl and documentation on the VeryFastTree web site.

  Support value options:

    By default, VeryFastTree computes local support values by resampling the site likelihoods 1,000 times and the Shimodaira Hasegawa test. If you specify -nome, it will compute minimum-evolution bootstrap supports instead In either case, the support values are proportions ranging from 0 to 1

-nome -- to compute minimum-evolution bootstrap supports

-nosupport -- to turn off support values

-boot <number> to use just n resamples

-noboot -- to no use resamples

-seed <number> to initialize the random number generator

  Searching for the best join:
By default, VeryFastTree combines the 'visible set' of fast neighbor-joining with local hill-climbing as in relaxed neighbor-joining

-slow -- exhaustive search (like NJ or BIONJ, but different gap handling) -slow takes half an hour instead of 8 seconds for 1,250 proteins

-fastest -- search the visible set (the top hit for each node) only Unlike the original fast neighbor-joining, -fastest updates visible(C) after joining A and B if join(AB,C) is better than join(C,visible(C)) -fastest also updates out-distances in a very lazy way, -fastest sets -2nd on as well, use -fastest -no2nd to avoid this

  Top-hit heuristics:

    By default, VeryFastTree uses a top-hit list to speed up search

-top 0.01 set the top-hit list size to 1.0 if it is less than 0.01 -notop -- (or -slow) to turn this feature off and compare all leaves to each other, and all new joined nodes to each other

-topm 1.0 -- set the top-hit list size to parameter*sqrt(N) VeryFastTree estimates the top m hits of a leaf from the top 2*m hits of a 'close' neighbor, where close is defined as d(seed,close) < 0.75 * d(seed, hit of rank 2*m), and updates the top-hits as joins proceed

-close 0.75 -- modify the close heuristic, lower is more conservative

-refresh 0.8 -- compare a joined node to all other nodes if its top-hit list is less than 80% of the desired length, or if the age of the top-hit list is log2(m) or greater

-2nd or -no2nd to turn 2nd-level top hits heuristic on or off This reduces memory usage and running time but may lead to marginal reductions in tree quality. (By default, -fastest turns on -2nd.)

  Join options:

-nj: regular (unweighted) neighbor-joining (default)

-bionj: weighted joins as in BIONJ VeryFastTree will also weight joins during NNIs

  Constrained topology search options:

-constraints alignmentfile an alignment with values of 0, 1, and - Not all sequences need be present. A column of 0s and 1s defines a constrained split. Some constraints may be violated (see 'violating constraints:' in standard error).

-constraintWeight w how strongly to weight the constraints. A value of 1 means a penalty of 1 in tree length for violating a constraint Default: 100.0

  Optimizations:

-threads <number> (Env:OMP_NUM_THREADS) number of threads used in the parallel execution. If this option is not set, the corresponding value will be obtained from the environment variable OMP_NUM_THREADS. This is the same approach followed by FastTree-2. If n=1, VeryFastTree behaves in the same way than FastTree-2 compiled without the -DOPENMP flag

-threads-level <number> in [0 - 4] degree of parallelization. If level is 0, VeryFastTree uses the same parallelization strategy as FastTree-2 with some new parallel blocks. If level is 1, VeryFastTree uses parallel blocks that require additional memory for computation. If level is 2, VeryFastTree accelerates the rounds of ML NNIs using its tree partitioning method. If level is 3 (default), VeryFastTree performs more computations without preserving sequential order. If level is 4, VeryFastTree accelerates the rounds of SPR steps using its tree partitioning method (it can only be used with datasets larger than 2^sprlength + 2).

Note: Each level includes the previous ones, and computation at level 2 and above is performed in a different tree traverse order, so the result may change but is still correct

-threads-mode <number> in [0 - 1] changes the mode of parallelization. If level is 0, VeryFastTree uses non-deterministic parts, some inspired by FastTree-2 but improved. If level is 1 (default), VeryFastTree only uses deterministic parallelization. Since version 4.0, deterministic algorithms are at least faster than non-deterministic ones, making deterministic the preferred choice

-threads-ptw <number> (Partitioning Tendency Window) It sets the size of the partitioning tendency window used by the tree partitioning algorithm to determine when to stop searching. The window stores the last solutions and checks if a better solution can be found. Increasing the value allows the algorithm to explore the tree deeper and potentially find better solutions. The default value is 20.

-threads-verbose -- to show subtrees assigned to the threads and theoretical
 speedup, only with verbose > 0

-double-precision -- to use double precision arithmetic. Therefore, it is equivalent to compile FastTree-2 with -DUSE_DOUBLE

-ext name to speed up computations enabling the vector extensions. Available: AUTO(default), NONE, SSE, SSE3, AVX, AVX2, AVX512 or CUDA

-fastexp <number> in [0 - 3] to select an alternative implementation for the exponential function exp(x), which has a significant impact on performance. Options: 0 - built-in math library with double precision (default), 1 - built-in math library with simple precision (not recommended with -double-precision option), 2 - fast implementation to compute an approximation of exp(x) using double precision, and 3 - fast implementation to compute an approximation of exp(x) using simple precision (not recommended with -double-precision option)

-disk-computing -- if there is not enough available RAM to perform the computation, disk will be used to store extra data when it was not needed. Using disk to perform the computation will substantially increase the execution time

-disk-computing-path path like -disk-computing but using a custom path folder to store data

-disk-dynamic-computing -- by default, disk computing only creates files associated with static data in RAM, which means that there is no significant impact on performance as long as there is available RAM. This option further reduces memory usage by storing dynamic data on disk. However, even if there is enough RAM, it will have a negative impact on performance due to the constant creation and deletion of files

-disk-dynamic-limit <number> -disk-dynamic-computing can exceed the limit of memory-mapped file system. If 'memory mapping fails' errors occur, setting a limit will solve the problem. In Linux, the limit can be checked with 'sysctl vm.max_map_count'. It is important not to use the exact value and leave a small margin for other operations that require this feature

-relative-progress -- to shows relative time to previous step rather than absolute time in progress report

  Deprecated:

-logdist -- use logarithmic distances, now on by default and obsolete

-exactml -- Exact posterior distributions, now on by default and obsolete

-mlexact -- Exact posterior distributions, now on by default and obsolete

For more information, see https://github.com/citiususc/veryfasttree or http://www.microbesonline.org/fasttree/