VSEARCH

Introduction

The aim of this project is to create an alternative to the USEARCH tool developed by Robert C. Edgar (2010). The new tool should:

• have open source code with an appropriate open source license
• be free of charge, gratis
• have a 64-bit design that handles very large databases and much more than 4GB of memory
• be as accurate or more accurate than usearch
• be as fast or faster than usearch

We have implemented a tool called VSEARCH which supports de novo and reference based chimera detection, clustering, full-length and prefix dereplication, rereplication, reverse complementation, masking, all-vs-all pairwise global alignment, exact and global alignment searching, shuffling, subsampling and sorting. It also supports FASTQ file analysis, filtering, conversion and merging of paired-end reads.

VSEARCH stands for vectorized search, as the tool takes advantage of parallelism in the form of SIMD vectorization as well as multiple threads to perform accurate alignments at high speed. VSEARCH uses an optimal global aligner (full dynamic programming Needleman-Wunsch), in contrast to USEARCH which by default uses a heuristic seed and extend aligner. This usually results in more accurate alignments and overall improved sensitivity (recall) with VSEARCH, especially for alignments with gaps.

VSEARCH binaries are provided for GNU/Linux on three 64-bit processor architectures: x86-64, POWER8 (ppc64le) and ARMv8 (aarch64). Binaries are also provided for MacOS (version 10.9 Mavericks or later) on Intel (x86-64) and Apple Silicon (ARMv8), as well as Windows (64-bit, version 7 or higher, on x86_64). VSEARCH contains dedicated SIMD code for the three processor architectures (SSE2/SSSE3, AltiVec/VMX/VSX, Neon).

CPU \ OS	GNU/Linux	MacOS	Windows
x86_64	✔	✔	✔
ARMv8	✔	✔
POWER8	✔

Various packages, plugins and wrappers are also available from other sources - see below.

The source code compiles correctly with gcc (versions 4.8.5 to 13.0) and llvm-clang (3.8 to 17.0). The source code should also compile on FreeBSD and NetBSD systems.

VSEARCH can directly read input query and database files that are compressed using gzip and bzip2 (.gz and .bz2) if the zlib and bzip2 libraries are available.

Most of the nucleotide based commands and options in USEARCH version 7 are supported, as well as some in version 8. The same option names as in USEARCH version 7 has been used in order to make VSEARCH an almost drop-in replacement. VSEARCH does not support amino acid sequences or local alignments. These features may be added in the future.

Getting Help

If you can't find an answer in the VSEARCH documentation, please visit the VSEARCH Web Forum to post a question or start a discussion.

Example

In the example below, VSEARCH will identify sequences in the file database.fsa that are at least 90% identical on the plus strand to the query sequences in the file queries.fsa and write the results to the file alnout.txt.

./vsearch --usearch_global queries.fsa --db database.fsa --id 0.9 --alnout alnout.txt

Download and install

Source distribution To download the source distribution from a release and build the executable and the documentation, use the following commands:

wget https://github.com/torognes/vsearch/archive/v2.28.1.tar.gz
tar xzf v2.28.1.tar.gz
cd vsearch-2.28.1
./autogen.sh
./configure CFLAGS="-O3" CXXFLAGS="-O3"
make
make install  # as root or sudo make install

You may customize the installation directory using the --prefix=DIR option to configure. If the compression libraries zlib and/or bzip2 are installed on the system, they will be detected automatically and support for compressed files will be included in vsearch. Support for compressed files may be disabled using the --disable-zlib and --disable-bzip2 options to configure. A PDF version of the manual will be created from the vsearch.1 manual file if ps2pdf is available, unless disabled using the --disable-pdfman option to configure. It is recommended to run configure with the options CFLAGS="-O3" and CXXFLAGS="-O3". Other options may also be applied to configure, please run configure -h to see them all. GNU autoconf (version 2.63 or later), automake and the GCC C++ compiler is required to build vsearch. Version 3.82 or later of Make may be required on Linux, while version 3.81 is sufficient on macOS.

