Vsearch Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 44

vsearch(1) USER COMMANDS vsearch(1)

NAME vsearch — chimera detection, clustering, dereplication and rereplication, FASTA/FASTQ ﬁle processing,

masking, pairwise alignment, searching, shufﬂing, sorting, subsampling, and taxonomic classiﬁcation of

amplicons for metagenomics, genomics, and population genetics.

SYNOPSIS

Chimera detection:

vsearch (--uchime_denovo | --uchime2_denovo | --uchime3_denovo)fastaﬁle (--chimeras |

--nonchimeras | --uchimealns | --uchimeout) outputﬁle [options]

vsearch --uchime_ref fastaﬁle (--chimeras | --nonchimeras | --uchimealns | --uchimeout) outputﬁle

--db fastaﬁle [options]

Clustering:

vsearch (--cluster_fast | --cluster_size | --cluster_smallmem | --cluster_unoise) fastaﬁle (--alnout |

--proﬁle | --samout | --uc | --userout) outputﬁle --id real [options]

Dereplication and rereplication:

vsearch (--derep_fulllength | --derep_preﬁx) fastaﬁle (--output | --uc) outputﬁle [options]

vsearch --rereplicate fastaﬁle --output outputﬁle [options]

FASTA/FASTQ ﬁle processing:

vsearch --fastq_chars fastqﬁle [options]

vsearch --fastq_convert fastqﬁle --fastqout outputﬁle [options]

vsearch (--fastq_eestats | --fastq_eestats2) fastqﬁle --output outputﬁle [options]

vsearch --fastq_ﬁlter fastqﬁle (--fastaout | --fastaout_discarded | --fastqout | --fastqout_discarded)

outputﬁle [options]

vsearch --fastq_join fastqﬁle --reverse fastqﬁle (--fastaout | --fastqout) outputﬁle [options]

vsearch --fastq_mergepairs fastqﬁle --reverse fastqﬁle (--fastaout | --fastqout | --fastaout_not-

merged_fwd | --fastaout_notmerged_rev|--fastqout_notmerged_fwd | --fastqout_notmerged_rev|

--eetabbedout) outputﬁle [options]

vsearch --fastq_stats fastqﬁle [--log logﬁle][options]

vsearch --fastx_revcomp fastxﬁle (--fastaout | --fastqout) outputﬁle [options]

vsearch --sff_convert sff-ﬁle --fastqout outputﬁle [options]

Masking:

vsearch --fastx_mask fastxﬁle (--fastaout | --fastqout) outputﬁle [options]

vsearch --maskfasta fastaﬁle --output outputﬁle [options]

Pairwise alignment:

--uc | --userout) outputﬁle (--acceptall | --id real)[options]

Searching:

vsearch --search_exact fastaﬁle --db fastaﬁle (--alnout | --biomout | --blast6out |

--mothur_shared_out | --otutabout | --samout | --uc | --userout) outputﬁle [options]

vsearch --usearch_global fastaﬁle --db fastaﬁle (--alnout | --biomout | --blast6out |

--mothur_shared_out | --otutabout | --samout | --uc | --userout) outputﬁle --id real [options]

Shufﬂing and sorting:

vsearch (--shufﬂe | --sortbylength | --sortbysize) fastaﬁle --output outputﬁle [options]

Subsampling:

vsearch --fastx_subsample fastaﬁle (--fastaout | --fastqout) outputﬁle (--sample_pct real |--sam-

ple_size positive integer)[options]

version 2.10.4 January 4, 2019 1

vsearch(1) USER COMMANDS vsearch(1)

Taxonomic classiﬁcation:

vsearch --sintax fastaﬁle --db fastaﬁle --tabbedout outputﬁle [--sintax_cutoff real][options]

UDB database handling:

vsearch --makeudb_usearch fastaﬁle --output outputﬁle [options]

vsearch --udb2fasta udbﬁle --output outputﬁle [options]

vsearch (--udbinfo | --udbstats) udbﬁle [options]

DESCRIPTION

Environmental or clinical molecular diversity studies generate large volumes of amplicons (e.g.; SSU-

rRNAsequences) that need to be checked for chimeras, dereplicated, masked, sorted, searched, clustered or

compared to reference sequences. The aim of vsearch is to offer a all-in-one open source tool to perform

these tasks, using optimized algorithm implementations and harvesting the full potential of modern com-

puters, thus providing fast and accurate data processing.

Comparing nucleotide sequences is at the core of vsearch.Tospeed up comparisons, vsearch implements

an extremely fast Needleman-Wunsch algorithm, making use of the Streaming SIMD Extensions (SSE2) of

post-2003 x86-64 CPUs. If SSE2 instructions are not available, vsearch exits with an error message. On

Power8 CPUs it will use AltiVec/VSX/VMX instructions. Memory usage increases rapidly with sequence

length: for example comparing twosequences of length 1 kb requires 8 MB of memory per thread, and

comparing two10kbsequences requires 800 MB of memory per thread. For comparisons involving

sequences with a length product greater than 25 million (for example twosequences of length 5 kb),

vsearch uses a slower alignment method described by Hirschberg(1975) and Myers and Miller (1988),

with much smaller memory requirements.

Input

vsearch accept as input fasta or fastq ﬁles containing one or several nucleotidic entries. In fasta ﬁles, each

nucleotidic entry is made of a header and a sequence. The header is deﬁned as the string comprised

between the ’>’ symbol and the ﬁrst space, tab or the end of the line, whichevercomes ﬁrst. Additionally,if

the header matches integeras the number of occurrences (or abundance) of the sequence in the study.That

abundance information is used or created during chimera detection, clustering, dereplication, sorting and

searching.

The sequence is deﬁned as a string of IUPAC symbols (ACGTURYSWKMDBHVN), starting after the end

of the identiﬁer line and ending before the next identiﬁer line, or the ﬁle end. vsearch silently ignores ascii

characters 9 to 13, and exits with an error message if ascii characters 0 to 8, 14 to 31, ’.’or’-’ are present.

All other ascii or non-ascii characters are stripped and complained about in a warning message.

In fastq ﬁles, each entry is made of sequence header starting with a symbol ’@’, a nucleotidic sequence

(same rules as for fasta sequences), a quality header starting with a symbol ’+’ and a string of ASCII char-

acters (offset 33 or 64), each one encoding the quality value of the corresponding position in the nucleotidic

sequence.

vsearch operations are case insensitive,except when soft masking is activated. Masking is automatically

applied during chimera detection, clustering, masking, pairwise alignment and searching. Soft masking is

speciﬁed with the options ’--dbmask soft’ (for searching and chimera detection with a reference) or

’--qmask soft’ (for searching, de novo chimera detection, clustering and masking). When using soft mask-

ing, lower case letters indicate masked symbols, while upper case letters indicate regular symbols. Masked

symbols are neverincluded in the unique indexwords used for sequence comparisons, otherwise theyare

treated as normal symbols.

When comparing sequences during chimera detection, dereplication, searching and clustering, T and U are

considered identical, regardless of their case. If twosymbols are not identical, their alignment result in a

negative mismatch score (default -4), except if one or both of the symbols are ambiguous (RYSWKMDB-

HVN) in which case the score is zero. Alignment of twoidentical ambiguous symbols (for example, R vs

R) also receivesascore of zero.

vsearch can read data from standard ﬁles and write to standard ﬁles, but it can also read from pipes and

write to pipes! For example, multiple fasta ﬁles can be piped into vsearch for dereplication. Todoso, ﬁle

version 2.10.4 January 4, 2019 2

vsearch(1) USER COMMANDS vsearch(1)

names can be replaced with:

-the symbol ’-’, representing ’/dev/stdin’ for input ﬁles or ’/dev/stdout’ for output ﬁles,

-anamed pipe created with the command mkﬁfo,

-aprocess substitution ’<(command)’ as input or ’>(command)’ as output.

vsearch can automatically read compressed gzip or bzip2 ﬁles if the appropriate libraries are present during

the compilation. vsearch can also read pipes streaming compressed gzip or bzip2 data if the options

--gzip_decompress or --bzip2_decompress are selected. When reading from a pipe, the progress indicator is

not updated.

Options

vsearch recognizes a large number of command-line options. For easier navigation, options are grouped

belowbytheme (chimera detection, clustering, dereplication and rereplication, FASTA/FASTQ ﬁle pro-

cessing, masking, pairwise alignment, searching, shufﬂing, sorting, and subsampling). Westart with the

general options that apply to all themes. Options may start with a single (-) or double dash (--). Option

names may be shortened as long as theyare not ambiguous (e.g. --derep_f).

General options:

--bzip2_decompress

When reading from a pipe streaming bzip2-compressed data, decompress the data. That

option is not needed when reading from a standard bzip2-compressed ﬁle.

--fasta_width positive integer

Fasta ﬁles produced by vsearch are wrapped (sequences are written on lines of integer

nucleotides, 80 by default). Set that value to zero to eliminate the wrapping.

--gzip_decompress

When reading from a pipe streaming gzip-compressed data, decompress the data. That

option is not needed when reading from a standard gzip-compressed ﬁle.

--help | -h Display help text and exit.

--log ﬁlename

Write messages to the speciﬁed log ﬁle. Information written includes program version,

amount of memory available, number of cores and command line options, and if need

be, informational messages, warnings and fatal errors. The start and ﬁnish times are

also recorded as well as the elapsed time and the maximum amount of memory con-

sumed. The different vsearch commands can also write additional informations to

the log ﬁle.

--maxseqlength positive integer

All vsearch operations discard sequences of length equal or greater than integer

(50,000 nucleotides by default).

--minseqlength positive integer

All vsearch operations discard sequences of length smaller than integer:1nucleotide

by default for sorting or shufﬂing, 32 nucleotides for clustering, dereplication or

searching.

--no_progress

Do not showthe gradually increasing progress indicator.

--notrunclabels

Do not truncate sequence labels at ﬁrst space or tab, use the full header in output ﬁles.

--quiet Suppress all messages to stdout and stderr except for warnings and fatal error mes-

sages.

version 2.10.4 January 4, 2019 3

vsearch(1) USER COMMANDS vsearch(1)

--threads positive integer

Number of computation threads to use (1 to 256). The number of threads should be

lesser or equal to the number of available CPU cores. The default is to use all available

resources and to launch one thread per logical core. The following commands are

multi-threaded: allpairs_global, cluster_fast, cluster_size, cluster_smallmem,

fastq_mergepairs, maskfasta, search_exact, uchime_ref, and usearch_global. Only one

thread is used for the other commands.

--version | -v

Output version information and exit.

Chimera detection options:

Chimera detection is based on a scoring function controlled by ﬁveoptions (--dn, --mindiffs,

--mindiv, --minh, --xn). Sequences are ﬁrst sorted by decreasing abundance, if available, and com-

pared on their plus strand only (case insensitive).

Input sequences are masked as speciﬁed with the --qmask and --hardmask options. Masking of the

database for reference based chimera detection is speciﬁed with the --dbmask option.

In de novo mode, input fasta ﬁle should present abundance annotations (i.e. a pattern [;]size=inte-

ger[;] in the fasta header). Input order matters for chimera detection, so we recommend to sort

sequences by decreasing abundance (default of --derep_fulllength command). If your sequence set

needs to be sorted, please see the --sortbysize command in the sorting section.

--abskew real

When using --uchime_denovo,the abundance skew isused to distinguish in a three-

wayalignment which sequence is the chimera and which are the parents. The assump-

tion is that chimeras appear later in the PCR ampliﬁcation process and are therefore

less abundant than their parents. For --uchime3_denovo the default value is 16.0. For

the other commands, the default value is 2.0, which means that the parents should be at

least 2 times more abundant than their chimera. Anypositive value equal or greater

than 1.0 can be used.

--alignwidth positive integer

When using --uchimealns, set the width of the three-way alignments (80 nucleotides by

default). Set to zero to eliminate wrapping.

--borderline ﬁlename

Output borderline chimeric sequences to ﬁlename,infasta format. Borderline chimeric

sequences are sequences that have a high enough score but which are not sufﬁciently

different from their closest parent.

--chimeras ﬁlename

Output chimeric sequences to ﬁlename,infasta format. Output order may vary when

using multiple threads.

--db ﬁlename

When using --uchime_ref, detect chimeras using the fasta-formatted reference

sequences contained in ﬁlename.Reference sequences are assumed to be chimera-free.

Chimeras cannot be detected if their parents, or sufﬁciently close relatives, are not

present in the database.

--dn real No vote pseudo-count, corresponding to the parameter nin the chimera scoring func-

tion (default value is 1.4).

--fasta_score

Add the chimera score to the headers in the fasta output ﬁles for chimeras, non-

chimeras and borderline sequences, using the format

version 2.10.4 January 4, 2019 4

vsearch(1) USER COMMANDS vsearch(1)

--mindiffs positive integer

Minimum number of differences per segment (default value is 3). The parameter is

ignored with --uchime2_denovo and --uchime3_denovo.

--mindiv real

Minimum divergence from closest parent (default value is 0.8). The parameter is

ignored with --uchime2_denovo and --uchime3_denovo.

