Development manual for vsearch 2.32.0, built from the dev branch: it describes changes that are not released yet. The manual for the current release is published separately.

NAME

vsearch — a versatile open-source tool for metabarcoding and metagenomics

SYNOPSIS

vsearch <command> [file] [options]

(see below for a list of all available commands)

DESCRIPTION

vsearch is a versatile open-source tool for microbiome analysis, including chimera detection, clustering, dereplication and rereplication, extraction, FASTA/FASTQ/SFF file processing, masking, orienting, pairwise alignment, restriction site cutting, searching, shuffling, sorting, subsampling, and taxonomic classification of amplicon sequences for metabarcoding, metagenomics, genomics, and population genetics.

Each command is described in a dedicated manpage. For example, type man vsearch-usearch_global to read about the --usearch_global command. Command manpages belong to section 1 (executable programs). Format and reference manpages belong to sections 5 and 7 respectively; for example, type man 5 vsearch-fastq to read about the fastq format as used by vsearch.

The same pages are published online at https://torognes.github.io/vsearch/, where they can be browsed and searched.

Shell auto-completion of commands, options and filenames is available for bash, zsh and fish. make install places the three scripts in the directories those shells search, so pressing the tab key while typing a vsearch command line suggests the commands, then the options that the chosen command accepts, and completes filenames. See the Shell auto-completion section of the README for per-user installation and for enabling completion without installing system-wide.

VSEARCH COMMANDS

General

vsearch-help(1): List available commands and options.
vsearch-version(1): Write version information, citation, and compression support status.

Chimera detection

vsearch-uchime_denovo(1): Detect chimeras de novo using the UCHIME algorithm.
vsearch-uchime2_denovo(1): Detect chimeras de novo using the UCHIME2 algorithm.
vsearch-uchime3_denovo(1): Detect chimeras de novo using the UCHIME2 algorithm with a stricter abundance skew.
vsearch-uchime_ref(1): Detect chimeras using a reference database.
vsearch-chimeras_denovo(1): Detect chimeras de novo in long exact sequences.

Clustering

vsearch-cluster_fast(1): Clusterize sequences sorted by decreasing length.
vsearch-cluster_size(1): Clusterize sequences sorted by decreasing abundance.
vsearch-cluster_smallmem(1): Clusterize pre-sorted sequences using minimal memory.
vsearch-cluster_unoise(1): Denoise amplicon sequences using the UNOISE3 algorithm.

Dereplication and rereplication

vsearch-fastx_uniques(1): Merge strictly identical fasta or fastq sequences.
vsearch-derep_fulllength(1): Merge strictly identical fasta sequences (deprecated; use --fastx_uniques).
vsearch-derep_id(1): Merge identical fasta sequences sharing the same label.
vsearch-derep_prefix(1): Merge fasta or fastq sequences with identical prefixes.
vsearch-derep_smallmem(1): Merge strictly identical sequences using minimal memory.
vsearch-rereplicate(1): Use abundance values to rereplicate fasta sequences.

Extraction of sequences

vsearch-fastx_getseq(1): Extract a sequence from a fasta or fastq file by label.
vsearch-fastx_getseqs(1): Extract sequences from a fasta or fastq file by label.
vsearch-fastx_getsubseq(1): Extract a subsequence from a fasta or fastq file by label.

FASTA/FASTQ/SFF file processing

vsearch-fasta2fastq(1): Convert fasta entries into fastq entries with fake quality scores.
vsearch-fastq_chars(1): Analyze a fastq file to identify the quality encoding and range of quality score values used.
vsearch-fastq_convert(1): Convert between fastq encoding variants.
vsearch-fastq_eestats(1): Report per-position quality and expected error statistics.
vsearch-fastq_eestats2(1): Report read retention across combinations of length and expected error cutoffs.
vsearch-fastq_filter(1): Trim and filter fastq sequences.
vsearch-fastq_join(1): Join paired-end reads into one sequence with a gap.
vsearch-fastq_mergepairs(1): Merge paired-end reads by aligning overlapping regions.
vsearch-fastq_stats(1): Analyze fastq sequences and output detailed statistics.
vsearch-fastx_filter(1): Trim and filter fasta or fastq sequences.
vsearch-fastx_revcomp(1): Reverse-complement fasta or fastq sequences.
vsearch-fastx_syncpairs(1): Reorder paired reads so mates match across both files.
vsearch-sff_convert(1): Convert an SFF file to fastq.