The distributed Linux ppc64le and aarch64 binaries were compiled using the C++ cross-compiler. The Windows binary was built using Mingw-w64.

Cloning the repo Instead of downloading the source distribution as a compressed archive, you could clone the repo and build it as shown below. The options to configure as described above are still valid.

git clone https://github.com/torognes/vsearch.git
cd vsearch
./autogen.sh
./configure CFLAGS="-O3" CXXFLAGS="-O3"
make
make install  # as root or sudo make install

Binary distribution Starting with version 1.4.0, binary distribution files containing pre-compiled binaries as well as the documentation will be made available as part of each release. The included executables include support for input files compressed by zlib and bzip2 (with files usually ending in .gz or .bz2).

Binary distributions are provided for x86-64 systems running GNU/Linux, macOS (version 10.7 or higher) or Windows (64-bit, version 7 or higher), 64-bit AMDv8 (aarch64) systems running GNU/Linux or macOS, as well as POWER8 (ppc64le) systems running GNU/Linux.

Download the appropriate executable for your system using the following commands if you are using a Linux x86_64 system:

wget https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-linux-x86_64.tar.gz
tar xzf vsearch-2.28.1-linux-x86_64.tar.gz

Or these commands if you are using a Linux ppc64le system:

wget https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-linux-ppc64le.tar.gz
tar xzf vsearch-2.28.1-linux-ppc64le.tar.gz

Or these commands if you are using a Linux aarch64 (arm64) system:

wget https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-linux-aarch64.tar.gz
tar xzf vsearch-2.28.1-linux-aarch64.tar.gz

Or these commands if you are using a Mac with an Apple Silicon CPU:

wget https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-macos-aarch64.tar.gz
tar xzf vsearch-2.28.1-macos-aarch64.tar.gz

Or these commands if you are using a Mac with an Intel CPU:

wget https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-macos-x86_64.tar.gz
tar xzf vsearch-2.28.1-macos-x86_64.tar.gz

Or if you are using Windows, download and extract (unzip) the contents of this file:

https://github.com/torognes/vsearch/releases/download/v2.28.1/vsearch-2.28.1-win-x86_64.zip

Linux and Mac: You will now have the binary distribution in a folder called vsearch-2.28.1-linux-x86_64 or vsearch-2.28.1-macos-x86_64 in which you will find three subfolders bin, man and doc. We recommend making a copy or a symbolic link to the vsearch binary bin/vsearch in a folder included in your $PATH, and a copy or a symbolic link to the vsearch man page man/vsearch.1 in a folder included in your $MANPATH. The PDF version of the manual is available in doc/vsearch_manual.pdf. Versions with statically compiled libraries are available for Linux systems. These have "-static" in their name, and could be used on systems that do not have all the necessary libraries installed.

Windows: You will now have the binary distribution in a folder called vsearch-2.28.1-win-x86_64. The vsearch executable is called vsearch.exe. The manual in PDF format is called vsearch_manual.pdf. If you want to be able to call vsearch.exe from any command prompt window, you can put the vsearch executable in a folder (for instance C:\Users\<yourname>\bin), and add the new folder to the user Path: open the Environment Variables window by searching for it in the Start menu, Edit user variables, add ;C:\Users\<yourname>\bin to the end of the Path variable, and save your changes. The windows distribution also includes the libbz2.dll and zlib1.dll files required for reading compressed input files. These DLL's have been obtained for mingw-w64 from the MSYS2 platform.

Documentation The VSEARCH user's manual is available in the man folder in the form of a man page. A pdf version (vsearch_manual.pdf) will be generated by make. To install the manpage manually, copy the vsearch.1 file or a create a symbolic link to vsearch.1 in a folder included in your $MANPATH. The manual in both formats is also available with the binary distribution. The manual in PDF form (vsearch_manual.pdf) is also attached to the latest release.

Packages, plugins, and wrappers

Conda package Thanks to the BioConda team, there is now a vsearch package in Conda.

Debian package Thanks to the Debian Med team, there is now a vsearch package in Debian.