--minh real

Minimum score (h). Increasing this value tends to reduce the number of false positives

and to decrease sensitivity.Default value is 0.28, and values ranging from 0.0 to 1.0

included are accepted. The parameter is ignored with --uchime2_denovo and

--uchime3_denovo.

--nonchimeras ﬁlename

Output non-chimeric sequences to ﬁlename,infasta format. Output order may vary

when using multiple threads.

--relabel string

Relabel sequences using the preﬁx string and a ticker (1, 2, 3, etc.) to construct the new

headers. Use --sizeout to conservethe abundance annotations.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Relabel sequences using the MD5 message digest algorithm applied to each sequence.

Former sequence headers are discarded. The sequence is converted to upper case and

each ’U’ is replaced by a ’T’ before computation of the digest. The MD5 digest is a

cryptographic hash function designed to minimize the probability that twodifferent

inputs give the same output, evenfor very similar,but non-identical inputs. Still, there

is a very small, but non-zero, probability that twodifferent inputs give the same digest

(i.e. a collision). MD5 generates a 128-bit (16-byte) digest that is represented by 16

hexadecimal numbers (using 32 symbols among 0123456789abcdef). Use --sizeout to

conservethe abundance annotations.

--relabel_sha1

Relabel sequences using the SHA1 message digest algorithm applied to each sequence.

It is similar to the --relabel_md5 option but uses the SHA1 algorithm instead of the

MD5 algorithm. SHA1 generates a 160-bit (20-byte) digest that is represented by 20

hexadecimal numbers (40 symbols). The probability of a collision (twonon-identical

sequences resulting in the same digest) is smaller for the SHA1 algorithm than it is for

the MD5 algorithm.

--self When using --uchime_ref, ignore a reference sequence when its label matches the label

of the query sequence (useful to estimate false-positive rate in reference sequences).

--selﬁd When using --uchime_ref, ignore a reference sequence when its nucleotide sequence is

strictly identical to the nucleotidic sequence of the query.

--sizeout When relabelling, add abundance annotations to fasta headers (using the format

’;size=integer;’).

--uchime_denovo ﬁlename

Detect chimeras present in the fasta-formatted ﬁlename,without external references

(i.e. de novo). Automatically sort the sequences in ﬁlename by decreasing abundance

beforehand (see the sorting section for details). Multithreading is not supported.

--uchime2_denovo ﬁlename

Detect chimeras present in the fasta-formatted ﬁlename,using the UCHIME2 algo-

rithm. This algorithm is designed for denoised amplicons (see --cluster_unoise). Auto-

matically sort the sequences in ﬁlename by decreasing abundance beforehand (see the

version 2.10.4 January 4, 2019 5

vsearch(1) USER COMMANDS vsearch(1)

sorting section for details). Multithreading is not supported.

--uchime3_denovo ﬁlename

Detect chimeras present in the fasta-formatted ﬁlename,using the UCHIME2 algo-

rithm. The only difference from --uchime2_denovo isthat the default minimum abun-

dance skew (--abskew)isset to 16.0 rather than 2.0.

--uchime_ref ﬁlename

Detect chimeras present in the fasta-formatted ﬁlename by comparing them with refer-

ence sequences (option --db). Multithreading is supported.

--uchimealns ﬁlename

Write the three-way global alignments (parentA, parentB, chimera) to ﬁlename using a

human-readable format. Use --alignwidth to modify alignment length. Output order

may vary when using multiple threads. All sequences are converted to upper case

before alignment. Lower case letters indicate disagreement in the alignment.

--uchimeout ﬁlename

Write chimera detection results to ﬁlename using a 18-ﬁeld, tab-separated uchime-like

format. Use --uchimeout5 to use a format compatible with usearch v5 and earlier ver-

sions. Rows output order may vary when using multiple threads.

1. score: higher score means a more likely chimeric alignment.

2. Q: query sequence label.

3. A: parent A sequence label.

4. B: parent B sequence label.

5. T:top parent sequence label (i.e. parent most similar to the query). That

ﬁeld is removedwhen using --uchimeout5.

6. idQM: percentage of similarity of query (Q) and model (M) constructed

as a part of parent A and a part of parent B.

7. idQA: percentage of similarity of query (Q) and parent A.

8. idQB: percentage of similarity of query (Q) and parent B.

9. idAB: percentage of similarity of parent A and parent B.

10. idQT:percentage of similarity of query (Q) and top parent (T).

11. LY: yes votes in the left part of the model.

12. LN: no votes in the left part of the model.

13. LA: abstain votes in the left part of the model.

14. RY: yes votes in the right part of the model.

15. RN: no votes in the right part of the model.

16. RA: abstain votes in the right part of the model.

17. div: divergence, deﬁned as (idQM - idQT).

18. YN: query is chimeric (Y), or not (N), or is a borderline case (?).

--uchimeout5

When using --uchimeout, write chimera detection results using a 17-ﬁeld, tab-separated

uchime-likeformat (drop the 5th ﬁeld of --uchimeout), compatible with usearch ver-

sion 5 and earlier versions.

--xn real No vote weight, corresponding to the parameter beta in the scoring function (default

value is 8.0).

version 2.10.4 January 4, 2019 6

vsearch(1) USER COMMANDS vsearch(1)

--xsize Strip abundance information from the headers when writing the output ﬁle.

Clustering options:

vsearch implements a single-pass, greedy centroid-based clustering algorithm, similar to the algo-

rithms implemented in usearch, DNAclust and sumaclust for example. Important parameters are

the global clustering threshold (--id) and the pairwise identity deﬁnition (--iddef).

Input sequences are masked as speciﬁed with the --qmask and --hardmask options.

--biomout ﬁlename

Generate an OTU table in the biom version 1.0 JSON ﬁle format as speciﬁed at

http://biom-format.org/documentation/format_versions/biom-1.0.html. The format

describes howtostore a sparse matrix containing the abundances of the OTUs in the

different samples. This format is much more efﬁcient than the classic and mothur OTU

table formats available with the --otutabout and --mothur_shared_out options, respec-

tively,and is recommended at least for large tables. The OTUs are represented by the

cluster centroids. Taxonomy information will be included for the OTUs if available.

Sample identiﬁers will be extracted from the headers of all sequences in the input ﬁle.

If the header contains ’;sample=abc123;’ or ’;barcodelabel=abc123;’ or a similar string

somewhere, then the givensample identiﬁer (here ’abc123’) will be used. The semi-

colon is not mandatory at the beginning or end of the header.The sample identiﬁer may

contain anyprintable character except semicolons. If no such sample label is found, the

identiﬁer in the initial part of the header will be used, but only letters, digits and under-

scores are allowed. OTU identiﬁers will be extracted from the headers of the cluster

centroid sequences. If the header contains ’;otu=def789;’ or a similar string some-

where, then the givenOTU identiﬁer (here ’def789’) will be used. The semicolon is not

mandatory at the beginning or end of the header.The OTU identiﬁer may contain any

printable character except semicolons. If no such OTU label is found, the identiﬁer in

the initial part of the header will be used, and all characters except semicolons are

allowed. Alternatively,OTU identifers can be generated using the relabelling options

(--relabel, --relabel_sha1 or --relabel_md5). Taxonomy information, if present, will

also be extracted from the headers of the centroid sequences. If the header contains

’;tax=Homo_sapiens;’ or a similar string somewhere, then the giventaxonomy infor-

mation (here ’Homo_sapiens’) will be used. The semicolon is not mandatory at the

beginning or end of the header.The taxonomy information may contain anyprintable

character except semicolons. If an OTU table in the biom version 2.1 HDF5 ﬁle format

is required, the biom utility may be used as described at http://biom-format.org/docu-

mentation/biom_conversion.html.

--centroids ﬁlename

Output cluster centroid sequences to ﬁlename,infasta format. The centroid is the

sequence that seeded the cluster (i.e. the ﬁrst sequence of the cluster).

--clusterout_id

Add cluster identiﬁer information to the output ﬁles when using the --consout and

--proﬁle options.

--clusterout_sort

Sort output ﬁles by decreasing abundance when using the --consout, --msaout and

--proﬁle options.

--cluster_fast ﬁlename

Clusterize the fasta sequences in ﬁlename,automatically sort by decreasing sequence

length beforehand.

--cluster_size ﬁlename

Clusterize the fasta sequences in ﬁlename,automatically sort by decreasing sequence

abundance beforehand.

version 2.10.4 January 4, 2019 7

vsearch(1) USER COMMANDS vsearch(1)

--cluster_smallmem ﬁlename

Clusterize the fasta sequences in ﬁlename without automatically modifying their order

beforehand. Sequence are expected to be sorted by decreasing sequence length, unless

--usersort is used.

--cluster_unoise ﬁlename

Perform denoising of the fasta sequences in ﬁlename according to the UNOISE version

3algorithm by Robert Edgar,but without the chimera removalstep. The options --min-

size (default 8) and --unoise_alpha (default 2.0) may be speciﬁed. Chimera removal(de

novo)should be performed afterwards with --uchime3_denovo.

--clusters string

Output each cluster to a separate fasta ﬁle using the preﬁx string and a ticker (0, 1, 2,

etc.) to construct the path and ﬁlenames.

--consout ﬁlename

Output cluster consensus sequences to ﬁlename.For each cluster,amultiple alignment

is computed, and a consensus sequence is constructed by taking the majority symbol

(nucleotide or gap) from each column of the alignment. Columns containing a majority

of gaps are skipped, except for terminal gaps.

--cons_truncate

This command is ignored. A warning is issued.

--id real Do not add the target to the cluster if the pairwise identity with the centroid is lower

than real (value ranging from 0.0 to 1.0 included). The pairwise identity is deﬁned as

the number of (matching columns) / (alignment length - terminal gaps). That deﬁnition

can be modiﬁed by --iddef.

--iddef 0|1|2|3|4

Change the pairwise identity deﬁnition used in --id. Values accepted are:

0. CD-HIT deﬁnition: (matching columns) / (shortest sequence length).

1. edit distance: (matching columns) / (alignment length).

2. edit distance excluding terminal gaps (same as --id).

3. Marine Biological Lab deﬁnition counting each gap opening (internal or

terminal) as a single mismatch, whether or not the gap was extended: 1.0

-[(mismatches + gap openings)/(longest sequence length)]

4. BLAST deﬁnition, equivalent to --iddef 1 in a context of global pairwise

alignment.

--minsize positive integer

Specify the minimum abundance of sequences for denoising using --cluster_unoise.

The default is 8.

--msaout ﬁlename

Output a multiple sequence alignment and a consensus sequence for each cluster to ﬁle-

name,infasta format. Be warned that vsearch computes center star multiple sequence

alignments using a fast method whose accuracycan decrease signiﬁcantly when using

lowpairwise identity thresholds. The consensus sequence is constructed by taking the

majority symbol (nucleotide or gap) from each column of the alignment. Columns con-

taining a majority of gaps are skipped, except for terminal gaps.

--mothur_shared_out ﬁlename

Output an OTU table in the mothur ’shared’ tab-separated plain text format as

described at http://www.mothur.org/wiki/Shared_ﬁle. The format describes howa

matrix containing the abundances of the OTUs in the different samples is stored. The

ﬁrst line will start with the strings ’label’, ’group’ and ’numOtus’ and is followed by a

list of all OTU identiﬁers. The following lines, one for each sample, starts with the

version 2.10.4 January 4, 2019 8

vsearch(1) USER COMMANDS vsearch(1)

string ’vsearch’ followed by the sample identiﬁer,the total number of OTUs, and a list

of abundances for each OTU in that sample, in the order givenonthe ﬁrst line. The

OTUand sample identiﬁers are extracted from the FASTAheaders of the sequences.

The OTUs are represented by the cluster centroids. See the --biomout option for further

details.

--otutabout ﬁlename

Output an OTU table in the classic tab-separated plain text format as a matrix contain-

ing the abundances of the OTUs in the different samples. The ﬁrst line will start with

the string ’#OTU ID’ and is followed by a tab-separated list of all sample identiﬁers.

The following lines, one for each OTU, starts with the OTU identiﬁer and is followed

by a tab-separated list of abundances for that OTU in each sample, in the order given

on the ﬁrst line. The OTU and sample identiﬁers are extracted from the FASTAheaders

of the sequences. The OTUs are represented by the cluster centroids. An extra column

is added to the right of the table if taxonomy information is available for at least one of

the OTUs. This column will be labelled ’taxonomy’ and each rowwill then contain the

taxonomy information extracted for that OTU. See the --biomout option for further

details.

--proﬁle ﬁlename

Output a sequence proﬁle to a text ﬁle with the frequencyofeach nucleotide in each

position in the multiple alignment for each cluster.There is a FASTA-likeheader line

for each cluster,followed by the proﬁle information in a tab-separated format. The

eight columns are: position (0-based), consensus nucleotide, number of As, number of

Cs, number of Gs, number of Ts or Us, number of gap symbols, and ﬁnally the total

number of ambiguous nucleotide symbols (B, D, H, K, M, N, R, S, Y,VorW). All

numbers are integers.

--qmask none|dust|soft

