veryfasttree(1)

✨ NAME ✨

Welcome to the veryfasttree(1) manual 🎀 It's a User Commands page, so it's all about the command-line tool.

VeryFastTree is all about speeding up the estimation of phylogenetic trees for large alignments through parallelization and vectorization strategies 🦋

---

✨ DESCRIPTION ✨

Okay so VeryFastTree is a super efficient, highly optimized take on the FastTree-2 tool 💅 It's inspired by FastTree-2 and built to infer approximately-maximum-likelihood phylogenetic trees from nucleotide or protein sequence alignments 🧬

It was made for big alignments, so it leans on parallelization and vectorization to level up performance and scalability. The result is that you can build trees in a fraction of the time it used to take 😭🔥

Bestie, it keeps FastTree-2's integrity. VeryFastTree keeps the same phases, methods, and heuristics for estimating trees, so its topological accuracy is equivalent to FastTree-2 🫶 And here's the big win: unlike the parallel version of FastTree-2, VeryFastTree guarantees deterministic results, so there are no sneaky variations in the output 💖

Transitioning is lowkey effortless. VeryFastTree uses the exact same command line arguments as FastTree-2, so you just swap FastTree-2 for VeryFastTree, keep the same set of options, and your analyses get a major glow-up ✨

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 👑 For models, it uses the Jukes-Cantor or generalized time-reversible (GTR) models of nucleotide evolution, plus the JTT (Jones-Taylor-Thornton 1992) model of amino acid evolution 🌸 To handle rates varying across sites, it gives each site a single rate, which is the "CAT" approximation 🌈 Lastly, to check how reliable each split in the tree is, it computes local support values with the Shimodaira-Hasegawa test. These are the same as PhyML 3's "SH-like local supports" 💜

---

✨ SYNOPSIS ✨

Here's how you actually call it:

VeryFastTree protein_alignment > tree

VeryFastTree -nt nucleotide_alignment > tree

VeryFastTree -nt -gtr < nucleotide_alignment > tree

It accepts alignments in NEXUS, Fasta, Fastq or Phylip interleaved formats, and they can be compressed with ZLib and libBZ2 📦

Common options

These are the greatest hits you'll use most 🍓

• -quiet — shhh, don't report information to you while it runs 🤫
• -nopr — skip the progress indicator
• -log logfile — save intermediate trees, settings, and model details
• -fastest — speeds up the neighbor joining phase and reduces memory usage. It's recommended for more than 50,000 sequences 💅
• -n <number> — analyze multiple alignments (phylip format only). Use this for global bootstrap, with seqboot and CompareToBootstrap.pl 🎀
• -nosupport — don't compute support values
• -intree newick_file — set the starting tree(s)
• -intree1 newick_file — use this one starting tree for all the alignments. It's a faster move for global bootstrap on huge alignments 🚀
• -pseudo — use pseudocounts, which are recommended for highly gapped sequences 🫧
• -gtr — the generalized time-reversible model (nucleotide alignments only) 🧬
• -wag — the 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 — turn off maximum-likelihood
• -nome — turn off minimum-evolution NNIs and SPRs. It's recommended if you're running additional ML NNIs with -intree 🙈
• -nome -mllen — used with -intree to optimize branch lengths for a fixed topology
• -cat # — specify the number of rate categories of sites (default 20). Or use -nocat for constant rates 🌈
• -gamma — after optimizing the tree under the CAT approximation, rescale the lengths to optimize the Gamma20 likelihood
• -constraints constraintAlignment — constrain the topology search. The constraintAlignment should have 1s or 0s to indicate splits 🔒
• -threads <number> (Env: OMP_NUM_THREADS) — the number of threads (n) used in the parallel execution 🧵
• -double-precision — use double precision arithmetic. It's the same as compiling FastTree-2 with -DUSE_DOUBLE 💜
• -ext name — speeds up computations by enabling the vector extensions. Available: AUTO (default), NONE, SSE, SSE3, AVX, AVX2, AVX512 or CUDA ⚡
• -expert — see even more options 👀

Detailed usage for VeryFastTree

Here's the full, extra-long combo breakdown 🧾

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. If you're working with nucleotides, add -nt 🧬

If you don't give it an alignment file, VeryFastTree reads standard input instead 🌊

⋯ part 2 is coming up next, bestie 🦋

✨ Support value options ✨

Okay so by default, VeryFastTree works out local support values by resampling the site likelihoods 1,000 times and running the Shimodaira Hasegawa test 💅. If you use -nome, it'll compute minimum-evolution bootstrap supports instead. Either way, the support values are proportions from 0 to 1 🦋.

• -nome — tells it to compute minimum-evolution bootstrap supports 🌸
• -nosupport — turns support values off completely 🙈
• -boot <number> — uses just n resamples ✨
• -noboot — means no resamples, so don't use them at all 🫶
• -seed <number> — sets the seed used 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, just like relaxed neighbor-joining does. It's giving efficiency 🔥