Masking

vsearch-fastx_mask(1): Mask low-complexity regions in fasta or fastq sequences.
vsearch-maskfasta(1): Mask low-complexity regions in fasta sequences (deprecated; use --fastx_mask).

Orienting

vsearch-orient(1): Use a reference database to orient fasta or fastq sequences.

Pairwise alignment

vsearch-allpairs_global(1): Perform global pairwise alignments of all sequence pairs.

Restriction site cutting

vsearch-cut(1): Use a restriction pattern to cut fasta sequences.

Searching

vsearch-search_exact(1): Search for exact full-length matches against a database.
vsearch-usearch_global(1): Search sequences against a reference database using global alignment.

Sorting, shuffling and scrambling

vsearch-scramble(1): Randomize the nucleotide order within each fasta or fastq entry.
vsearch-shuffle(1): Randomize the order of fasta or fastq entries.
vsearch-sortbylength(1): Sort fasta or fastq sequences by decreasing length.
vsearch-sortbysize(1): Sort fasta or fastq sequences by decreasing abundance.

Subsampling

vsearch-fastx_subsample(1): Randomly subsample fasta or fastq sequences.

Taxonomic classification

vsearch-sintax(1): Classify sequences using the SINTAX algorithm.

UDB database handling

vsearch-makeudb_usearch(1): Create a UDB database file from a fasta file.
vsearch-udb2fasta(1): Extract sequences from a UDB database file into a fasta file.
vsearch-udbinfo(1): Display information about a UDB database file.
vsearch-udbstats(1): Report statistics about indexed words in a UDB database file.

FILE FORMATS

vsearch-cigar(5): The CIGAR (Compact Idiosyncratic Gapped Alignment Report) format, used by vsearch to encode pairwise alignments.
vsearch-fasta(5): The fasta format, as used by vsearch.
vsearch-fastq(5): The fastq format, as used by vsearch.
vsearch-sff(5): The Standard Flowgram Format (SFF), used by Roche 454 and early Ion Torrent PGM sequencing platforms.
vsearch-udb(5): The UDB (USEARCH database) binary format, containing fasta sequences and a pre-computed k-mer index.

REFERENCE PAGES

vsearch-expected_error(7): A quality summary metric for fastq sequences.
vsearch-history(7): New features and important modifications, release by release.
vsearch-nucleotides(7): The IUPAC nucleotide symbols accepted by vsearch.
vsearch-pairwise_alignment_parameters(7): The pairwise alignment model implemented in vsearch.
vsearch-usearch(7): What vsearch shares with usearch, and what it does differently.
vsearch-userfields(7): The output fields available with the --userout option.

CITATION

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

REPORTING BUGS

Submit suggestions and bug-reports at https://github.com/torognes/vsearch/issues, send a pull request on https://github.com/torognes/vsearch, or compose a friendly or curmudgeont e-mail to Torbjørn Rognes (torognes@ifi.uio.no).

AVAILABILITY

Source code and binaries are available at https://github.com/torognes/vsearch.

These manual pages are also published online at https://torognes.github.io/vsearch/.

COPYRIGHT

Contact: Torbjørn Rognes torognes@ifi.uio.no, Department of Informatics, University of Oslo, PO Box 1080 Blindern, NO-0316 Oslo, Norway

This software is dual-licensed and available under a choice of one of two licenses, either under the terms of the GNU General Public License version 3 or the BSD 2-Clause License.

GNU General Public License version 3

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

The BSD 2-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ACKNOWLEDGMENTS

We would like to thank the authors of the following projects 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.
vsearch binaries may include code from the zlib library, copyright Jean-Loup Gailly and Mark Adler.
vsearch binaries may include code from the bzip2 library, copyright Julian R. Seward.