Mask regions in sequences using the dust or the soft methods, or do not mask (none).

Warning, when using soft masking, clustering becomes case sensitive.The default is to

mask using dust.

--relabel string

Relabel sequence identiﬁers in the output ﬁles produced by --consout, --proﬁle and

--centroids options. Please see the description of the same option under Chimera detec-

tion for details.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Relabel sequence identiﬁers in the output ﬁles produced by --consout, --proﬁle and

--centroids options. Please see the description of the same option under Chimera detec-

tion for details.

--relabel_sha1

Relabel sequence identiﬁers in the output ﬁles produced by --consout, --proﬁle and

--centroids options. Please see the description of the same option under Chimera detec-

tion for details.

--sizein Take into account the abundance annotations present in the input fasta ﬁle (search for

the pattern ’[>;]size=integer[;]’ in sequence headers).

--sizeorderWhen an amplicon is close to 2 or more centroids, both within the distance speciﬁed

with the --id option, resolvethe ambiguity by clustering it with the centroid having the

highest abundance, not necessarily the closest one. The option only has effect when the

value speciﬁed with --maxaccepts is higher than one. The --sizeorder option turns on

what is sometimes referred to as abundance-based greedy clustering (AGC), in contrast

version 2.10.4 January 4, 2019 9

vsearch(1) USER COMMANDS vsearch(1)

to the default distance-based greedy clustering (DGC).