FreeBSD ports package Thanks to Jason Bacon, a vsearch FreeBSD ports package is available. Install the binary package with pkg install vsearch, or build from source with additional optimizations.

Galaxy wrapper Thanks to the work of the Intergalactic Utilities Commission members, vsearch is now part of the Galaxy ToolShed.

Homebrew package Thanks to Torsten Seeman, a vsearch package for Homebrew has been made.

Pkgsrc package Thanks to Jason Bacon, a vsearch pkgsrc package is available for NetBSD and other UNIX-like systems. Install the binary package with pkgin install vsearch, or build from source with additional optimizations.

QIIME 2 plugin Thanks to the QIIME 2 team, there is now a plugin called q2-vsearch for QIIME 2.

Converting output to a biom file for use in QIIME and other software

With the from-uccommand in biom 2.1.5 or later, it is possible to convert data in a .uc file produced by vsearch into a biom file that can be read by QIIME and other software. It is described here.

Please note that vsearch version 2.2.0 and later are able to directly output OTU tables in biom 1.0 format as well as the classic and mothur formats.

Implementation details and initial assessment

Please see the paper for details:

Rognes T, Flouri T, Nichols B, Quince C, Mahé F. (2016) VSEARCH: a versatile open source tool for metagenomics. PeerJ 4:e2584 doi: 10.7717/peerj.2584

Dependencies

When compiling VSEARCH the header files for the following two optional libraries are required if support for gzip and bzip2 compressed FASTA and FASTQ input files is needed:

• libz (zlib library) (zlib.h header file) (optional)
• libbz2 (bzip2lib library) (bzlib.h header file) (optional)

VSEARCH will automatically check whether these libraries are available and load them dynamically.

On Windows these libraries are called zlib1.dll and libbz2.dll. These DLL's are included with the released distribution of vsearch 2.28.1 and later.

To create the PDF file with the manual the ps2pdf tool is required. It is part of the ghostscript package.

VSEARCH license and third party licenses

The VSEARCH code is dual-licensed either under the GNU General Public License version 3 or under the BSD 2-clause license. Please see LICENSE.txt for details.

VSEARCH includes code from several other projects. We thank the authors for making their source code available.

VSEARCH includes code from Google's CityHash project by Geoff Pike and Jyrki Alakuijala, providing some excellent hash functions available under a MIT license.

VSEARCH includes code derived from Tatusov and Lipman's DUST program that is in the public domain.

VSEARCH includes public domain code written by Alexander Peslyak for the MD5 message digest algorithm.

VSEARCH includes public domain code written by Steve Reid and others for the SHA1 message digest algorithm.

The VSEARCH distribution includes code from GNU Autoconf which normally is available under the GNU General Public License, but may be distributed with the special autoconf configure script exception.

VSEARCH may include code from the zlib library copyright Jean-loup Gailly and Mark Adler, distributed under the zlib license.

VSEARCH may include code from the bzip2 library copyright Julian R. Seward, distributed under a BSD-style license.

Code

The code is written mostly in C++.

File	Description
align.cc	New Needleman-Wunsch global alignment, serial. Only for testing.
align_simd.cc	SIMD parallel global alignment of 1 query with 8 database sequences
allpairs.cc	All-vs-all optimal global pairwise alignment (no heuristics)
arch.cc	Architecture specific code (Mac/Linux)
attributes.cc	Extraction and printing of attributes in FASTA headers
bitmap.cc	Implementation of bitmaps
chimera.cc	Chimera detection
city.cc	CityHash code
cluster.cc	Clustering (cluster_fast and cluster_smallmem)
cpu.cc	Code dependent on specific cpu features (e.g. ssse3)
cut.cc	Restriction site cutting
db.cc	Handles the database file read, access etc
dbhash.cc	Database hashing for exact searches
dbindex.cc	Indexes the database by identifying unique kmers in the sequences
derep.cc	Dereplication
dynlibs.cc	Dynamic loading of compression libraries
eestats.cc	Produce statistics for fastq_eestats command
fa2fq.cc