• -slow — exhaustive search, like NJ or BIONJ but with different gap handling. Heads up though, -slow takes half an hour instead of 8 seconds for 1,250 proteins 😭
• -fastest — searches only the visible set (the top hit for each node). 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)). It also updates out-distances in a very lazy way. -fastest turns -2nd on as well, so if you want to avoid that, use -fastest -no2nd 💀

💜 Top-hit heuristics 💜

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

• -top 0.01 — sets the top-hit list size to 1.0 if it is less than 0.01 🍓
• -notop (or -slow) — turns this feature off so it compares all leaves to each other, and all new joined nodes to each other 🌈
• -topm 1.0 — sets 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. "Close" means d(seed,close) < 0.75 * d(seed, hit of rank 2*m). It also updates the top-hits as joins proceed 🧚
• -close 0.75 — modifies the close heuristic. Lower is more conservative 🙈
• -refresh 0.8 — compares 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 — turns the 2nd-level top hits heuristic on or off. This reduces memory usage and running time, but it may lead to marginal reductions in tree quality. (By default, -fastest turns on -2nd.) 👑

🌸 Join options 🌸

• -nj — regular (unweighted) neighbor-joining, and it's the 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 to be present. A column of 0s and 1s defines a constrained split. Some constraints may be violated, so check violating constraints: in standard error 👀
• -constraintWeight w — how strongly the constraints get weighted. 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) — the number of threads used in parallel execution. If this option isn't set, the value comes from the environment variable OMP_NUM_THREADS. It's the same approach FastTree-2 follows. If n=1, VeryFastTree behaves the same way as FastTree-2 compiled without the -DOPENMP flag 🧵
• -threads-level <number> — the degree of parallelization, in [0 - 4]. Here's the breakdown bestie:
  • 0: VeryFastTree uses the same parallelization strategy as FastTree-2, plus some new parallel blocks.
  • 1: VeryFastTree uses parallel blocks that need additional memory for computation.
  • 2: VeryFastTree accelerates the rounds of ML NNIs using its tree partitioning method.
  • 3 (default): VeryFastTree performs more computations without preserving sequential order.
  • 4: VeryFastTree accelerates the rounds of SPR steps using its tree partitioning method. This 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 it's 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, so deterministic is the preferred choice 💜
• -threads-ptw <number> — (Partitioning Tendency Window) sets the size of the partitioning tendency window used by the tree partitioning algorithm to decide when to stop searching. The window stores the last solutions and checks whether a better one can be found. Increasing the value lets the algorithm explore the tree deeper and potentially find better solutions. The default value is 20 🧚
• -threads-verbose — shows the subtrees assigned to the threads and the theoretical speedup, but only with verbose > 0 📊
• -double-precision — uses double precision arithmetic. It's equivalent to compiling FastTree-2 with -DUSE_DOUBLE 🌈
• -ext name — speeds up computations by enabling vector extensions. Available options: AUTO (default), NONE, SSE, SSE3, AVX, AVX2, AVX512, or CUDA ⚡
• -fastexp <number> — in [0 - 3], selects an alternative implementation for the exponential function exp(x), which has a big impact on performance. The options are:
  • 0: built-in math library with double precision (default)
  • 1: built-in math library with simple precision (not recommended with the -double-precision option)
  • 2: fast implementation that computes an approximation of exp(x) using double precision
  • 3: fast implementation that computes an approximation of exp(x) using simple precision (not recommended with the -double-precision option) 🍓
• -disk-computing — if there isn't enough available RAM for the computation, disk gets used to store extra data when it wasn't needed.

Warning: Using disk to perform the computation will substantially increase the execution time 😭

• -disk-computing-path path — works like -disk-computing, but lets you use a custom path folder to store data 📁
• -disk-dynamic-computing — by default, disk computing only creates files for static data in RAM, so there's no significant performance impact as long as you have available RAM. This option reduces memory usage even further by storing dynamic data on disk. But even if there's enough RAM, it will hurt performance because of the constant creation and deletion of files 💀
• -disk-dynamic-limit <number> — -disk-dynamic-computing can exceed the limit of the memory-mapped file system. If 'memory mapping fails' errors pop up, setting a limit will fix it. In Linux, you can check the limit with sysctl vm.max_map_count. It's important not to use the exact value, and to leave a small margin for other operations that need this feature 🙏
• -relative-progress — shows the relative time to the previous step rather than the absolute time in the progress report ⏱️

🥀 Deprecated 🥀

Heads up: these options are deprecated, so they're not it anymore.

• -logdist — uses logarithmic distances. It's now on by default and obsolete 🙅‍♀️
• -exactml — exact posterior distributions. It's now on by default and obsolete 🙅‍♀️
• -mlexact — exact posterior distributions. It's now on by default and obsolete 🙅‍♀️

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

---

And that's the whole page, bestie! 🫶 Brought to you by the Univ. of Santiago de Compostela, dated June 2023 💖✨