--sizeout Add abundance annotations to the output fasta ﬁles (add the pattern speciﬁed, abun-

dance annotations are reported to output ﬁles, and each cluster centroid receivesa new

abundance value corresponding to the total abundance of the amplicons included in the

cluster (--centroids option). If --sizein is not speciﬁed, input abundances are set to 1 for

amplicons, and to the number of amplicons per cluster for centroids.

--strand plus|both

When comparing sequences with the cluster seed, check the plus strand only (default)

or check both strands.

--uc ﬁlename

Output clustering results in ﬁlename using a tab-separated uclust-likeformat with 10

columns and 3 different type of entries (S, H or C). Each fasta sequence in the input ﬁle

can be either a cluster centroid (S) or a hit (H) assigned to a cluster.Cluster records (C)

summarize information (size, centroid label) for each cluster.Inthe context of cluster-

ing, the option --uc_allhits has no effect on the --uc output. Column content varies with

the type of entry (S, H or C):

1. Record type: S, H, or C.

2. Cluster number (zero-based).

3. Centroid length (S), query length (H), or cluster size (C).

4. Percentage of similarity with the centroid sequence (H), or set to ’*’ (S,

C).

5. Match orientation + or - (H), or set to ’*’ (S, C).

6. Not used, always set to ’*’ (S, C) or to zero (H).

7. Not used, always set to ’*’ (S, C) or to zero (H).

8. set to ’*’ (S, C) or,for H, compact representation of the pairwise align-

ment using the CIGAR format (Compact Idiosyncratic Gapped Align-

ment Report): M (match), D (deletion) and I (insertion). The equal sign

’=’ indicates that the query is identical to the centroid sequence.

9. Label of the query sequence (H), or of the centroid sequence (S, C).

10. Label of the centroid sequence (H), or set to ’*’ (S, C).

--unoise_alpha real

Specify the alpha parameter to the --cluster_unoise command. The default i 2.0.

--usersort When using --cluster_smallmem, allowany sequence input order,not just a decreasing

length ordering.

--xsize Strip abundance information from the headers when writing the output ﬁle.

... Most searching options as well as score ﬁltering, gap penalties and masking also apply

to clustering (see the Searching section for deﬁnitions): --alnout, --blast6out,

--fastapairs, --matched, --notmatched, --maxaccept, --maxreject, --samout, --userout,

--userﬁelds

Dereplication and rereplication options:

--derep_fulllength ﬁlename

Merge strictly identical sequences contained in ﬁlename.Identical sequences are

deﬁned as having the same length and the same string of nucleotides (case insensitive,

Tand U are considered the same). See the options --sizein and --sizeout to takeinto

account and compute abundance values.

version 2.10.4 January 4, 2019 10

vsearch(1) USER COMMANDS vsearch(1)

--derep_preﬁx ﬁlename

Merge sequences with identical preﬁxes contained in ﬁlename.Ashort sequence iden-

tical to an initial segment (preﬁx) of another sequence is considered a replicate of the

longer sequence. If a sequence is identical to the preﬁx of twoormore longer

sequences, it is clustered with the shortest of them. If theyare equally long, it is clus-

tered with the most abundant. Remaining ties are solved using sequence headers and

sequence input order.Sequence comparisons are case insensitive,and T and U are con-

sidered identical.

--maxuniquesize positive integer

Discard sequences with a post-dereplication abundance value greater than integer.

--minuniquesize positive integer

Discard sequences with a post-dereplication abundance value smaller than integer.

--output ﬁlename

Write the dereplicated sequences to ﬁlename,infasta format and sorted by decreasing

abundance. Identical sequences receive the header of the ﬁrst sequence of their group.

If --sizeout is used, the number of occurrences (i.e. abundance) of each sequence is

indicated at the end of their fasta header using the pattern

--relabel string

Please see the description of the same option under Chimera detection for details.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Please see the description of the same option under Chimera detection for details.

--relabel_sha1

Please see the description of the same option under Chimera detection for details.

--rereplicate ﬁlename

Duplicate each sequence the number of times indicated by the abundance of each

sequence in the speciﬁed ﬁle (option --sizein is always implied). The sequence labels

are identical for the same sequence, unless --relabel, --relabel_sha1 or --relabel_md5 is

used to create unique labels. Output is written to the ﬁle speciﬁed with the --output

option, in FASTAformat. The output ﬁle does not contain abundance information

unless --sizeout is speciﬁed, in which case an abundance of 1 is used.

--sizein Take into account the abundance annotations present in the input fasta ﬁle (search for

the pattern ’[>;]size=integer[;]’ in sequence headers). That option is active bydefault

when rereplicating.

--sizeout Add abundance annotations to the output fasta ﬁle (add the pattern speciﬁed, each

unique sequence receivesanewabundance value corresponding to its total abundance

(sum of the abundances of its occurrences). If --sizein is not speciﬁed, input abun-

dances are set to 1, and each unique sequence receivesanew abundance value corre-

sponding to its number of occurrences in the input ﬁle.

--strand plus|both

When searching for strictly identical sequences, check the plus strand only (default) or

check both strands.

--topn positive integer

Output only the top integersequences (i.e. the most abundant).

--uc ﬁlename

Output full-length or preﬁx-dereplication results in ﬁlename using a tab-separated

uclust-likeformat with 10 columns and 3 different type of entries (S, H or C). Each

fasta sequence in the input ﬁle can be either a cluster centroid (S) or a hit (H) assigned

version 2.10.4 January 4, 2019 11

vsearch(1) USER COMMANDS vsearch(1)

to a cluster.Cluster records (C) summarize information (size, centroid label) for each

cluster.Inthe context of dereplication, the option --uc_allhits has no effect on the --uc

output. Column content varies with the type of entry (S, H or C):

1. Record type: S, H, or C.

2. Cluster number (zero-based).

3. Sequence length (S, H), or cluster size (C).

4. Percentage of similarity with the centroid sequence (H), or set to ’*’ (S,

C).

5. Match orientation + or - (H), or set to ’*’ (S, C).

6. Not used, always set to ’*’ (S, C) or 0 (H).

7. Not used, always set to ’*’ (S, C) or 0 (H).

8. Not used, always set to ’*’.

9. Label of the query sequence (H), or of the centroid sequence (S, C).

10. Label of the centroid sequence (H), or set to ’*’ (S, C).

--xsize Strip abundance information from the headers when writing the output ﬁle.

FASTA/FASTQ ﬁle processing options:

Analyse, shorten, ﬁlter,convert or merge sequences in FASTQ ﬁles, or reverse complement

sequences in FASTAorFASTQ ﬁles. The --fastq_chars command can be used to analyse FASTQ

ﬁles to identify the quality encoding and the range of quality score values used. Toconvert

between different FASTQ ﬁle variants, use the --fastq_convert command. Statistical analysis of the

quality and length of the sequences in a FASTQ ﬁle may be performed with the --fastq_stats,

--fastq_eestats, and --fastq_eestats2 commands. Sequences may be shortened, ﬁltered and con-

verted by the --fastq_ﬁlter or --fastx_ﬁlter commands. Paired-end reads can be merged using the

--fastq_mergepairs command. The --fastx_revcomp command reverse-complements sequences.

Finally,the --sff_convert command can be used to convert SFF ﬁles to FASTQ.

--eeout When using --fastq_ﬁlter or --fastq_mergepairs, include the number of expected errors

(ee) in the sequence header of FASTQ and FASTAﬁles. This option is a synonym of

the --fastq_eeout option.

--eetabbedout ﬁlename

When speciﬁed with the --fastq_mergepairs command, write statistics with expected

errors of each merged read to the givenﬁle. The ﬁle is a tab separated ﬁle with four

columns: The number of errors expected in the forward read, the number of expected

errors in the reverse read, the number of observed errors in the forward read, and the

number of observed errors in the reverse read. The observed number of errors are the

number of differences in the overlap region of the merged sequence relative toeach of

the reads in the pair.

--fastaout ﬁlename

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,write to the given

FASTA-formatted ﬁle the sequences passing the ﬁlter,orthe merged sequences.

--fastaout_notmerged_fwd ﬁlename

When using --fastq_mergepairs, write forward reads not merged to the speciﬁed

FASTAﬁle.

--fastaout_notmerged_rev ﬁlename

When using --fastq_mergepairs, write reverse reads not merged to the speciﬁed FASTA

ﬁle.

version 2.10.4 January 4, 2019 12

vsearch(1) USER COMMANDS vsearch(1)

--fastaout_discarded ﬁlename

Write sequences that do not pass the ﬁlter of the --fastq_ﬁlter or --fastx_ﬁlter command

to the givenFASTA-formatted ﬁle.

--fastq_allowmergestagger

When using --fastq_mergepairs, allowtomerge staggered read pairs. Staggered pairs

are pairs where the 3’ end of the reverse read has an overhang to the left of the 5’ end

of the forward read. This situation can occur when a very short fragment is sequenced.

The 3’ overhang of the reverse read is not included in the merged sequence. The oppo-

site option is the --fastq_nostagger option. The default is to discard staggered pairs.

--fastq_ascii positive integer

Deﬁne the ASCII character number used as the basis for the FASTQ quality score. The

default is 33, which is used by the Sanger / Illumina 1.8+ FASTQ format (phred+33).

The value 64 is used by the Solexa, Illumina 1.3+ and Illumina 1.5+ formats

(phred+64).

--fastq_asciiout positive integer

When using --fastq_convert or --sff_convert, deﬁne the ASCII character number used

as the basis for the FASTQ quality score when writing FASTQ output ﬁles. The default

is 33.

--fastq_chars ﬁlename

Summarize the composition of sequence and quality strings contained in the input

FASTQ ﬁle. For each of the four DNAletters, --fastq_chars givesthe number of occur-

rences of the letter,its relative frequencyand the length of the longest run of that letter.

Foreach character present in the quality strings, --fastq_chars givesthe ASCII value of

the character,its relative frequency, and the number of times a k-mer of that character

appears at the end of quality strings. The length of the k-mer can be set using

--fastq_tail (4 by default). The command --fastq_chars tries to automatically detect the

quality encoding (Solexa, Illumina 1.3+, Illumina 1.5+ or Illumina 1.8+/Sanger) by

analyzing the range of observed quality score values. In case of success, --fastq_chars

suggests values for the --fastq_ascii (33 or 64), --fastq_qmin and --fastq_qmax options

to be used with the other commands that require a FASTQ input ﬁle.

--fastq_convert ﬁlename

Convert between the different variants of the FASTQ ﬁle format. The quality encoding

of the input ﬁle must be speciﬁed with the --fastq_ascii option (either 33 or 64, the

default is 33), and the output quality encoding must be speciﬁed with the --fastq_asci-

iout option (default 33). The minimum and maximum output quality scores may be

limited using the --fastq_qminout and --fastq_qmaxout options. The output ﬁle is speci-

ﬁed with the --fastqout option.

--fastq_eeout

When using --fastq_ﬁlter or --fastq_mergepairs, include the number of expected errors

(ee) in the sequence header of FASTQ and FASTAﬁles. This option is a synonym of

the --eeout option.

--fastq_eestats ﬁlename

Analyze a FASTQ ﬁle and report statistics on the distributions of quality scores, error

probabilities and expected accumulated errors. The report, a table of 21 tab-separated

columns, is written to the ﬁle speciﬁed with the --output option. The ﬁrst column corre-

sponds to the position in the reads (Pos). The second and third columns correspond to

the number of reads (Reads) and percentage of reads (PctRecs) that include this posi-

tion. The remaining columns include information about the distribution of quality

scores in this position (Q), error probabilities in this position (Pe), and ﬁnally the

expected number of accumulated errors from the beginning of the reads and until the

current position (EE). For each of the Q, Pe and EE distributions, the following statis-

tics are included: minimum value (Min), lower quartile (Low), median (Med), mean

version 2.10.4 January 4, 2019 13

vsearch(1) USER COMMANDS vsearch(1)

(Mean), upper quartile (Hi), and maximum value (Max). The quality encoding and the

range of quality values may be speciﬁed with --fastq_ascii --fastq_qmin and

--fastq_qmax.

--fastq_eestats2 ﬁlename

Analyze the speciﬁed FASTQ ﬁle and report statistics on the number of sequences that

would be retained at a combination of selected cutoffs for length truncation and maxi-

mum expected errors, that could potentially be used as arguments to the --fastq_trun-

clen and --fastq_maxee options to the --fastq_ﬁlter command. The result, a table of

twoormore columns, is written to the ﬁle speciﬁed with the --output option. There is a

line for each length truncation cutoff. The ﬁrst column on each line contains the

selected truncation length, while the following columns contain the number of

sequences and, in parenthesis, the percentage of sequences that would be retained at the

selected EE levels. The truncation length cutoffs may be speciﬁed with the

--length_cutoffs option and requires a list of three comma-separated integers indicating

the shortest cutoff, the longest cutoff, and the increment between cutoffs. The longest

cutoffmay be speciﬁed with a star (*) which indicates that the limit is equal to the

longest sequence in the input ﬁle. The default setting is "50,*,50" meaning that trunca-

tion lengths of 50, 100, 150 and so on up to the longest sequence length should be

used. The maximum expected error (EE) cutoffs may be speciﬁed with the --ee_cutoffs

option which requires a comma-separated list of ﬂoating point numbers as its argu-

ment. The default setting is "0.5,1.0,2.0" that indicates that expected error levels of 0.5,

1.0 and 2.0 should be used.

--fastq_ﬁlter ﬁlename

Shorten and/or ﬁlter sequences in the givenFASTQ ﬁle. Similar to the --fastx_ﬁlter

command, but works only on FASTQ ﬁles. See --fastx_ﬁlter for details.

--fastq_join ﬁlename

Join paired-end sequence reads into one sequence and add a gap between them using a

padding sequence. The sequences are not merged as with the fastq_mergepairs com-

mand, but simply joined with a gap. The forward reads are speciﬁed as the argument to

this option and the reverse reads are speciﬁed with the --reverse option. The resulting

sequences consist of the forward read, the padding sequence and the reverse comple-

ment of the reverse read. The padding sequence is speciﬁed with the --join_padgap

option and the padding quality is speciﬁed with the --join_padgapq option. The default

padding sequence string is NNNNNNNN and the default padding quality string is IIIII-

III, corresponding to a base quality score of 40 (a very high quality score with error

probability 0.0001). The joined sequences are output to the ﬁle(s) speciﬁed with the

--fastaout or --fastqout options.

--fastq_maxdiffs positive integer

When using --fastq_mergepairs, specify the maximum number of non-matching

nucleotides allowed in the overlap region. That option has a strong inﬂuence on the

merging success rate. The default value is 10.

--fastq_maxdiffpct real

When using --fastq_mergepairs, specify the maximum percentage of non-matching

nucleotides allowed in the overlap region. The default value is 100.0%. There are other

more sophisticated rules in the merging algorithm that will discard read pairs with a

high fraction of mismatches.

--fastq_maxee real

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,discard sequences with

more than the speciﬁed number of expected errors.

--fastq_maxee_rate real

When using --fastq_ﬁlter or --fastx_ﬁlter,discard sequences with more than the speci-

ﬁed number of expected errors per base.

version 2.10.4 January 4, 2019 14

vsearch(1) USER COMMANDS vsearch(1)

--fastq_maxlen positive integer

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,discard sequences with

more than the speciﬁed number of bases.

--fastq_maxmergelen positive integer

When using --fastq_mergepairs, specify the maximum length of the merged sequence.

By default there is no limit.

--fastq_maxns positive integer

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,discard sequences with

more than the speciﬁed number of N’s.

--fastq_mergepairs ﬁlename

Merge paired-end sequence reads into one sequence. The forward reads are speciﬁed as

the argument to this option and the reverse reads are speciﬁed with the --reverse option.

The merged sequences are output to the ﬁle(s) speciﬁed with the --fastaout or --fastqout

options. The non-merged reads can be output to the ﬁles speciﬁed with the --fas-

taout_notmerged_fwd, --fastaout_notmerged_rev, --fastqout_notmerged_fwd and

--fastqout_notmerged_revoptions. Statistics may be output to the ﬁle speciﬁed with the

--eetabbedout option. Sequences are truncated as speciﬁed with the --fastq_truncqual

option to remove low-quality bases in the 3’ end. Sequences shorter than speciﬁed with

--fastq_minlen (after truncation) are discarded (1 by default). Sequences with too many

ambiguous bases (N’s), as speciﬁed with the --fastq_maxns are also discarded (no limit

by default). Staggered reads are not merged unless the --fastq_allowmergestagger

option is speciﬁed. The minimum length of the overlap region between the reads may

be speciﬁed with the --fastq_minovlen option (default 10). The overlap region may not

include more mismatches than speciﬁed with the --fastq_maxdiffs option (10 by

default) or a higher percentage of mismatches than speciﬁed with the --fastq_maxdiff-

pct option (100.0% by default), otherwise the read pair is discarded. Additional rules

will avoid merging of reads that cannot be aligned reliably and unambiguously.The

mimimum and maximum length of the merged sequence may be speciﬁed with the

--fastq_minmergelen and --fastq_maxmergelen options, respectively.Other relevant

options are: --fastq_ascii, --fastq_maxee, --fastq_nostagger,--fastq_qmax,

--fastq_qmaxout, --fastq_qmin, --fastq_qminout, and --label_sufﬁx.

--fastq_minlen positive integer

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,discard sequences with

less than the speciﬁed number of bases (default 1).

--fastq_minmergelen positive integer

When using --fastq_mergepairs, specify the minimum length of the merged sequence.

The default is 1.

--fastq_minovlen positive integer

When using --fastq_mergepairs, specify the minimum overlap between the merged

reads. The default is 10.

--fastq_nostagger

When using --fastq_mergepairs, forbid the merging of staggered read pairs. This is the

default behaviour of --fastq_mergepairs. Tochange that behaviour,see the

--fastq_allowmergestagger option.

--fastq_qmax positive integer

Specify the maximum quality score accepted when reading FASTQ ﬁles. The default is

41, which is usual for recent Sanger/Illumina 1.8+ ﬁles.

--fastq_qmaxout positive integer

When using --fastq_convert or --sff_convert, specify the maximum quality score used

when writing FASTQ ﬁles. The default is 41, which is usual for recent Sanger/Illumina

1.8+ ﬁles. Older formats may use a maximum quality score of 40.

version 2.10.4 January 4, 2019 15

vsearch(1) USER COMMANDS vsearch(1)

--fastq_qmin positive integer

Specify the minimum quality score accepted for FASTQ ﬁles. The default is 0, which is

usual for recent Sanger/Illumina 1.8+ ﬁles. Older formats may use scores between -5

and 2.

--fastq_qminout positive integer

When using --fastq_convert or --sff_convert, specify the minimum quality score used

when writing FASTQ ﬁles. The default is 0, which is usual for Sanger/Illumina 1.8+

ﬁles. Older versions of the format may use scores between -5 and 2.

--fastq_stats ﬁlename

Analyze a FASTQ ﬁle and report the number of reads it contains. The quality encoding

and the range of quality values may be speciﬁed with --fastq_ascii --fastq_qmin and

--fastq_qmax. That command requires the --log option and outputs the following

detailed statistics on read length, quality score, length vs. quality distributions, and

length / quality ﬁltering:

Read length distribution:

1. L: read length.

2. N: number of reads.

3. Pct: fraction of reads with this length.

4: AccPct: fraction of reads with this length or longer.

Quality score distribution:

1. ASCII: character encoding the quality score.

2. Q: Phred quality score.

3. Pe: probability of error associated with the quality score.

4. N: number of bases with this quality score.

5. Pct: fraction of bases with this quality score.

6: AccPct: fraction of bases with this quality score or higher.

Length vs. quality distribution:

1. L: position in reads (starting from position 2).

2. PctRecs: fraction of reads with at least this length.

3. AvgQ: average quality score overall reads up to this position.

4. P(AvgQ): error probability corresponding to AvgQ.

5. AvgP: average error probability.

6: AvgEE: average expected error overall reads up to this position.

7: Rate: growth rate of AvgEE between this position and position - 1.

8: RatePct: Rate (as explained above)expressed as a percentage.

Effect of expected error and length ﬁltering:

The ﬁrst column indicates read lengths (L). The next four columns indicate the

number of reads that would be retained by the --fastq_ﬁlter command if the

reads were truncated at length L(option --fastq_trunclen L)and ﬁltered to

have a maximum expected error of 1.0, 0.5, 0.25 or 0.1 (with the option

--fastq_maxee ﬂoat). The last four columns indicate the fraction of reads that

would be retained by the --fastq_ﬁlter command using the same length and

maximum expected error parameters.

version 2.10.4 January 4, 2019 16

vsearch(1) USER COMMANDS vsearch(1)

Effect of minimum quality and length ﬁltering:

The ﬁrst column indicates read lengths (Len). The next four columns indicate

the fraction of reads that would be retained by the --fastq_ﬁlter command if

the reads were truncated at length Len (option --fastq_trunclen Len)oratthe

ﬁrst position with a quality Qbelow5,10, 15 or 20 (option --fastq_truncqual

Q).

--fastq_stripleft positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,strip the speciﬁed number of bases from the

left end of the reads.

--fastq_stripright positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,strip the speciﬁed number of bases from the

right end of the reads.

--fastq_tail positive integer

When using --fastq_chars, count the number of times a series of characters of length k

appears at the end of quality strings. By default, k=4.

--fastq_truncee real

When using --fastq_ﬁlter or --fastx_ﬁlter,truncate sequences so that their total

expected error is not higher than the speciﬁed value.

--fastq_trunclen positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,truncate sequences to the speciﬁed length.

Shorter sequences are discarded.

--fastq_trunclen_keep positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,truncate sequences to the speciﬁed length.

Shorter sequences are not discarded.

--fastq_truncqual positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,truncate sequences starting from the ﬁrst base

with the speciﬁed base quality score value or lower.

--fastqout ﬁlename

When using --fastq_ﬁlter,--fastq_mergepairs or --fastx_ﬁlter,write to the given

FASTQ-formatted ﬁle the sequences passing the ﬁlter,orthe merged sequences.

--fastqout_discarded ﬁlename

When using --fastq_ﬁlter or --fastx_ﬁlter,write sequences that do not pass the ﬁlter to

the givenFASTQ-formatted ﬁle.

--fastqout_notmerged_fwd ﬁlename

When using --fastq_mergepairs, write forward reads not merged to the speciﬁed

FASTQ ﬁle.

--fastqout_notmerged_rev ﬁlename

When using --fastq_mergepairs, write reverse reads not merged to the speciﬁed FASTQ

ﬁle.

--fastx_ﬁlter ﬁlename

Shorten and/or ﬁlter the sequences in the givenFASTAorFASTQ ﬁle and output the

remaining sequences to the FASTQ ﬁle speciﬁed with the --fastqout option and to the

FASTAﬁle speciﬁed with the --fastaout option. The discarded sequences are written to

the ﬁles speciﬁed with the --fastaout_discarded and --fastqout_discarded options. The

input format (FASTAorFASTQ) is automatically detected. Output can not be written

to FASTQ ﬁles if the input is in FASTAformat. Sequences may be shortened using the

options --fastq_stripleft, --fastq_stripright, --fastq_truncee, --fastq_trunclen,

--fastq_trunclen_keep and --fastq_truncqual. The sequences may be ﬁltered using the

options --fastq_maxee, --fastq_maxee_rate, --fastq_maxlen, --fastq_maxns,

--fastq_minlen, --fastq_trunclen, --maxsize, and --minsize. If shortening results in an

version 2.10.4 January 4, 2019 17

vsearch(1) USER COMMANDS vsearch(1)

empty sequence, it is discarded. The sequences are ﬁrst shortened and then ﬁltered

based on the remaining bases. If no shortening or ﬁltering options are given, all

sequences are written to the output ﬁles, possibly after conversion from FASTQ to

FASTAformat. The --relabel option may be used to relabel the output sequences. The

--eeout may be used to output the expected number of errors in each sequence.

--fastx_revcomp ﬁlename

Reverse-complement the sequences in the givenFASTAorFASTQ ﬁle to a ﬁle speci-

ﬁed with the --fastaout and/or --fastqout options. If the input ﬁle is in FASTAformat,

the output can not be written back to a FASTQ ﬁle due to missing base quality scores.

--join_padgap string

When running --fastq_join, use the string as a sequence padding string. The default is

NNNNNNNN (8 N’s).

--join_padgapq string

When running --fastq_join, use the string as a quality padding string. The default is a

string of I’sequal in length to the sequence padding string. The letter I corresponds to a

base quality score of 40 indicating a very high quality base with error probability of

0.0001.

--label_sufﬁx string

When using --fastx_revcomp or --fastq_mergepairs, add the sufﬁx string to sequence

headers.

--maxsize positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,discard sequences with an abundance higher

than the speciﬁed value.

--minsize positive integer

When using --fastq_ﬁlter or --fastx_ﬁlter,discard sequences with an abundance lower

than the speciﬁed value.

--output ﬁlename

When using --fastq_eestats or --fastq_eestats2, write tabulated results to ﬁlename.See

--fastq_eestats’sand --fastq_eestats2’sdocumentation for a complete description of the

table.

--relabel_keep

When using --relabel, keep the old identiﬁer in the header after a space.

--relabel string

Please see the description of the same option under Chimera detection for details.

--relabel_md5

Please see the description of the same option under Chimera detection for details.

--relabel_sha1

Please see the description of the same option under Chimera detection for details.

--rev erse ﬁlename

When using --fastq_mergepairs or --fastq_join, specify the FASTQ ﬁle containing con-

taining the reverse reads.

--sff_convert ﬁlename

Convert the givenSFF ﬁle to FASTQ. The FASTQ output ﬁle is speciﬁed with the

--fastqout option. The sequence may be clipped as speciﬁed in the SFF ﬁle if the option

--sff_clip is speciﬁed, otherwise no clipping occurs. Bases that would have been

clipped are converted to lower case, while the rest is in upper case. The output quality

encoding may be speciﬁed with the --fastq_asciiout option (default 33). The minimum

and maximum output quality scores may be limited using the --fastq_qminout and

--fastq_qmaxout options.

version 2.10.4 January 4, 2019 18

vsearch(1) USER COMMANDS vsearch(1)

--sff_clip Speciﬁes that the sequences converted by the --sff_convert command should be clipped

in both ends as indicated in the SFF ﬁle. By default no clipping is performed.

--xsize Strip abundance information from the headers when writing the output ﬁle.

Masking options:

An input sequence can be composed of lower-oruppercase letters. When soft masking is speci-

ﬁed, lower case letters are treated as symbols that should be masked. Otherwise the case of the

input sequences is ignored.

Masking is performed by the commands for chimera detection (uchime_denovo,uchime_ref),

clustering (cluster_fast, cluster_smallmem, cluster_size), masking (maskfasta, fastx_mask), pair-

wise alignment (allpairs_global) and searching (search_exact, usearch_global).

Masking is usually speciﬁed with the --qmask option, while the --dbmask option is used for the

database sequences speciﬁed with the --db option with the --usearch_global, --search_exact and

--uchime_ref commands.

The argument to the --qmask and --dbmask option may be none, soft or dust. If the argument is

none, the no masking is performed. If the argument is soft the lower case symbols are masked.

Finally,ifthe argument is dust, the sequence is masked using the DUST algorithm by Tatusovand

Lipman to mask low-complexity regions.

If the --hardmask option is speciﬁed, all masked regions are converted to N’s, otherwise masked

regions are indicated by lower case letters.

If anysequence is masked, the masked version of the sequence (with lower case letters or N’s) is

used in all output ﬁles. Otherwise the sequence is unmodiﬁed. The exception is the sequences in

the output ﬁle speciﬁed with the --uchimealns option, where the input sequences are converted to

upper case ﬁrst and lower case letters indicate disagreement between the aligned sequences.

When a sequence region is masked, words in the region are not included in the indices used in the

heuristic search algorithm. In all other aspects, the region is treated as other regions.

Regions in sequences that are hardmasked (with N’s) have a zero alignment score and do not con-

tribute to an alignment.

Here are the results of combined masking options --qmask (or --dbmask for database sequences)

and --hardmask, assuming each input sequence contains both lower and uppercase nucleotides:

qmask hardmask action

none offnomasking, all symbols used, no change

none on no masking, all symbols used, no change

dust offmasked symbols lowercased, rest uppercased

dust on masked symbols changed to Ns, rest unchanged

soft offlowercase symbols masked, no case changes

soft on lowercase symbols masked and changed to Ns

--fastaout ﬁlename

Write the masked sequences to ﬁlename,infasta format. Applies only to the

--fastx_mask command.

--fastqout ﬁlename

Write the masked sequences to ﬁlename,infastq format. Applies only to the

--fastx_mask command.

--fastx_mask ﬁlename

Mask regions in sequences contained in the speciﬁed fasta or fastq ﬁle. The default is

to mask using DUST (use --qmask to modify that behavior). The output ﬁles are speci-

ﬁed with the --fastaout and --fastqout options. The minimum and maximum percentage

of unmasked residues may be speciﬁed with the --min_unmasked_pct and

--max_unmasked_pct options, respectively.

--hardmask

Symbols in masked regions are replaced by N’s. The default is to replace the masked

regions by lower case letters.

version 2.10.4 January 4, 2019 19

vsearch(1) USER COMMANDS vsearch(1)

--maskfasta ﬁlename

Mask regions in sequences contained in the fasta ﬁle ﬁlename.The default is to mask

using dust (use --qmask to modify that behavior). The output ﬁle is speciﬁed with the

--output option. This command is depreciated, please use --fastx_mask instead.

--max_unmasked_pct real

Discard sequences with more than the speciﬁed maximum percentage of unmasked

residues. Works only with --fastx_mask.

--min_unmasked_pct real

Discard sequences with less than the speciﬁed minimum percentage of unmasked

residues. Works only with --fastx_mask.

--output ﬁlename

Write the masked sequences to ﬁlename,infasta format. Applies only to the

--mask_fasta command.

--qmask none|dust|soft

If the argument is dust, mask regions in sequences using the DUST algorithm that

detects simple repeats and low-complexity regions. This is the default. If the argument

is soft, mask the lower case letters in the input sequence. If the argument is none, do

not mask.

Pairwise alignment options:

The results of the n * (n - 1) / 2 pairwise alignments are written to the result ﬁles speciﬁed with

--alnout, --blast6out, --fastapairs --matched, --notmatched, --samout, --uc or --userout (see Search-

ing section below). Specify either the --acceptall option to output all pairwise alignments, or spec-

ify an identity levelwith --id to discard weak alignments. Most other accept/reject options (see

Searching options below) may also be used. Sequences are aligned on their plus strand only.

Masking is performed as usual and speciﬁed with --qmask and --hardmask.

--acceptallWrite the results of all alignments to output ﬁles. This option overrides all other

accept/reject options (including --id).

--allpairs_global ﬁlename

Perform optimal global pairwise alignments of all vs. all fasta sequences contained in

ﬁlename.This command is multi-threaded.

--id real Reject the sequence match if the pairwise identity is lower than real (value ranging

from 0.0 to 1.0 included).

--threads positive integer

Number of computation threads to use (1 to 256). The number of threads should be

lesser or equal to the number of available CPU cores. The default is to use all available

resources and to launch one thread per logical core.

--uc ﬁlename

Output pairwise alignment results in ﬁlename using a tab-separated uclust-likeformat

with 10 columns. Each sequence is compared to all other sequences, and all hits

(--acceptall) or only some hits (--id ﬂoat)are reported, with one pairwise comparison

per line:

1. Record type, always set to ’H’.

2. Ordinal number of the target sequence (based on input order,starting

from zero).

3. Sequence length.

4. Percentage of similarity with the target sequence.

version 2.10.4 January 4, 2019 20

vsearch(1) USER COMMANDS vsearch(1)

5. Match orientation, always set to ’+’.

6. Not used, always set to zero.

7. Not used, always set to zero.

8. Compact representation of the pairwise alignment using the CIGAR for-

mat (Compact Idiosyncratic Gapped Alignment Report): M (match), D

(deletion) and I (insertion). The equal sign ’=’ indicates that the query is

identical to the centroid sequence.

9. Label of the query sequence.

10. Label of the target sequence.

Searching options:

--alnout ﬁlename

Write pairwise global alignments to ﬁlename using a human-readable format. Use

--rowlen to modify alignment length. Output order may vary when using multiple

threads.

--biomout ﬁlename

Write search results to an OTU table in the biom version 1.0 ﬁle format. The query ﬁle

contains the samples, while the database ﬁle contains the OTUs. Sample and OTU

identiﬁers are extracted from the header of these sequences. See the --biomout option

in the Clustering section for further details.

--blast6out ﬁlename

Write search results to ﬁlename using a blast-liketab-separated format of twelveﬁelds

(listed below), with one line per query-target matching (or lack of matching if --out-

put_no_hits is used). Warning, vsearch uses global pairwise alignments, not blast’s

seed-and-extend algorithm. Therefore, some common blast output values (alignment

start and end, evalue, bit score) are reported differently.Output order may vary when

using multiple threads. A similar output can be obtain with --userout ﬁlename and

--userﬁelds query+target+id+alnlen+mism+opens+qlo+qhi+tlo+thi+evalue+bits. A

complete list and description is available in the section ’Userﬁelds’ of this manual.

1. query:query label.

2. target:target (database sequence) label. The ﬁeld is set to ’*’ if there is

no alignment.

3. id:percentage of identity (real value ranging from 0.0 to 100.0). The per-

centage identity is deﬁned as 100 * (matching columns) / (alignment

length - terminal gaps). See ﬁelds id0 to id4 for other deﬁnitions.

4. alnlen:length of the query-target alignment (number of columns). The

ﬁeld is set to 0 if there is no alignment.

5. mism:number of mismatches in the alignment (zero or positive integer

value).

6. opens:number of columns containing a gap opening (zero or positive

integer value).

7. qlo:ﬁrst nucleotide of the query aligned with the target. Always equal to

1ifthere is an alignment, 0 otherwise (see qilo to ignore initial gaps).

8. qhi:last nucleotide of the query aligned with the target. Always equal to

the length of the pairwise alignment, 0 otherwise (see qihi to ignore ter-

minal gaps).

9. tlo:ﬁrst nucleotide of the target aligned with the query.Always equal to

1ifthere is an alignment, 0 otherwise (see tilo to ignore initial gaps).

version 2.10.4 January 4, 2019 21

vsearch(1) USER COMMANDS vsearch(1)

10. thi:last nucleotide of the target aligned with the query.Always equal to

the length of the pairwise alignment, 0 otherwise (see tihi to ignore ter-

minal gaps).

11. evalue:expectancy-value (not computed for nucleotide alignments).

Always set to -1.

12. bits:bit score (not computed for nucleotide alignments). Always set to 0.

--db ﬁlename

Compare query sequences (speciﬁed with --usearch_global) to the fasta-formatted tar-

get sequences contained in ﬁlename,using global pairwise alignment. Alternatively,the

name of a preformatted UDB database created using the makeudb_usearch command

(see below) may be speciﬁed.

--dbmask none|dust|soft

Mask regions in the target database sequences using the dust method or the soft

method, or do not mask (none). Warning, when using soft masking search commands

become case sensitive.The default is to mask using dust.

--dbmatched ﬁlename

Write database target sequences matching at least one query sequence to ﬁlename,in

fasta format. If the option --sizeout is used, the number of queries that matched each

target sequence is indicated using the pattern ";size=integer;".

--dbnotmatched ﬁlename

Write database target sequences not matching query sequences to ﬁlename,infasta for-

mat.

--fastapairs ﬁlename

Write pairwise alignments of query and target sequences to ﬁlename,infasta format.

--fulldp Dummy option for compatibility with usearch. Tomaximize search sensitivity, vsearch

uses a 8-way 16-bit SIMD vectorized full dynamic programming algorithm (Needle-

man-Wunsch), whether or not --fulldp is speciﬁed.

--gapext string

Set penalties for a gap extension. See --gapopen for a complete description of the

penalty declaration system. The default is to initialize the six gap extending penalties

using a penalty of 2 for extending internal gaps and a penalty of 1 for extending termi-

nal gaps, in both query and target sequences (i.e. 2I/1E).

--gapopen string

Set penalties for a gap opening. A gap opening can occur in six different contexts: in

the query (Q) or in the target (T) sequence, at the left (L) or right (R) extremity of the

sequence, or inside the sequence (I). Sequence symbols (Q and T) can be combined

with location symbols (L, I, and R), and numerical values to declare penalties for all

possible contexts: aQL/bQI/cQR/dTL/eTI/fTR, where abcdef are zero or positive inte-

gers, and ’/’ is used as a separator.

To simplify declarations, the location symbols (L, I, and R) can be combined, the sym-

bol (E) can be used to treat both extremities (L and R) equally,and the symbols Q and

Tcan be omitted to treat query and target sequences equally.For instance, the default is

to declare a penalty of 20 for opening internal gaps and a penalty of 2 for opening ter-

minal gaps (left or right), in both query and target sequences (i.e. 20I/2E). If only a

numerical value is given, without anysequence or location symbol, then the penalty

applies to all gap openings. Toforbid gap-opening, an inﬁnite penalty value can be

declared with the symbol ’*’. Touse vsearch as a semi-global aligner,anull-penalty

can be applied to the left (L) or right (R) gaps.

vsearch always initializes the six gap opening penalties using the default parameters

(20I/2E). The user is then free to declare only the values he/she wants to modify.The

version 2.10.4 January 4, 2019 22

vsearch(1) USER COMMANDS vsearch(1)

string is scanned from left to right, accepted symbols are (0123456789/LIREQT*), and

later values override previous values.

Please note that vsearch,incontrast to usearch, only allows integer gap penalties.

Because the lowest gap penalties are 0.5 by default in usearch, all default scores and

gappenalties in vsearch have been doubled to maintain equivalent penalties and to pro-

duce identical alignments.

--hardmask

Mask sequence regions by replacing them with Ns instead of setting them to lower case

as is the default. For more information, please see the Masking section.

--id real Reject the sequence match if the pairwise identity is lower than real (value ranging

from 0.0 to 1.0 included). The search process sorts target sequences by decreasing

number of k-mers theyhav e in common with the query sequence, using that informa-

tion as a proxy for sequence similarity.That efﬁcient pre-ﬁltering also prevents pair-

wise alignments with weakly matching targets, as there needs to be at least 6 shared k-

mers to start the pairwise alignment, and at least one out of every 16 k-mers from the

query needs to match the target. Consequently,using values lower than --id 0.5 is not

likely to capture more weakly matching targets. The pairwise identity is by default

deﬁned as the number of (matching columns) / (alignment length - terminal gaps). That

deﬁnition can be modiﬁed by --iddef.

--iddef 0|1|2|3|4

Change the pairwise identity deﬁnition used in --id. Values accepted are:

0. CD-HIT deﬁnition: (matching columns) / (shortest sequence length).

1. edit distance: (matching columns) / (alignment length).

2. edit distance excluding terminal gaps (default deﬁnition for --id).

3. Marine Biological Lab deﬁnition counting each gap opening (internal or

terminal) as a single mismatch, whether or not the gap was extended: 1.0

-[(mismatches + gap openings)/(longest sequence length)]

4. BLAST deﬁnition, equivalent to --iddef 1 for global pairwise alignments.

The option --userﬁelds accepts the ﬁelds id0 to id4, in addition to the ﬁeld id, to report

the pairwise identity values corresponding to the different deﬁnitions.

--idpreﬁx positive integer

Reject the sequence match if the ﬁrst integernucleotides of the target do not match the

query.

--idsufﬁx positive integer

Reject the sequence match if the last integernucleotides of the target do not match the

query.

--leftjust Reject the sequence match if the pairwise alignment begins with gaps.

--match integer

Score assigned to a match (i.e. identical nucleotides) in the pairwise alignment. The

default value is 2.

--matched ﬁlename

Write query sequences matching database target sequences to ﬁlename,infasta format.

--maxaccepts positive integer

Maximum number of hits to accept before stopping the search. The default value is 1.

This option works in pair with --maxrejects. The search process sorts target sequences

by decreasing number of k-mers theyhav e in common with the query sequence, using

that information as a proxy for sequence similarity.After pairwise alignments, if the

ﬁrst target sequence passes the acceptation criteria, it is accepted as best hit and the

version 2.10.4 January 4, 2019 23

vsearch(1) USER COMMANDS vsearch(1)

search process stops for that query.If--maxaccepts is set to a higher value, more hits

are accepted. If --maxaccepts and --maxrejects are both set to 0, the complete database

is searched.

--maxdiffs positive integer

Reject the sequence match if the alignment contains at least integersubstitutions, inser-

tions or deletions.

--maxgaps positive integer

Reject the sequence match if the alignment contains at least integerinsertions or dele-

tions.

--maxhits positive integer

Maximum number of hits to showonce the search is terminated (hits are sorted by

decreasing identity). Unlimited by default. That option applies to --alnout, --blast6out,

--fastapairs, --samout, --uc, or --userout output ﬁles.

--maxid real

Reject the sequence match if the percentage of identity between the twosequences is

greater than real.

--maxqsize positive integer

Reject query sequences with an abundance greater than integer.

--maxqt real

Reject if the query/target sequence length ratio is greater than real.

--maxrejects positive integer

Maximum number of non-matching target sequences to consider before stopping the

search. The default value is 32. This option works in pair with --maxaccepts. The

search process sorts target sequences by decreasing number of k-mers theyhav e in

common with the query sequence, using that information as a proxy for sequence simi-

larity.After pairwise alignments, if none of the ﬁrst 32 examined target sequences pass

the acceptation criteria, the search process stops for that query (no hit). If --maxrejects

is set to a higher value, more target sequences are considered. If --maxaccepts and

--maxrejects are both set to 0, the complete database is searched.

--maxsizeratio real

Reject if the query/target abundance ratio is greater than real.

--maxsl real

Reject if the shorter/longer sequence length ratio is greater than real.

--maxsubs positive integer

Reject the sequence match if the pairwise alignment contains more than integersubsti-

tutions.

--mid real

Reject the sequence match if the percentage of identity is lower than real (ignoring all

gaps, internal and terminal).

--mincols positive integer

Reject the sequence match if the alignment length is shorter than integer.

--minqt real

Reject if the query/target sequence length ratio is lower than real.

--minsizeratio real

Reject if the query/target abundance ratio is lower than real.

--minsl real

Reject if the shorter/longer sequence length ratio is lower than real.

version 2.10.4 January 4, 2019 24

vsearch(1) USER COMMANDS vsearch(1)

--mintsize positive integer

Reject target sequences with an abundance lower than integer.

--minwordmatches non-negative integer

Minimum number of word matches required for a sequence to be considered further.

Default value is 12 for the default word length 8. For word lengths 3-15, the default

minimum word matches are 18, 17, 16, 15, 14, 12, 11, 10, 9, 8, 7, 5 and 3, respectively.

If the query sequence has fewer unique words than the number speciﬁed, all words in

the query must match. If the argument is 0, no word matches are required.

--mismatch integer

Score assigned to a mismatch (i.e. different nucleotides) in the pairwise alignment. The

default value is -4.

--mothur_shared_out ﬁlename

Write search results to an OTU table in the mothur ’shared’ tab-separated plain text ﬁle

format. The query ﬁle contains the samples, while the database ﬁle contains the OTUs.

Sample and OTU identiﬁers are extracted from the header of these sequences. See the

--otutabout option in the Clustering section for further details.

--notmatched ﬁlename

Write query sequences not matching database target sequences to ﬁlename,infasta for-

mat.

--otutabout ﬁlename

Write search results to an OTU table in the classic tab-separated plain text format. The

query ﬁle contains the samples, while the database ﬁle contains the OTUs. Sample and

OTUidentiﬁers are extracted from the header of these sequences. See the

--mothur_shared_out option in the Clustering section for further details.

--output_no_hits

Write both matching and non-matching queries to --alnout, --blast6out, --samout or

--userout output ﬁles. Non-matching queries are labelled ’No hits’ in --alnout ﬁles.

--pattern string

This option is ignored. It is provided for compatibility with usearch.

--qmask none|dust|soft

Mask regions in the query sequences using the dust or the soft algorithms, or do not

mask (none). Warning, when using soft masking search commands become case sensi-

tive.The default is to mask using dust.

--query_cov real

Reject if the fraction of the query aligned to the target sequence is lower than real.The

query coverage is computed as (matches + mismatches) / query sequence length. Inter-

nal or terminal gaps are not taken into account.

--rightjustReject the sequence match if the pairwise alignment ends with gaps.

--rowlen positive integer

Width of alignment lines in --alnout output. The default value is 64. Set to 0 to elimi-

nate wrapping.

--samheader

Include header lines to the SAM ﬁle when --samout is speciﬁed. The header includes

lines starting with @HD, @SQ and @PG, but no @RG lines (see

<https://github.com/samtools/hts-specs>). By default no header line is written.

--samout ﬁlename

Write alignment results to ﬁlename using the SAM format (a tab-separated text ﬁle).

When using the --samheader option, the SAM ﬁle starts with header lines. Each non-

version 2.10.4 January 4, 2019 25

vsearch(1) USER COMMANDS vsearch(1)

header line is a SAM record, which represents either a query-target alignment or the

absence of match for a query (output order may vary when using multiple threads).

Each record contains 11 mandatory ﬁelds and optional ﬁelds (see

<https://github.com/samtools/hts-specs> for a complete description of the format):

1. query sequence label.

2. combination of bitwise ﬂags. Possible values are: 0 (top hit), 4 (no hit),

16 (reverse-complemented hit), 256 (secondary hit, i.e. all hits except the

top hit).

3. target sequence label.

4. ﬁrst position of a target aligned with the query (always 1 for global pair-

wise alignments, 0 if there is no match).

5. mapping quality (ignored, always set to ’*’).

6. CIGAR string (set to ’*’ if there is no match).

7. name of the target sequence matching with the next read of the query (for

mate reads only,ignored and always set to ’*’).

8. position of the primary alignment of the next read of the query (for mate

reads only,ignored and always set to 0).

9. target sequence length (for multi-segment targets, ignored and always set

to 0).

10. query sequence (complete, not only the segment aligned to the target as

usearch does).

11. quality string (ignored, always set to ’*’).

Optional ﬁelds for query-target matches (number and order of ﬁelds

may vary):

12. AS:i:? alignment score (i.e. percentage of identity).

13. XN:i:? next best alignment score (always set to 0).

14. XM:i:? number of mismatches.

15. XO:i:? number of gap openings (excluding terminal gaps).

16. XG:i:? number of gap extensions (excluding terminal gaps).

17. NM:i:? edit distance to the target (sum of XM and XG).

18. MD:Z:? string for mismatching positions.

19. YT:Z:UU string representing the alignment type.

--search_exact ﬁlename

Search for exact full-length matches to the query sequences contained in ﬁlename in

the database of target sequences (--db). Only 100% exact matches are reported and this

command is much faster than --usearch_global. The --id, --maxaccepts and --maxre-

jects options are ignored, but the rest of the searching options may be speciﬁed.

--self Reject the sequence match if the query and target labels are identical.

--selﬁd Reject the sequence match if the query and target sequences are strictly identical.

--sizeout Add abundance annotations to the output of the option --dbmatched (using the pattern

’;size=integer;’), to report the number of queries that matched each target.

--strand plus|both

When searching for similar sequences, check the plus strand only (default) or check

both strands.

version 2.10.4 January 4, 2019 26

vsearch(1) USER COMMANDS vsearch(1)

--target_cov real

Reject the sequence match if the fraction of the target sequence aligned to the query

sequence is lower than real.The target coverage is computed as (matches + mis-

matches) / target sequence length. Internal or terminal gaps are not taken into account.

--top_hits_only

Only the top hits between the query and database sequence sets are written to the out-

put speciﬁed with the options --alnout, --samout, --userout, --blast6out, --uc,

--fastapairs, --matched or --notmatched (but not --dbmatched and --dbnotmatched). For

each query,the top hit is the one presenting the highest percentage of identity (see the

--iddef option to change the way identity is measured). For a givenquery,ifsev eral top

hits present exactly the same percentage of identity,the number of hits reported is con-

trolled by the --maxaccepts value (1 by default).

--uc ﬁlename

Output searching results in ﬁlename using a tab-separated uclust-likeformat with 10

columns. When using the --search_exact command, the table layout is the same than

with the --allpairs_global. When using the --usearch_global command, the table

present twodifferent type of entries: hit (H) or no hit (N). Each query sequence is com-

pared to all other sequences, and the best hit (--maxaccept 1) or several hits (--maxac-

cept > 1) are reported (H). Output order may vary when using multiple threads. Col-

umn content varies with the type of entry (H or N):

1. Record type: H, or N (’hit’ or ’no hit’).

2. Ordinal number of the target sequence (based on input order,starting

from zero). Set to ’*’ for N.

3. Sequence length. Set to ’*’ for N.

4. Percentage of similarity with the target sequence. Set to ’*’ for N.

5. Match orientation + or -. . Set to ’.’for N.

6. Not used, always set to zero for H, or ’*’ for N.

7. Not used, always set to zero for H, or ’*’ for N.

8. Compact representation of the pairwise alignment using the CIGAR for-

mat (Compact Idiosyncratic Gapped Alignment Report): M (match), D

(deletion) and I (insertion). The equal sign ’=’ indicates that the query is

identical to the centroid sequence. Set to ’*’ for N.

9. Label of the query sequence.

10. Label of the target centroid sequence. Set to ’*’ for N.

--uc_allhits

When using the --uc option, showall hits, not just the top hit for each query.

--usearch_global ﬁlename

Compare target sequences (--db) to the fasta-formatted query sequences contained in

ﬁlename,using global pairwise alignment.

--userﬁelds string

When using --userout, select and order the ﬁelds written to the output ﬁle. Fields are

separated by ’+’ (e.g. query+target+id). See the ’Userﬁelds’ section for a complete list

of ﬁelds.

--userout ﬁlename

Write user-deﬁned tab-separated output to ﬁlename.Select the ﬁelds with the option

--userﬁelds. Output order may vary when using multiple threads. If --userﬁelds is

empty or not present, ﬁlename is empty.

version 2.10.4 January 4, 2019 27

vsearch(1) USER COMMANDS vsearch(1)

--weak_id real

Showhits with percentage of identity of at least real,without terminating the search. A

normal search stops as soon as enough hits are found (as deﬁned by --maxaccepts,

--maxrejects, and --id). As --weak_id reports weak hits that are not deduced from

--maxaccepts, high --id values can be used, hence preserving both speed and sensitivity.

Logically, real must be smaller than the value indicated by --id.

--wordlength positive integer

Length of words (i.e. k-mers) for database indexing. The range of possible values goes

from 3 to 15, but values near 8 or 9 are generally recommended. Longer words may

reduce the sensitivity/recall for weak similarities, but can increase precision. On the

other hand, shorter words may increase sensitivity or recall, but may reduce precision.

Computation time generally increases with shorter words and decreases with longer

words, but it increases again for very long words. Memory requirements for a part of

the indexincrease with a factor of 4 each time word length increases by one nucleotide,

and this generally becomes signiﬁcant for long words (12 or more). The default value is

Shufﬂing options:

Fasta entries in the input ﬁle are outputted in a pseudo-random order.

--output ﬁlename

Write the shufﬂed sequences to ﬁlename,infasta format.

--randseed positive integer

When shufﬂing sequence order,use integeras seed. A givenseed always produces the

same output order (useful for replicability). Set to 0 to use a pseudo-random seed

(default behavior).

--relabel string

Relabel sequences using the preﬁx string and a ticker (1, 2, 3, etc.) to construct the new

headers. Use --sizeout to conservethe abundance annotations.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Relabel sequences using the MD5 message digest algorithm applied to each sequence.

Former sequence headers are discarded. The sequence is converted to upper case and U

is replaced by T before the digest is computed. The MD5 digest is a cryptographic hash

function designed to minimize the probability that twodifferent inputs givesthe same

output, evenfor very similar,but non-identical inputs. Still, there is always a very

small, but non-zero probability that twodifferent inputs give the same result. The MD5

digest generates a 128-bit (16-byte) digest that is represented by 16 hexadecimal num-

bers (using 32 symbols among 0123456789abcdef). Use --sizeout to conservethe abun-

dance annotations.

--relabel_sha1

Relabel sequences using the SHA1 message digest algorithm applied to each sequence.

It is similar to the --relabel_md5 option but uses the SHA1 algorithm instead of the

MD5 algorithm. The SHA1 digest generates a 160-bit (20-byte) result that is repre-

sented by 20 hexadecimal numbers (40 symbols). The probability of a collision (two

non-identical sequences having the same digest) is smaller for the SHA1 algorithm

than it is for the MD5 algorithm. Use --sizeout to conservethe abundance annotations.

--sizeout When using --relabel, --relabel_md5 or --relabel_sha1, preserveand report abundance

annotations to the output fasta ﬁle (using the pattern ’;size=integer;’).

version 2.10.4 January 4, 2019 28

vsearch(1) USER COMMANDS vsearch(1)

--shufﬂe ﬁlename

Pseudo-randomly shufﬂe the order of sequences contained in ﬁlename.

--topn positive integer

Output only the ﬁrst integersequences after pseudo-random reordering.

--xsize Strip abundance information from the headers when writing the output ﬁle.

Sorting options:

Fasta entries are sorted by decreasing abundance (--sortbysize) or sequence length (--sort-

bylength). Toobtain a stable sorting order,ties are sorted by decreasing abundance and label

increasing alpha-numerical order (--sortbylength), or just by label increasing alpha-numerical

order (--sortbysize). Label sorting assumes that all sequences have unique labels. The same applies

to the automatic sorting performed during chimera checking (--uchime_denovo), dereplication

(--derep_fulllength), and clustering (--cluster_fast and --cluster_size).

--maxsize positive integer

When using --sortbysize, discard sequences with an abundance value greater than inte-

ger.

--minsize positive integer

When using --sortbysize, discard sequences with an abundance value smaller than inte-

ger.

--output ﬁlename

Write the sorted sequences to ﬁlename,infasta format.

--relabel string

Please see the description of the same option under Chimera detection for details.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Please see the description of the same option under Chimera detection for details.

--relabel_sha1

Please see the description of the same option under Chimera detection for details.

--sizeout When using --relabel, report abundance annotations to the output fasta ﬁle (using the

pattern ’;size=integer;’).

--sortbylength ﬁlename

Sort by decreasing length the sequences contained in ﬁlename.See the general options

--minseqlength and --maxseqlength to eliminate short and long sequences.

--sortbysize ﬁlename

Sort by decreasing abundance the sequences contained in ﬁlename (missing abundance

values are assumed to be ’;size=1’). See the options --minsize and --maxsize to elimi-

nate rare and dominant sequences.

--topn positive integer

Output only the top integersequences (i.e. the longest or the most abundant).

--xsize Strip abundance information from the headers when writing the output ﬁle.

Subsampling options:

Subsampling randomly extracts a certain number or a certain percentage of the sequences in the

input ﬁle. If the --sizein option is in effect, the abundances of the input sequences is taken into

account and the sampling is performed as if the input sequences were rereplicated, subsampled

and dereplicated before being written to the output ﬁle. The extraction is performed as a random

sampling with a uniform distribution among the input sequences and is performed without replace-

ment. The input ﬁle is speciﬁed with --fastx_subsample option, the output ﬁles are speciﬁed with

the --fastaout and --fastqout options and the amount of sequences to be sampled is speciﬁed with

version 2.10.4 January 4, 2019 29

vsearch(1) USER COMMANDS vsearch(1)

the --sample_pct or --sample_size options. The sequences not sampled may be written to ﬁles

speciﬁed with the options --fasta_discarded and --fastq_discarded. The --fastq_ascii, --fastq_qmin

and --fastq_qmax options are also available.

--fastaout ﬁlename

Write the sampled sequences to ﬁlename,infasta format.

--fastaout_discarded ﬁlename

Write the sequences not sampled to ﬁlename,infasta format.

--fastq_ascii positive integer

Deﬁne the ASCII character number used as the basis for the FASTQ quality score. The

default is 33, which is used by the Sanger / Illumina 1.8+ FASTQ format (phred+33).

The value 64 is used by the Solexa, Illumina 1.3+ and Illumina 1.5+ formats

(phred+64).

--fastq_qmax positive integer

Specify the maximum quality score accepted when reading FASTQ ﬁles. The default is

41, which is usual for recent Sanger/Illumina 1.8+ ﬁles.

--fastq_qmin positive integer

Specify the minimum quality score accepted for FASTQ ﬁles. The default is 0, which is

usual for recent Sanger/Illumina 1.8+ ﬁles. Older formats may use scores between -5

and 2.

--fastqout ﬁlename

Write the sampled sequences to ﬁlename,infastq format. Requires input in fastq for-

mat.

--fastqout_discarded ﬁlename

Write the sequences not sampled to ﬁlename,infastq format. Requires input in fastq

format.

--fastx_subsample ﬁlename

Perform subsampling from the sequences in the speciﬁed input ﬁle that is in FASTAor

FASTQ format.

--randseed positive integer

Use integeras a seed for the pseudo-random generator.Agiv enseed always produces

the same output, which is useful for replicability.Set to 0 to use a pseudo-random seed

(default behavior).

--relabel string

Relabel sequences using the preﬁx string and a ticker (1, 2, 3, etc.) to construct the new

headers. Use --sizeout to conservethe abundance annotations.

--relabel_keep

When relabelling, keep the old identiﬁer in the header after a space.

--relabel_md5

Relabel sequences using the MD5 message digest algorithm applied to each sequence.

Former sequence headers are discarded. The sequence is converted to upper case and U

is replaced by T before the digest is computed. The MD5 digest is a cryptographic hash

function designed to minimize the probability that twodifferent inputs give the same

output, evenfor very similar,but non-identical inputs. Still, there is always a very

small, but non-zero probability that twodifferent inputs give the same result. The MD5

digest generates a 128-bit (16-byte) digest that is represented by 16 hexadecimal num-

bers (using 32 symbols among 0123456789abcdef). Use --sizeout to conservethe abun-

dance annotations.

version 2.10.4 January 4, 2019 30

vsearch(1) USER COMMANDS vsearch(1)

--relabel_sha1

Relabel sequences using the SHA1 message digest algorithm applied to each sequence.

It is similar to the --relabel_md5 option but uses the SHA1 algorithm instead of the

MD5 algorithm. The SHA1 digest generates a 160-bit (20-byte) result that is repre-

sented by 20 hexadecimal numbers (40 symbols). The probability of a collision (two

non-identical sequences having the same digest) is smaller for the SHA1 algorithm

than it is for the MD5 algorithm. Use --sizeout to conservethe abundance annotations.

--sample_pct real

Subsample the givenpercentage of the input sequences. Accepted values range from

0.0 to 100.0.

--sample_size positive integer

Extract the givennumber of sequences.

--sizein Take the abundance information of the input ﬁle into account, otherwise the abundance

of each sequence is considered to be 1.

--sizeout Write abundance information to the output ﬁle.

--xsize Strip abundance information from the headers when writing the output ﬁle.

Taxonomic classiﬁcation options:

The vsearch command --sintax will classify the input sequences according to the Sintax algorithm

as described by Robert Edgar (2016) in SINTAX: a simple non-Bayesian taxonomy classiﬁer for

16S and ITS sequences, BioRxiv, 074161. Preprint. doi: https://doi.org/10.1101/074161.

The name of the fasta ﬁle containing the input sequences to be classiﬁed is givenasanargument to

the --sintax command. The reference sequence database is speciﬁed with the --db option. The

results are written in a tab delimited text ﬁle whose name is speciﬁed with the --tabbedout option.

The --sintax_cutoffoption may be used to set a minimum levelofbootstrap support for the taxo-

nomic ranks to be reported.

Multithreading is supported. Databases in UDB ﬁles are supported. The strand option may be

speciﬁed.

The reference database must contain taxonomic information in the header of each sequence in the

form of a string starting with ";tax=" and followed by a comma-separated list of up to eight taxo-

nomic identiﬁers. Each taxonomic identiﬁer must start with an indication of the rank by one of the

letters d (for domain) k (kingdom), p (phylum), c (class), o (order), f (family), g (genus), or s

(species). The letter is followed by a colon (:) and the name of that rank. Commas and semicolons

are not allowed in the name of the rank.

Example: ">X80725_S000004313;tax=d:Bacteria,p:Proteobacteria,c:Gammaproteobacte-

ria,o:Enterobacteriales,f:Enterobacteriaceae,g:Escherichia/Shigella,s:Escherichia_coli".

--db ﬁlename

Read the reference sequences from ﬁlename,inFASTA, FASTQ or UDB format. These

sequences needs to be annotated with taxonomy.

--sintax_cutoff real

Specify a minimum levelofbootstrap support for the taxonomic ranks that will be

included in column 4 of the output ﬁle. For instance 0.9, corresponding to 90%.

--sintax ﬁlename

Read the input sequences from ﬁlename,inFASTAorFASTQ format.

--tabbedout ﬁlename

Write the results to ﬁlename,inatab-separated text format. Column 1 contains the

query label. Column 2 contains the predicted taxonomy in the same format as for the

version 2.10.4 January 4, 2019 31

vsearch(1) USER COMMANDS vsearch(1)

reference data, with bootstrap support indicated in parentheses after each rank. Column

3contains the strand. If the --sintax_cutoffoption is used, the predicted taxonomy will

be repeated in column 4 while omitting the bootstrap values and including only the

ranks with support at or above the threshold.

UDB options:

Databases to be used with the --usearch_global command may be prepared from FASTAﬁles and

stored to a binary UDB formatted ﬁle in order to speed up searching. This may be worthwhile

when searching a large database repeatedly.The sequences are indexedand stored in a way that

can be quickly loaded into memory.The commands and options belowcan be used to create and

inspect UDB ﬁles. An UDB ﬁle may be speciﬁed with the --db option instead of a FASTAformat-

ted ﬁle with the --usearch_global command.

--dbmask none|dust|soft

Specify the sequence masking method used with the --makeudb_usearch command,

either none, dust or soft. No masking is performed when none is speciﬁed. When dust

is speciﬁed, the DUST algorithm will be used for masking lowcomplexity regions

(short repeats and skewed composition). Lower case letters in the input ﬁle will be

masked when soft is speciﬁed (soft masking).

--hardmask

Mask sequences by replacing letters with N for the --makeudb_usearch command. The

default is to use lower case letters (soft masking).

--makeudb_usearch ﬁlename

Create an UDB database ﬁle from the FASTA-formatted sequences in the ﬁle with the

givenﬁlename.The UDB database is written to the ﬁle speciﬁed with the --output

option.

--output ﬁlename

Specify the ﬁlename of a FASTAorUDB output ﬁle for the --makeudb_usearch or the

--udb2fasta command, respectively.

--udb2fasta ﬁlename

Read the UDB database in the ﬁle with the givenﬁlename and output the sequences in

FASTAformat in the ﬁle speciﬁed by the --output option.

--udbinfo ﬁlename

Showinformation about the UDB database in the ﬁle with the givenﬁlename.

--udbstats ﬁlename

Report statistics about the indexedwords in the UDB database in the ﬁle with the given

ﬁlename.

--wordlength positive integer

Specify the length of the words to be used when creating the UDB database index

using the --makeudb_usearch command. Valid numbers range from 3 to 15. The default

is 8.

Userﬁelds (ﬁelds accepted by the --userﬁelds option):

aln Print a string of M (match), D (delete, i.e. a gap in the query) and I (insert, i.e. a gap in

the target) representing the pairwise alignment. Empty ﬁeld if there is no alignment.

alnlen Print the length of the query-target alignment (number of columns). The ﬁeld is set to 0

if there is no alignment.

bits Bit score (not computed for nucleotide alignments). Always set to 0.

caln Compact representation of the pairwise alignment using the CIGAR format (Compact

Idiosyncratic Gapped Alignment Report): M (match), D (deletion) and I (insertion).

Empty ﬁeld if there is no alignment.

version 2.10.4 January 4, 2019 32

vsearch(1) USER COMMANDS vsearch(1)

ev alue E-value (not computed for nucleotide alignments). Always set to -1.

exts Number of columns containing a gap extension (zero or positive integer value).

gaps Number of columns containing a gap (zero or positive integer value).

id Percentage of identity (real value ranging from 0.0 to 100.0). The percentage identity is

deﬁned as 100 * (matching columns) / (alignment length - terminal gaps).

id0 CD-HIT deﬁnition of the percentage of identity (real value ranging from 0.0 to 100.0)

using the length of the shortest sequence in the pairwise alignment as denominator: 100

*(matching columns) / (shortest sequence length).

id1 The percentage of identity (real value ranging from 0.0 to 100.0) is deﬁned as the edit

distance: 100 * (matching columns) / (alignment length).

id2 The percentage of identity (real value ranging from 0.0 to 100.0) is deﬁned as the edit

distance, excluding terminal gaps. The ﬁeld id2 is an alias for the ﬁeld id.

id3 Marine Biological Lab deﬁnition of the percentage of identity (real value ranging from

0.0 to 100.0), counting each gap opening (internal or terminal) as a single mismatch,

whether or not the gap was extended, and using the length of the longest sequence in

the pairwise alignment as denominator: 100 * (1.0 - [(mismatches + gaps) / (longest

sequence length)]).

id4 BLAST deﬁnition of the percentage of identity (real value ranging from 0.0 to 100.0),

equivalent to --iddef 1 in a context of global pairwise alignment. The ﬁeld id4 is always

equal to the ﬁeld id1.

ids Number of matches in the alignment (zero or positive integer value).

mism Number of mismatches in the alignment (zero or positive integer value).

opens Number of columns containing a gap opening (zero or positive integer value).

pairs Number of columns containing only nucleotides. That value corresponds to the length

of the alignment minus the gap-containing columns (zero or positive integer value).

pctgaps Number of columns containing gaps expressed as a percentage of the alignment length

(real value ranging from 0.0 to 100.0).

pctpv Percentage of positive columns. When working with nucleotide sequences, this is

equivalent to the percentage of matches (real value ranging from 0.0 to 100.0).

pv Number of positive columns. When working with nucleotide sequences, this is equiv-

alent to the number of matches (zero or positive integer value).

qcov Fraction of the query sequence that is aligned with the target sequence (real value rang-

ing from 0.0 to 100.0). The query coverage is computed as 100.0 * (matches + mis-

matches) / query sequence length. Internal or terminal gaps are not taken into account.

The ﬁeld is set to 0.0 if there is no alignment.

qframe Query frame (-3 to +3). That ﬁeld only concerns coding sequences and is not computed

by vsearch.Always set to +0.

qhi Last nucleotide of the query aligned with the target. Always equal to the length of the

pairwise alignment, 0 otherwise (see qihi to ignore terminal gaps).

qihi Last nucleotide of the query aligned with the target (ignoring terminal gaps).

Nucleotide numbering starts from 1. The ﬁeld is set to 0 if there is no alignment.

qilo First nucleotide of the query aligned with the target (ignoring initial gaps). Nucleotide

numbering starts from 1. The ﬁeld is set to 0 if there is no alignment.

ql Query sequence length (positive integer value). The ﬁeld is set to 0 if there is no align-

ment.

version 2.10.4 January 4, 2019 33

vsearch(1) USER COMMANDS vsearch(1)

qlo First nucleotide of the query aligned with the target. Always equal to 1 if there is an

alignment, 0 otherwise (see qilo to ignore initial gaps).

qrow Print the sequence of the query segment as seen in the pairwise alignment (i.e. with gap

insertions if need be). Empty ﬁeld if there is no alignment.

qs Query segment length. Always equal to query sequence length.

qstrand Query strand orientation (+ or - for nucleotide sequences). Empty ﬁeld if there is no

alignment.

query Query label.

raw Rawalignment score (negative,null or positive integer value). The score is the sum of

match rewards minus mismatch penalties, gap openings and gap extensions. The ﬁeld

is set to 0 if there is no alignment.

target Target label. The ﬁeld is set to ’*’ if there is no alignment.

tcov Fraction of the target sequence that is aligned with the query sequence (real value rang-

ing from 0.0 to 100.0). The target coverage is computed as 100.0 * (matches + mis-

matches) / target sequence length. Internal or terminal gaps are not taken into account.

The ﬁeld is set to 0.0 if there is no alignment.

tframe Target frame (-3 to +3). That ﬁeld only concerns coding sequences and is not computed

by vsearch.Always set to +0.

thi Last nucleotide of the target aligned with the query.Always equal to the length of the

pairwise alignment, 0 otherwise (see tihi to ignore terminal gaps).

tihi Last nucleotide of the target aligned with the query (ignoring terminal gaps).

Nucleotide numbering starts from 1. The ﬁeld is set to 0 if there is no alignment.

tilo First nucleotide of the target aligned with the query (ignoring initial gaps). Nucleotide

numbering starts from 1. The ﬁeld is set to 0 if there is no alignment.

tl Target sequence length (positive integer value). The ﬁeld is set to 0 if there is no align-

ment.

tlo First nucleotide of the target aligned with the query.Always equal to 1 if there is an

alignment, 0 otherwise (see tilo to ignore initial gaps).

trow Print the sequence of the target segment as seen in the pairwise alignment (i.e. with gap

insertions if need be). Empty ﬁeld if there is no alignment.

ts Target segment length. Always equal to target sequence length. The ﬁeld is set to 0 if

there is no alignment.

tstrand Target strand orientation (+ or - for nucleotide sequences). Always set to ’+’, so reverse

strand matches have tstrand ’+’ and qstrand

DELIBERATE CHANGES

If you are a usearch user,our objective istomakeyou feel at home. That’swhy vsearch wasdesigned to

behave likeusearch, to some extent. Likeany complexsoftware, usearch is not free from quirks and incon-

sistencies. Wedecided not to reproduce some of them, and for complete transparency, todocument here the

deliberate changes we made.

During a search with usearch, when using the options --blast6out and --output_no_hits, for queries with no

match the number of ﬁelds reported is 13, where it should be 12. This is corrected in vsearch.

The ﬁeld rawofthe --userﬁelds option is not informative inusearch. This is corrected in vsearch.

The ﬁelds qlo, qhi, tlo, thi nowhav e counterparts (qilo, qihi, tilo, tihi) reporting alignment coordinates

ignoring terminal gaps.

In usearch, when using the option --output_no_hits, queries that receive nomatch are reported in

--blast6out ﬁle, but not in the alignment output ﬁle. This is corrected in vsearch.

version 2.10.4 January 4, 2019 34

vsearch(1) USER COMMANDS vsearch(1)

vsearch introduces a new--cluster_size command that sorts sequences by decreasing abundance before

clustering.

vsearch reintroduces --iddef alternative pairwise identity deﬁnitions that were removedfrom usearch.

vsearch extends the --topn option to sorting commands.

vsearch extends the --sizein option to dereplication (--derep_fulllength) and clustering (--cluster_fast).

vsearch treats T and U as identical nucleotides during dereplication.

vsearch sorting is stabilized by using sequence abundances or sequences labels as secondary or tertiary

keys.

vsearch by default uses the DUST algorithm for masking low-complexity regions. Masking behavior is

also slightly changed to be more consistent.

NOVELTIES

vsearch introduces newcommands and newoptions not present in usearch 7. Theyare described in the

’Options’ section of this manual. Here is a short list:

-uchime2_denovo,uchime3_denovo,alignwidth, borderline, fasta_score (chimera checking)

-cluster_size, cluster_unoise, clusterout_id, clusterout_sort, proﬁle (clustering)

-fasta_width, gzip_decompress, bzip2_decompress (general option)

-iddef (clustering, pairwise alignment, searching)

-maxuniquesize (dereplication)

-relabel_md5 and relabel_sha1 (chimera detection, dereplication, FASTQ processing, shufﬂing,

sorting)

-shufﬂe (shufﬂing)

-fastq_eestats, fastq_eestats2, fastq_maxlen, fastq_truncee (FASTQ processing)

-fastaout_discarded, fastqout_discarded (subsampling)

-rereplicate (dereplication/rereplication)

EXAMPLES

Align all sequences in a database with each other and output all pairwise alignments:

vsearch --allpairs_global database.fas --alnout results.aln --acceptall

Check for the presence of chimeras (de novo); parents should be at least 1.5 times more abundant than

chimeras. Output non-chimeric sequences in fasta format (no wrapping):

vsearch --uchime_denovo queries.fas --abskew 1.5 --nonchimeras results.fas --fasta_width 0

Cluster with a 97% similarity threshold, collect cluster centroids, and write cluster descriptions using a

uclust-likeformat:

vsearch --cluster_fast queries.fas --id 0.97 --centroids centroids.fas --uc clusters.uc

Dereplicate the sequences contained in queries.fas,takeinto account the abundance information already

present, write unwrapped fasta sequences to queries_unique.fas with the newabundance information, dis-

card all sequences with an abundance of 1:

vsearch --derep_fulllength queries.fas --sizein --fasta_width 0 --sizeout --output

queries_unique.fas --minuniquesize 2

Mask simple repeats and lowcomplexity regions in the input fasta ﬁle with the DUST algorithm (masked

regions are lowercased), and write the results to the output ﬁle:

vsearch --maskfasta queries.fas --qmask dust --output queries_masked.fas

Search queries in a reference database, with a 80%-similarity threshold, taketerminal gaps into account

version 2.10.4 January 4, 2019 35

vsearch(1) USER COMMANDS vsearch(1)

when calculating pairwise similarities, output pairwise alignments:

vsearch --usearch_global queries.fas --db references.fas --id 0.8 --iddef 1 --alnout results.aln

Search a sequence dataset against itself (ignore self hits), get all matches with at least 60% similarity,and

collect results in a blast-liketab-separated format. Accept an unlimited number of hits (--maxaccepts 0),

and compare each query to all other sequences, including unlikely candidates (--maxrejects 0):

vsearch --usearch_global queries.fas --db queries.fas --self --id 0.6 --blast6out results.blast6

--maxaccepts 0 --maxrejects 0

Shufﬂe the input fasta ﬁle (change the order of sequences) in a repeatable fashion (ﬁxed seed), and write

unwrapped fasta sequences to the output ﬁle:

vsearch --shufﬂe queries.fas --output queries_shufﬂed.fas --randseed 13 --fasta_width 0

Sort by decreasing abundance the sequences contained in queries.fas (using the ’size=integer’information),

relabel the sequences while preserving the abundance information (with --sizeout), keep only sequences

with an abundance equal to or greater than 2:

vsearch --sortbysize queries.fas --output queries_sorted.fas --relabel sampleA_ --sizeout --min-

size 2

AUTHORS

Implementation by Torbjørn Rognes and Tomás Flouri, documentation by Frédéric Mahé.

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 <https://doi.org/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@iﬁ.uio.no>.

AV AILABILITY

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

Contact: Torbjørn Rognes <torognes@iﬁ.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 twolicenses, 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) anylater version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;without

ev e nthe implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See

the GNU General Public License for more details.

Youshould have receivedacopyofthe 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 modiﬁcation, are permitted provided

version 2.10.4 January 4, 2019 36

vsearch(1) USER COMMANDS vsearch(1)

that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the fol-

lowing disclaimer.

2. 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 NOTLIMITED 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, ORCONSEQUEN-

TIAL DAMAGES (INCLUDING, BUT NOTLIMITED TO, PROCUREMENT OF SUBSTITUTE

GOODS OR SERVICES; LOSS OF USE, DAT A,ORPROFITS; OR BUSINESS INTERRUPTION)

HOWEVER CAUSED AND ON ANY THEORYOFLIABILITY,WHETHER IN CONTRACT,STRICT

LIABILITY,ORTORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAM-

AGE.

We would liketothank the authors of the following projects for making their source code available:

-vsearch includes code from Google’sCityHash project by GeoffPikeand Jyrki Alakuijala, pro-

viding some excellent hash functions available under a MIT license.

-vsearch includes code derivedfrom Tatusovand Lipman’sDUST 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.

Vsearch Manual

Navigation menu

Versions of this User Manual:

Views

Navigation