<commit_before>.\" ============================================================================
.TH vsearch 1 "November 19, 2014" "version 0.3.1" "USER COMMANDS"
.\" ============================================================================
.SH NAME
vsearch \(em dereplicate, filter, sort, search, compare and clusterize
amplicons from metagenomic projects
.\" ============================================================================
.SH SYNOPSIS
Chimera detection:
.RS
\fBvsearch\fR [\fIoptions\fR] --uchime_denovo \fIfastafile\fR
(--chimeras|--nonchimeras|--uchimealns|--uchimeout) \fIoutputfile\fR
.PP
\fBvsearch\fR [\fIoptions\fR] --uchime_ref \fIfastafile\fR
(--chimeras|--nonchimeras|--uchimealns|--uchimeout) \fIoutputfile\fR
--db \fIfastafile\fR
.RE
Clustering:
.RS
\fBvsearch\fR [\fIoptions\fR] (--cluster_fast|--cluster_smallmem)
\fIfastafile\fR --uc \fIoutputfile\fR --id \fIreal\fR
.RE
Dereplication:
.RS
\fBvsearch\fR [\fIoptions\fR] --derep_fulllength \fIfastafile\fR (--output|--uc) \fIoutputfile\fR
.RE
Masking:
.RS
\fBvsearch\fR [\fIoptions\fR] --maskfasta \fIfastafile\fR --output \fIoutputfile\fR
.RE
Searching:
.RS
\fBvsearch\fR [\fIoptions\fR] --vsearch_global \fIfastafile\fR --db
\fIfastafile\fR (--alnout|--blast6out|--userout|--uc) \fIoutputfile\fR --id
\fIreal\fR
.RE
Shuffling:
.RS
\fBvsearch\fR [\fIoptions\fR] --shuffle \fIfastafile\fR --output \fIoutputfile\fR
.RE
Sorting:
.RS
\fBvsearch\fR [\fIoptions\fR] (--sortbysize|--sortbylength) \fIfastafile\fR --output \fIoutputfile\fR
.RE
.PP
.\" ============================================================================
.SH DESCRIPTION
Environmental or clinical molecular studies generate large volumes of
amplicons (e.g. SSU-rRNA sequences) that need to be dereplicated,
filtered, sorted, searched, clusterized or compared to reference
sequences. The aim of \fBvsearch\fR 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 computers,
thus guaranteeing a fast and accurate data processing.
.PP
Nucleotidic sequence comparisons is at the core of \fBvsearch\fR. To
speed up comparisons, \fBvsearch\fR implements an efficient
\fIk\fR-mer filtering, and an extremely fast implementation of the
Needleman-Wunsch algorithm, making use of the Streaming SIMD
Extensions (SSE2) of modern x86-64 CPUs. If SSE2 instructions are not
available, \fBvsearch\fR exits with an error message.
.\" ----------------------------------------------------------------------------
.SS Input
\fBvsearch\fR input is a fasta file containing one or several
nucleotidic sequences. For each sequence, the sequence identifier is
defined as the string comprised between the ">" symbol and the first
space, or the end of the line, whichever comes first. Additionally, if
the line starts with (>[;]size=\fIinteger\fR;label), contains
(>label;size=\fIinteger\fR;label) or ends with
(>label;size=\fIinteger\fR[;]), \fBvsearch\fR will remove the pattern
[;]size=\fIinteger\fR[;] from the header and interpret \fIinteger\fR
as the number of occurrences (or abundance) of the sequence in the
study. That abundance information is used or created during
dereplication, sorting and searching.
.PP
The nucleotidic sequence is defined as a string of IUPAC symbols
(ACGTURYSWKMDBHVN), starting after the end of the identifier line and
ending before the next identifier line or the file end. \fBvsearch\fR
silently ignores ascii characters 9 to 13, and exits with an error
message if ascii characters 0 to 8, 14 to 31, "." and "-" are
present. All other characters are stripped and complained about in a
non-blocking warning message.
.PP
\fBvsearch\fR operations are case insensitive, except when soft masking is
activated. For --vsearch_global (searching), --cluster_fast and
--cluster_smallmem (clustering), and --maskfasta (masking) commands,
the case is important if soft masking is used. Soft masking is
specified with the options "--dbmask soft" (for searching) or "--qmask
soft" (for searching, clustering and masking). When using soft
masking, lower case letters indicate masked symbols, while upper case
letters indicate regular symbols. Masked symbols are never included in
the unique \fIk\fR-mers used in searching. When soft masking is not
activated, all letters are converted to upper case internally and used
in result files.
.PP
When aligning sequences during searching and clustering, T and U are
considered identical, regardless of their case. If two symbols are
non-identical, their alignment will result in the negative mismatch
score (default -4), except if one or both of the symbols are ambiguous
(RYSWKMDBHVN) in which case the score is zero. Alignment of two
identical ambiguous symbols (e.g. R vs R) also receives a score of
zero.
.PP
Optionally, \fBvsearch\fR can be compiled to accepted compressed fasta
files as input (gz and bzip2 formats).
.\" ----------------------------------------------------------------------------
.SS Options
\fBvsearch\fR recognizes a large number of command-line options. For
an easier navigation, options are grouped by theme (dereplication,
filtering, sorting, searching, comparison, clustering). We start with
general options that apply to all themes.
.PP
General options:
.RS
.TP 9
.B --help
display a short help and exit.
.TP
.B --version
output version information and exit.
.TP
.BI --fasta_width\~ "positive integer"
fasta files produced by \fBvsearch\fR are wrapped (sequences are
written on lines of \fIinteger\fR nucleotides, 80 by default). Set
that value to 0 to eliminate the wrapping.
.TP
.BI --maxseqlength\~ "positive integer"
all \fBvsearch\fR operations will discard sequences of length equal or
greater than \fIinteger\fR (50,000 nucleotides by default).
.TP
.BI --minseqlength\~ "positive integer"
all \fBvsearch\fR operations will discard sequences of length smaller
than \fIinteger\fR (1 nucleotide by default for sorting or shuffling,
32 nucleotides for clustering, dereplication or searching).
.TP
.B --notrunclabels
do not truncate sequence labels at first space, use the full header.
.TP
.BI --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 launch one thread per available logical core.
.RE
.PP
.\" ----------------------------------------------------------------------------
Chimera detection options:
.RS
.TP 9
.BI --abskew \0real
when using --uchime_denovo, min abundance ratio (or abundance skew) of
parent vs chimera (2.0).
.TP
.BI --chimeras \0filename
output chimeric sequences to file.
.TP
.BI --db \0filename
when using --uchime_ref, reference database for --uchime_ref.
.TP
.BI --dn \0real
no vote pseudo-count (parameter n) (1.4).
.TP
.BI --mindiffs \0integer
minimum number of differences in segment (3).
.TP
.BI --minh \0real
minimum score (h). Increasing this value tends to reduce the number of
false positives and decrease sensitivity. Default value is
0.28. (value ranging from 0.0 to 1.0 included).
.TP
.BI --nonchimeras \0filename
output non-chimeric sequences to file.
.TP
.B --self
when using --uchime_ref, exclude identical sequences.
.TP
.B --selfid
when using --uchime_ref, exclude identical labels.
.TP
.BI --strand\~ "plus|both"
when comparing sequences to the cluster seeds, check the \fIplus\fR
strand only (default) or check \fIboth\fR strands. When using
--uchime_ref, strand is always \fIplus\fB.
.TP
.BI --uchime_denovo \0filename
detect chimeras de novo.
.TP
.BI --uchime_ref \0filename
detect chimeras using a reference database.
.TP
.BI --uchimealns \0filename
write tri-way global alignments (parentA, parentB, chimera) to
\fIfilename\fR using a human-readable format. Use --rowlen to modify
alignment length. Output order may vary when using multiple threads.
.TP
.BI --uchimeout \0filename
write chimera detection results to \fIfilename\fR using the uchime
tab-separated format of 18 fields (see
http://drive5.com/usearch/manual/uchimeout.html). Use --uchimeout5 to
use a format compatible with usearch v5 and earlier versions.
.TP
.B --uchimeout5
write chimera detection results using a tab-separated format of 17
fields (drop the 5th field of --uchimeout), compatible with usearch
version 5 and earlier versions.
.TP
.BI --xn \0real
no vote weight (parameter β) (8.0).
.RE
.PP
.\" ----------------------------------------------------------------------------
Clustering options:
.RS
.TP 9
.BI --centroids \0filename
output cluster centroid sequences to \fIfilename\fR file \fBin fasta
format?\fR.
.TP
.BI --cluster_fast \0filename
clusterize the fasta sequences in \fIfilename\fR, perform a sorting by
decreasing sequence length first.
.TP
.BI --cluster_smallmem \0filename
clusterize the fasta sequences in \fIfilename\fR without modifying
their order first. Sequence must be sorted by decreasing sequence
length, unless --usersort is used.
.TP
.BI --clusters \0string
output each cluster to a separate fasta file using the prefix
\fIstring\fR and a ticker (0, 1, 2, etc.) to construct the filenames.
.TP
.BI --consout \0filename
output cluster consensus sequences to \fIfilename\fR. For each
cluster, a multiple 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. Use --construncate to take
terminal gaps into account.
.TP
.\" .B --construncate
.\" when using the --consout option to build consensus sequences, do not
.\" ignore terminal gaps. That option skips terminal columns if they
.\" contain a majority of gaps, yielding shorter consensus sequences than
.\" when using --consout alone.
.\" .TP
.BI --id \0real
do not add the target to the cluster if the pairwise identity with the
centroid is lower than \fIreal\fR (value ranging from 0.0 to 1.0
included). The pairwise identity is defined as the number of (matching
columns) / (alignment length - terminal gaps). That definition can be
modified by --iddef.
.TP
.BI --iddef\~ "0|1|2|3|4"
change the pairwise identity definition used in --id. Values accepted
are:
.RS
.RS
.nr step 0 1
.IP \n[step]. 4
CD-HIT definition using shortest sequence as numerator.
.IP \n+[step].
edit distance.
.IP \n+[step].
edit distance excluding terminal gaps (default value).
.IP \n+[step].
Marine Biological Lab definition counting each extended gap as a
single difference.
.IP \n+[step].
BLAST, same as 2 for global pairwise alignments.
.RE
.RE
.TP
.BI --msaout \0filename
output multiple sequence alignments of each cluster to \fIfilename\fR.
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in sequences using the
\fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). Warning, when using \fIsoft\fR masking, clustering
becomes case sensitive. The default is to mask using \fIdust\fR.
.TP
.BI --strand\~ "plus|both"
when comparing sequences to the cluster seeds, check the \fIplus\fR
strand only (default) or check \fIboth\fR strands.
.TP
.BI --uc \0filename
output clustering results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each seed. \fBTO BE TESTED\fR.
.TP
.B --usersort
when using --cluster_smallmem, allows to use any sequence input order,
not only a decreasing length sorting.
.TP
Many searching options also apply to clustering:
.br
--alnout, --blast6out, --userout, --userfields, fastapairs, --matched,
--notmatched, --maxaccept, --maxreject, score filtering, gap
--penalties, masking, etc. (documentation in progress).
.RE
.PP
.\" ----------------------------------------------------------------------------
Dereplication options:
.RS
.TP 9
.BI --derep_fulllength \0filename
merge strictly identical sequences contained in
\fIfilename\fR. Identical sequences are defined as having the same
length and the same string of nucleotides (case insensitive, T and U
are considered as different). As \fBvsearch\fR needs to read
\fIfilename\fR twice, \fIfilename\fR must be a real file, not a
stream.
.TP
.BI --maxuniquesize\~ "positive integer"
discard sequences with an abundance value greater than \fIinteger\fR.
.TP
.BI --minuniquesize\~ "positive integer"
discard sequences with an abundance value smaller than \fIinteger\fR.
.TP
.BI --output \0filename
write the dereplicated sequences to \fIfilename\fR, in fasta format
and sorted by decreasing abundance. Identical sequences receive the
header of the first sequence of their group. If --sizeout is used, the
number of occurrences (i.e. abundance) is indicated at the end of the
fasta header using the pattern ";size=\fIinteger\fR".
.TP
.B --sizein
take into account the abundance annotations present in the input fasta
file (search for the pattern "[>;]size=\fIinteger\fR[;]").
.TP
.B --sizeout
add abundance annotations to the output fasta file (using the pattern
";size=\fIinteger\fR").
.TP
.BI --strand\~ "plus|both"
when searching for strictly identical sequences, check the \fIplus\fR
strand only (default) or check \fIboth\fR strands.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.TP
.BI --uc \0filename
output dereplication results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each query. In the context of dereplication, that option has no
effect.
.RE
.PP
.\" ----------------------------------------------------------------------------
Masking options:
.RS
An input sequence can be composed of lower- or uppercase
nucleotides. Lowercase nucleotides are silently converted to uppercase
before masking, unless the --qmask soft option is used. Here are the
results of combined masking options --qmask (or --dbmask for database
sequences) and --hardmask, assuming each input sequences contains both
lower and uppercase nucleotides:
.PP
.TS
tab(:);
c c c
l l l.
qmask:hardmask:action
_
none:off:no masking, lowercase converted to uppercase
none:on:idem
dust:off:masked symbols converted to lowercase, the rest converted to uppercase
dust:on:masked symbols replaced by Ns, the rest converted to upper case
soft:off:lowercase symbols considered masked, no case changes
soft:on:lowercase symbols considered masked and converted to Ns
.TE
.PP
.TP 9
.B --hardmask
mask low-complexity regions by replacing them with Ns instead of
setting them to lower case.
.TP
.BI --maskfasta \0filename
mask simple repeats and low-complexity regions in sequences contained
in \fIfilename\fR. The default is to mask using \fIdust\fR (see
--qmask to modify that behavior).
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in sequences using the
\fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). The default is to mask using \fIdust\fR.
.TP
.BI --output \0filename
write the masked sequences to \fIfilename\fR, in fasta format.
.RE
.PP
.\" ----------------------------------------------------------------------------
Shuffling options:
.RS
.TP 9
.BI --output \0filename
write the shuffled sequences to \fIfilename\fR, in fasta format.
.TP
.BI --seed\~ "positive integer"
when shuffling sequence order, use \fIinteger\fR as seed. Set to 0 to
use a pseudo-random seed (default behavior).
.TP
.BI --shuffle \0filename
pseudo-randomly shuffle the order of sequences contained in
\fIfilename\fR.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.RE
.PP
.\" ----------------------------------------------------------------------------
Sorting options:
.RS
.TP 9
.BI --maxsize\~ "positive integer"
when using --sortbysize, discard sequences with an abundance value
greater than \fIinteger\fR.
.TP
.BI --minsize\~ "positive integer"
when using --sortbysize, discard sequences with an abundance value
smaller than \fIinteger\fR.
.TP
.BI --output \0filename
write the sorted sequences to \fIfilename\fR, in fasta format.
.TP
.BI --relabel \0string
relabel sequence using the prefix \fIstring\fR and a ticker (1, 2, 3,
etc.) to construct the new headers. Use --sizeout to conserve the
abundance annotations.
.TP
.B --sizeout
when using --relabel, report abundance annotations to the output fasta
file (using the pattern ";size=\fIinteger\fR").
.TP
.BI --sortbylength \0filename
sort by decreasing length the sequences contained in
\fIfilename\fR. See the general options --minseqlength and
--maxseqlength to eliminate short and long sequences.
.TP
.BI --sortbysize \0filename
sort by decreasing abundance the sequences contained in \fIfilename\fR
(the pattern "[>;]size=\fIinteger\fR[;]" has to be present). See the
options --minsize and --maxsize to eliminate rare and dominant
sequences.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.RE
.PP
.\" ----------------------------------------------------------------------------
Searching options:
.RS
.TP 9
.BI --alnout \0filename
write pairwise global alignments to \fIfilename\fR using a
human-readable format. Use --rowlen to modify alignment length. Output
order may vary when using multiple threads.
.TP
.BI --blast6out \0filename
write search results to \fIfilename\fR using a blast-like
tab-separated format of twelve fields (listed below), with one line
per query-target matching (or lack of matching if --output_no_hits is
used). Output order may vary when using multiple threads. A similar
output can be obtain with --userout \fIfilename\fR and --userfields
query+target+id+alnlen+mism+opens+qlo+qhi+tlo+thi+evalue+bits. A
complete list and description is available in the section "Fields" of
this manual.
.RS
.RS
.nr step 1 1
.IP \n[step]. 4
\fIquery\fR: query label.
.IP \n+[step].
\fItarget\fR: target (database sequence) label. The field is set to
"*" if there is no alignment.
.IP \n+[step].
\fIid\fR: percentage of identity (real value ranging from 0.0 to
100.0). The percentage identity is defined as 100 * (matching columns)
/ (alignment length - terminal gaps). See fields id0 to id4 for other
definitions.
.IP \n+[step].
\fIalnlen\fR: length of the query-target alignment (number of
columns). The field is set to 0 if there is no alignment.
.IP \n+[step].
\fImism\fR: number of mismatches in the alignment (zero or positive
integer value).
.IP \n+[step].
\fIopens\fR: number of columns containing a gap opening (zero or
positive integer value).
.IP \n+[step].
\fIqlo\fR: first nucleotide of the query aligned with the
target. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIqhi\fR: last nucleotide of the query aligned with the
target. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fItlo\fR: first nucleotide of the target aligned with the
query. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIthi\fR: last nucleotide of the target aligned with the
query. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIevalue\fR: expectancy-value (not computed for nucleotidic
alignments). Always set to -1.
.IP \n+[step].
\fIbits\fR: bit score (not computed for nucleotidic
alignments). Always set to 0.
.RE
.RE
.TP
.BI --db \0filename
compare query sequences (--vsearch_global) to the fasta-formatted
target sequences contained in \fIfilename\fR, using global pairwise
alignment.
.TP
.BI --dbmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in target database
sequences using the \fIdust\fR or the \fIsoft\fR algorithms, or do not
mask (\fInone\fR). Warning, when using \fIsoft\fR masking search
commands become case sensitive. The default is to mask using
\fIdust\fR.
.TP
.BI --dbmatched \0filename
write database target sequences matching at least one query sequence
to \fIfilename\fR, in fasta format. If the option --sizeout is used,
the number of queries that matched each target sequence is indicated
using the pattern ";size=\fIinteger\fR".
.TP
.BI --dbnotmatched \0filename
write database target sequences not matching query sequences to
\fIfilename\fR, in fasta format.
.TP
.BI --fastapairs \0filename
write pairwise alignments of query and target sequences to
\fIfilename\fR, in fasta format.
.TP
.B --fulldp
dummy option. To maximize search sensitivity, \fBvsearch\fR uses a
8-way 16-bit SIMD vectorized full dynamic programming algorithm
(Needleman-Wunsch), whether or not --fulldp is specified.
.TP
.BI --gapext \0string
set penalties for a gap extension. See --gapopen for a complete
description of the penaly 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 terminal
gaps, in both query and target sequences (i.e. 2I/1E).
.TP
.BI --gapopen \0string
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 null
or positive integers, and "/" is use as separator.
.br
To simplify declarations, the location symbols (L, I, and R) can be
combined, the symbol (E) can be used to treat both extremities (L and
R) equally, and the symbols Q and T can be ommited to treat both
sequences equally. For instance, the default is to declare a penalty
of 20 for opening internal gaps and a penalty of 2 for opening
terminal gaps (left or right), in both query and target sequences
(i.e. 20I/2E). If only a numerical value is given, without any
sequence or location symbol, then the penalty applies to all gap
openings. To declare an infinite penalty value, the symbol "*" can be
used to indicate that gap openings are forbidden in that context.
.br
\fBvsearch\fR always initializes the six gap opening
penalties using the default parameters (20I/2E). The user is then free
to declare only the values he wants to modify. The \fIstring\fR is
scanned from left to right, accepted symbols are (0123456789/LIREQT*),
and later values override previous values.
.TP
.B --hardmask
mask low-complexity regions by replacing them with Ns instead of
setting them to lower case. For more information, please see the
Masking section.
.TP
.BI --id \0real
reject the sequence match if the pairwise identity is lower than
\fIreal\fR (value ranging from 0.0 to 1.0 included). The search
process sorts target sequences by decreasing number of \fIk\fR-mers
they have in common with the query sequence, using that information as
a proxy for sequence similarity. That efficient pre-filtering will
also prevent pairwise alignments with weakly matching targets, as
there needs to be at least 6 shared \fIk\fR-mers to start the pairwise
alignment, and at least one out of every 16 \fIk\fR-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 defined as the number of (matching columns) /
(alignment length - terminal gaps). That definition can be modified by
--iddef.
.TP
.BI --iddef\~ "0|1|2|3|4"
change the pairwise identity definition used in --id. Values accepted
are:
.RS
.RS
.nr step 0 1
.IP \n[step]. 4
CD-HIT definition using shortest sequence as numerator.
.IP \n+[step].
edit distance.
.IP \n+[step].
edit distance excluding terminal gaps (default value of --id).
.IP \n+[step].
Marine Biological Lab definition counting each extended gap as a
single difference.
.IP \n+[step].
BLAST, same as 2 for global pairwise alignments.
.RE
.RE
The option --userfields accepts the fields id0 to id4, in addition to
the field id, to report the pairwise identity values corresponding to
the different definitions.
.TP
.BI --idprefix\~ "positive integer"
reject the target sequence if the first \fIinteger\fR nucleotides do
not match the query sequence.
.TP
.BI --idsuffix\~ "positive integer"
reject the target sequence if the last \fIinteger\fR nucleotides do
not match the query sequence.
.TP
.B --leftjust
reject the target sequence if the alignment begins with gaps.
.TP
.BI --match\~ "integer"
score assigned to a match (i.e. identical nucleotides) in the pairwise
alignment. The default value is 2.
.TP
.BI --matched \0filename
write query sequences matching database target sequences to
\fIfilename\fR, in fasta format.
.TP
.BI --maxaccepts\~ "positive integer"
maximum number of hits to accept before stopping the search. The
default value is 1. That option works in pair with maxrejects. The
search process sorts target sequences by decreasing number of
\fIk\fR-mers they have in common with the query sequence, using that
information as a proxy for sequence similarity. If the first target
sequence passes the acceptation criteria, it is accepted as best hit
and the 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.
.TP
.BI --maxdiffs\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR substitutions, insertions or deletions.
.TP
.BI --maxgaps\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR insertions or deletions.
.TP
.BI --maxhits\~ "positive integer"
maximum number of hits to show once the search is terminated (hits are
sorted by decreasing identity). Unlimited by default value. \fBIt
applies to alnout, blast6out, uc, userout, fastapairs\fR.
.TP
.BI --maxid \0real
reject the target sequence if its percentage of identity with the
query is equal to or greater than \fIreal\fR.
.TP
.BI --maxqsize\~ "positive integer"
reject query sequences with an abundance equal to or greater than
\fIinteger\fR.
.TP
.BI --maxqt \0real
reject if the query/target sequence length ratio is equal to or
greater than \fIreal\fR.
.TP
.BI --maxrejects\~ "positive integer"
maximum number of non-matching target sequences to consider before
stopping the search. The default value is 32. That option works in
pair with maxaccepts. The search process sorts target sequences by
decreasing number of \fIk\fR-mers they have in common with the query
sequence, using that information as a proxy for sequence
similarity. If none of the first 32 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.
.TP
.BI --maxsizeratio \0real
reject if the query/target abundance ratio is equal to or greater than
\fIreal\fR.
.TP
.BI --maxsl \0real
reject if the shorter/longer sequence length ratio is equal to or
greater than \fIreal\fR.
.TP
.BI --maxsubs\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR substitutions.
.TP
.BI --mid \0real
reject the alignment if the percentage of identity is lower than
\fIreal\fR (ignoring all gaps, internal and terminal).
.TP
.BI --mincols\~ "positive integer"
reject the target sequence if the alignment length is shorter than
\fIinteger\fR.
.TP
.BI --minqt \0real
reject if the query/target sequence length ratio is lower than
\fIreal\fR.
.TP
.BI --minsizeratio \0real
reject if the query/target abundance ratio is lower than \fIreal\fR.
.TP
.BI --minsl \0real
reject if the shorter/longer sequence length ratio is lower than
\fIreal\fR.
.TP
.BI --mintsize\~ "positive integer"
reject target sequences with an abundance lower than \fIinteger\fR.
.TP
.BI --mismatch\~ "integer"
score assigned to a mismatch (i.e. different nucleotides) in the
pairwise alignment. The default value is -4.
.TP
.BI --notmatched \0filename
write query sequences not matching database target sequences to
\fIfilename\fR, in fasta format.
.TP
.B --output_no_hits
write both matching and non-matching queries to --alnout, --blast6out,
and --userout output files (--uc and --uc_allhits output files always
feature non-matching queries). Non-matching queries are labelled "No
hits" in --alnout files.
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in query sequences
using the \fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). Warning, when using \fIsoft\fR masking search commands
become case sensitive. The default is to mask using \fIdust\fR.
.TP
.BI --query_cov \0real
reject if the fraction of the query aligned to the target sequence is
lower than \fIreal\fR. The query coverage is computed as such: 100.0 *
(matches + mismatches) / query sequence length. Internal or terminal
gaps are not taken into account.
.TP
.B --rightjust
reject the target sequence if the alignment ends with gaps.
.TP
.BI --rowlen\~ "positive integer"
width of alignment lines in --alnout output. The default value is
64. Set to 0 to eliminate the wrapping.
.TP
.B --self
reject the alignment if the query and target labels are identical.
.TP
.B --selfid
reject the alignment if the query and target sequences are strictly
identical.
.TP
.B --sizeout
add abundance annotations to the output of the option --dbmatched
(using the pattern ";size=\fIinteger\fR").
.TP
.BI --strand\~ "plus|both"
when searching for similar sequences, check the \fIplus\fR strand only
(default) or check \fIboth\fR strands.
.TP
.BI --target_cov \0real
reject if the fraction of the target sequence aligned to the query
sequence is lower than \fIreal\fR. The target coverage is computed as
such: 100.0 * (matches + mismatches) / target sequence
length. Internal or terminal gaps are not taken into account.
.TP
.B --top_hits_only
output only the hits with the highest percentage of identity with the
query.
.TP
.BI --uc \0filename
output searching results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format. Output order may vary when using multiple
threads.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each query. \fBTO BE TESTED\fR.
.TP
.BI --userfields \0string
when using --userout, select and order the fields written to the
output file. Fields are separated by "+" (e.g. query+target+id). See
the next section for a complete list of fields.
.TP
.BI --userout \0filename
write user-defined tab-separated output to \fIfilename\fR. Select the
fields with the option --userfields. Output order may vary when using
multiple threads. If --userfields is empty or not present,
\fIfilename\fR is empty.
.TP
.BI --vsearch_global \0filename
compare target sequences (--db) to the fasta-formatted query sequences
contained in \fIfilename\fR, using global pairwise alignment.
.TP
.BI --weak_id \0real
show hits with percentage of identity of at least \fIreal\fR, without
terminating the search. A normal search stops as soon as enough hits
are found (as defined 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, \fIreal\fR must be smaller than the value
indicated by --id.
.TP
.BI --wordlength\~ "positive integer"
length of words (i.e. \fIk\fR-mers) for database indexing. The range
of possible values goes from 3 to 15, but values near 8 are generally
recommended. Longer words may reduce the sensitivity for weak
similarities, but can increase accuracy. On the other hand, shorter
words may increase sensitivity, but can reduce accuracy. Computation
time will generally increase with shorter words and decrease with
longer words. Memory requirements for a part of the index increase
with a factor of 4 each time word length increases by one nucleotide,
and this generally becomes significant for long words (12 or
more). The default value is 8.
.RE
.PP
.\" ----------------------------------------------------------------------------
Fields accepted by the --userfields option:
.RS
.TP 9
.B 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 field if there is no alignment.
.TP
.B alnlen
Print the length of the query-target alignment (number of
columns). The field is set to 0 if there is no alignment.
.TP
.B bits
Bit score (not computed for nucleotidic alignments). Always set to 0.
.TP
.B caln
Compact representation of the pairwise alignment using the CIGAR
format (Compact Idiosyncratic Gapped Alignment Report): M (match), D
(deletion) and I (insertion). Empty field if there is no alignment.
.TP
.B evalue
E-value (not computed for nucleotidic alignments). Always set to -1.
.TP
.B exts
Number of columns containing a gap extension (zero or positive integer
value).
.TP
.B gaps
Number of columns containing a gap (zero or positive integer value).
.TP
.B id
Percentage of identity (real value ranging from 0.0 to 100.0). The
percentage identity is defined as 100 * (matching columns) /
(alignment length - terminal gaps).
.TP
.B id0
CD-HIT definition of the percentage of identity, using the shortest
sequence in the pairwise alignment as numerator (real value ranging
from 0.0 to 100.0).
.TP
.B id1
The percentage of identity (real value ranging from 0.0 to 100.0) is
defined as the edit distance: 100 * (matching columns) / (alignment
length).
.TP
.B id2
The percentage of identity (real value ranging from 0.0 to 100.0) is
defined as the edit distance, excluding terminal gaps. The field id2 is
an alias for the field id.
.TP
.B id3
Marine Biological Lab definition of the percentage of identity (real
value ranging from 0.0 to 100.0), counting each extended gap as a
single difference.
.TP
.B id4
BLAST definition of the percentage of identity (real value ranging
from 0.0 to 100.0), same as the field id2 for global pairwise
alignments.
.TP
.B ids
Number of matches in the alignment (zero or positive integer value).
.TP
.B mism
Number of mismatches in the alignment (zero or positive integer
value).
.TP
.B opens
Number of columns containing a gap opening (zero or positive integer
value).
.TP
.B 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).
.TP
.B pctgaps
Number of columns containing gaps expressed as a percentage of the
alignment length (real value ranging from 0.0 to 100.0).
.TP
.B pctpv
Percentage of positive columns. When working with nucleotidic
sequences, this is equivalent to the percentage of matches (real value
ranging from 0.0 to 100.0).
.TP
.B pv
Number of positive columns. When working with nucleotidic sequences,
this is equivalent to the number of matches (zero or positive integer
value).
.TP
.B qcov
Fraction of the query sequence that is aligned with the target
sequence (real value ranging from 0.0 to 100.0). The query coverage is
computed as such: 100.0 * (matches + mismatches) / query sequence
length. Internal or terminal gaps are not taken into account. The
field is set to 0.0 if there is no alignment.
.TP
.B qframe
Query frame (-3 to +3). That field only concerns coding sequences and
is not computed by \fBvsearch\fR. Always set to +0.
.TP
.B qhi
Last nucleotide of the query aligned with the target. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B ql
Query sequence length (positive integer value). The field is set to 0
if there is no alignment.
.TP
.B qlo
First nucleotide of the query aligned with the target. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B qrow
Print the sequence of the query segment as seen in the pairwise
alignment (i.e. with gap insertions if need be). Empty field if there
is no alignment.
.TP
.B qs
Query segment length. Always equal to query sequence length.
.\" The meaning of that field is not clear to us. 
.TP
.B qstrand
Query strand orientation (+ or - for nucleotidic sequences). Empty
field if there is no alignment.
.TP
.B query
Query label.
.TP
.B raw
Raw alignment score (negative, null or positive integer value). The
score is the sum of match rewards minus mismatch penalties, gap
openings and gap extensions. The field is set to 0 if there is no
alignment.
.TP
.B target
Target label. The field is set to "*" if there is no alignment.
.TP
.B tcov
Fraction of the target sequence that is aligned with the query
sequence (real value ranging from 0.0 to 100.0). The target coverage
is computed as such: 100.0 * (matches + mismatches) / target sequence
length. Internal or terminal gaps are not taken into account. The
field is set to 0.0 if there is no alignment.
.TP
.B tframe
Target frame (-3 to +3). That field only concerns coding sequences and
is not computed by \fBvsearch\fR. Always set to +0.
.TP
.B thi
Last nucleotide of the target aligned with the query. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B tl
Target sequence length (positive integer value). The field is set to 0
if there is no alignment.
.TP
.B tlo
First nucleotide of the target aligned with the query. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B trow
Print the sequence of the target segment as seen in the pairwise
alignment (i.e. with gap insertions if need be). Empty field if there
is no alignment.
.TP
.B ts
Target segment length. Always equal to target sequence length. The
field is set to 0 if there is no alignment.
.TP
.B tstrand
Target strand orientation (+ or - for nucleotidic sequences). Always
set to "+", so reverse strand matches have tstrand "+" and qstrand
"-". Empty field if there is no alignment.
.RE
.PP
.\" ============================================================================
.SH DELIBERATE CHANGES
If you are a usearch user, our objective is to make you feel at
home. That's why \fBvsearch\fR was designed to behave like usearch, to
some extend. Like any complex software, usearch is not free from
quirks and inconsistencies. We decided not to reproduce some of them,
and for complete transparency, to document here the deliberate changes
we made.
.PP
During a search with usearch, when using the options --blast6out and
--output_no_hits, for queries with no match the number of fields
reported is 13, where it should be 12. This is corrected in
\fBvsearch\fR.
.PP
The fields qlo, qhi, tlo, thi and raw of the --userfields option are
not informative in usearch. This is corrected in \fBvsearch\fR.
.PP
In usearch, when using the option --output_no_hits, queries that
receive no match are reported in blast6out file, but not in the
alignment output file. This is corrected in \fBvsearch\fR.
.PP
\fBvsearch\fR reintroduces with --iddef alternative pairwise identity
definitions that were removed from usearch.
.PP
\fBvsearch\fR extends the --topn option to sorting commands.
.PP
.\" ============================================================================
.SH NOVELTIES
\fBvsearch\fR introduces new options not present in usearch. They are<commit_msg>Clean synopsis<commit_after>.\" ============================================================================
.TH vsearch 1 "November 19, 2014" "version 0.3.1" "USER COMMANDS"
.\" ============================================================================
.SH NAME
vsearch \(em dereplicate, filter, sort, search, compare and clusterize
amplicons from metagenomic projects
.\" ============================================================================
.SH SYNOPSIS
Chimera detection:
.RS
\fBvsearch\fR [\fIoptions\fR] --uchime_denovo \fIfastafile\fR
(--chimeras|--nonchimeras|--uchimealns|--uchimeout) \fIoutputfile\fR
.PP
\fBvsearch\fR [\fIoptions\fR] --uchime_ref \fIfastafile\fR
(--chimeras|--nonchimeras|--uchimealns|--uchimeout) \fIoutputfile\fR
--db \fIfastafile\fR
.RE
Clustering:
.RS
\fBvsearch\fR [\fIoptions\fR] (--cluster_fast|--cluster_smallmem)
\fIfastafile\fR (--alnout|--blast6out|--uc|--userout) \fIoutputfile\fR
--id \fIreal\fR
.RE
Dereplication:
.RS
\fBvsearch\fR [\fIoptions\fR] --derep_fulllength \fIfastafile\fR
(--output|--uc) \fIoutputfile\fR
.RE
Masking:
.RS
\fBvsearch\fR [\fIoptions\fR] --maskfasta \fIfastafile\fR --output
\fIoutputfile\fR
.RE
Searching:
.RS
\fBvsearch\fR [\fIoptions\fR] --vsearch_global \fIfastafile\fR --db
\fIfastafile\fR (--alnout|--blast6out|--uc|--userout) \fIoutputfile\fR
--id \fIreal\fR
.RE
Shuffling:
.RS
\fBvsearch\fR [\fIoptions\fR] --shuffle \fIfastafile\fR --output
\fIoutputfile\fR
.RE
Sorting:
.RS
\fBvsearch\fR [\fIoptions\fR] (--sortbylength|--sortbysize)
\fIfastafile\fR --output \fIoutputfile\fR
.RE
.PP
.\" ============================================================================
.SH DESCRIPTION
Environmental or clinical molecular studies generate large volumes of
amplicons (e.g. SSU-rRNA sequences) that need to be dereplicated,
filtered, sorted, searched, clusterized or compared to reference
sequences. The aim of \fBvsearch\fR 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 computers,
thus guaranteeing a fast and accurate data processing.
.PP
Nucleotidic sequence comparisons is at the core of \fBvsearch\fR. To
speed up comparisons, \fBvsearch\fR implements an efficient
\fIk\fR-mer filtering, and an extremely fast implementation of the
Needleman-Wunsch algorithm, making use of the Streaming SIMD
Extensions (SSE2) of modern x86-64 CPUs. If SSE2 instructions are not
available, \fBvsearch\fR exits with an error message.
.\" ----------------------------------------------------------------------------
.SS Input
\fBvsearch\fR input is a fasta file containing one or several
nucleotidic sequences. For each sequence, the sequence identifier is
defined as the string comprised between the ">" symbol and the first
space, or the end of the line, whichever comes first. Additionally, if
the line starts with (>[;]size=\fIinteger\fR;label), contains
(>label;size=\fIinteger\fR;label) or ends with
(>label;size=\fIinteger\fR[;]), \fBvsearch\fR will remove the pattern
[;]size=\fIinteger\fR[;] from the header and interpret \fIinteger\fR
as the number of occurrences (or abundance) of the sequence in the
study. That abundance information is used or created during
dereplication, sorting and searching.
.PP
The nucleotidic sequence is defined as a string of IUPAC symbols
(ACGTURYSWKMDBHVN), starting after the end of the identifier line and
ending before the next identifier line or the file end. \fBvsearch\fR
silently ignores ascii characters 9 to 13, and exits with an error
message if ascii characters 0 to 8, 14 to 31, "." and "-" are
present. All other characters are stripped and complained about in a
non-blocking warning message.
.PP
\fBvsearch\fR operations are case insensitive, except when soft masking is
activated. For --vsearch_global (searching), --cluster_fast and
--cluster_smallmem (clustering), and --maskfasta (masking) commands,
the case is important if soft masking is used. Soft masking is
specified with the options "--dbmask soft" (for searching) or "--qmask
soft" (for searching, clustering and masking). When using soft
masking, lower case letters indicate masked symbols, while upper case
letters indicate regular symbols. Masked symbols are never included in
the unique \fIk\fR-mers used in searching. When soft masking is not
activated, all letters are converted to upper case internally and used
in result files.
.PP
When aligning sequences during searching and clustering, T and U are
considered identical, regardless of their case. If two symbols are
non-identical, their alignment will result in the negative mismatch
score (default -4), except if one or both of the symbols are ambiguous
(RYSWKMDBHVN) in which case the score is zero. Alignment of two
identical ambiguous symbols (e.g. R vs R) also receives a score of
zero.
.PP
Optionally, \fBvsearch\fR can be compiled to accepted compressed fasta
files as input (gz and bzip2 formats).
.\" ----------------------------------------------------------------------------
.SS Options
\fBvsearch\fR recognizes a large number of command-line options. For
an easier navigation, options are grouped by theme (dereplication,
filtering, sorting, searching, comparison, clustering). We start with
general options that apply to all themes.
.PP
General options:
.RS
.TP 9
.B --help
display a short help and exit.
.TP
.B --version
output version information and exit.
.TP
.BI --fasta_width\~ "positive integer"
fasta files produced by \fBvsearch\fR are wrapped (sequences are
written on lines of \fIinteger\fR nucleotides, 80 by default). Set
that value to 0 to eliminate the wrapping.
.TP
.BI --maxseqlength\~ "positive integer"
all \fBvsearch\fR operations will discard sequences of length equal or
greater than \fIinteger\fR (50,000 nucleotides by default).
.TP
.BI --minseqlength\~ "positive integer"
all \fBvsearch\fR operations will discard sequences of length smaller
than \fIinteger\fR (1 nucleotide by default for sorting or shuffling,
32 nucleotides for clustering, dereplication or searching).
.TP
.B --notrunclabels
do not truncate sequence labels at first space, use the full header.
.TP
.BI --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 launch one thread per available logical core.
.RE
.PP
.\" ----------------------------------------------------------------------------
Chimera detection options:
.PP
.RS
Chimera detection is based on a scoring function controlled by five
options (--dn, --mindiv, mindiffs, --minh, --xn).
.PP
In \fIde novo\fR mode, input fasta file should present abundance
annotations (pattern [;]size=\fIinteger\fR[;] in the fasta
header). The input order influences the chimera detection, 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.
.PP
.TP 9
.BI --abskew \0real
when using --uchime_denovo, the abundance skew is used to distinguish
in a 3-way alignment which sequence is the chimera and which are the
parents. The assumption is that chimeras appeared latter in the PCR
process and are therefore less abundant than their parents. The
default value is 2.0, which means that the parents should be at least
2 times more abundant than their chimera. Any positive values equal or
greater than 1.0 can be used.
.TP
.BI --chimeras \0filename
output chimeric sequences to file. Output order may vary when using
multiple threads.
.TP
.BI --db \0filename
when using --uchime_ref, detect chimeras using the fasta-formatted
reference sequences contained in \fIfilename\fR. Reference sequences
are assumed to be chimera-free. Chimeras will not be detected if their
parents (or sufficiently close relatives) are not present in the
database.
.TP
.BI --dn \0real
no vote pseudo-count (parameter n) (1.4).
.TP
.BI --mindiffs \0integer
minimum number of differences in segment (3).
.TP
.BI --minh \0real
minimum score (h). Increasing this value tends to reduce the number of
false positives and decrease sensitivity. Default value is
0.28. (value ranging from 0.0 to 1.0 included).
.TP
.BI --nonchimeras \0filename
output non-chimeric sequences to file. Output order may vary when
using multiple threads.
.TP
.BI --rowlen\~ "positive integer"
width of 3-way alignments in --uchimealns output. The default value is
80. Set to 0 to eliminate the wrapping.
.TP
.B --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).
.TP
.B --selfid
when using --uchime_ref, ignore a reference sequence when its
nucleotidic sequence is strictly identical with the query sequence.
.TP
.BI --strand\~ "plus|both"
when using --uchime_denovo, check the \fIplus\fR strand only (default)
or check \fIboth\fR strands. When using --uchime_ref, strand is always
\fIplus\fB.
.TP
.BI --threads\~ "positive integer"
when using the command --uchime_ref, set the 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 launch
one thread per available logical core.
.TP
.BI --uchime_denovo \0filename
detect chimeras de novo. Multithreading is not supported.
.TP
.BI --uchime_ref \0filename
detect chimeras present in the fasta-formatted \fIfilename\fR by
comparing them with reference sequences (option --db). Multithreading
is supported.
.TP
.BI --uchimealns \0filename
write 3-way global alignments (parentA, parentB, chimera) to
\fIfilename\fR using a human-readable format. Use --rowlen to modify
alignment length. Output order may vary when using multiple threads.
.TP
.BI --uchimeout \0filename
write chimera detection results to \fIfilename\fR using the uchime
tab-separated format of 18 fields (see the list below). Use
--uchimeout5 to use a format compatible with usearch v5 and earlier
versions. Output order may vary when using multiple threads.
.RS
.RS
.nr step 1 1
.IP \n[step]. 4
score \(em higher score means more strongly chimeric alignment.
.IP \n+[step].
Q \(em query sequence label.
.IP \n+[step].
A \(em parent A sequence label.
.IP \n+[step].
B \(em parent B sequence label.
.IP \n+[step].
T \(em top parent sequence label (i.e. parent most similar to the
query). That fields is removed when using --uchimeout5.
.IP \n+[step].
idQM \(em percentage of similarity of query (Q) and the model
(M) constructed as a segment of parent A and a segment of parent B.
.IP \n+[step].
idQA \(em percentage of similarity of query (Q) and parent A.
.IP \n+[step].
idQB \(em percentage of similarity of query (Q) and parent B.
.IP \n+[step].
idAB \(em percentage of similarity of parent A and parent B.
.IP \n+[step].
idQT \(em percentage of similarity of query (Q) and the top
parent (T).
.IP \n+[step].
LY \(em yes votes in the left segment of the model.
.IP \n+[step].
LN \(em no votes in the left segment of the model.
.IP \n+[step].
LA \(em abstain votes in the left segment of the model.
.IP \n+[step].
RY \(em yes votes in the right segment of the model.
.IP \n+[step].
RN \(em no votes in the right segment of the model.
.IP \n+[step].
RA \(em abstain votes in the right segment of the model.
.IP \n+[step].
div \(em divergence, defined as (idQM - idQT).
.IP \n+[step].
YN \(em query is chimeric (Y), or not (N) or is a borderline
case (?).
.RE
.RE
.TP
.B --uchimeout5
write chimera detection results using a tab-separated format of 17
fields (drop the 5th field of --uchimeout), compatible with usearch
version 5 and earlier versions.
.TP
.BI --xn \0real
no vote weight (parameter β) (8.0).
.RE
.PP
.\" ----------------------------------------------------------------------------
Clustering options:
.RS
.TP 9
.BI --centroids \0filename
output cluster centroid sequences to \fIfilename\fR file \fBin fasta
format?\fR.
.TP
.BI --cluster_fast \0filename
clusterize the fasta sequences in \fIfilename\fR, perform a sorting by
decreasing sequence length first.
.TP
.BI --cluster_smallmem \0filename
clusterize the fasta sequences in \fIfilename\fR without modifying
their order first. Sequence must be sorted by decreasing sequence
length, unless --usersort is used.
.TP
.BI --clusters \0string
output each cluster to a separate fasta file using the prefix
\fIstring\fR and a ticker (0, 1, 2, etc.) to construct the filenames.
.TP
.BI --consout \0filename
output cluster consensus sequences to \fIfilename\fR. For each
cluster, a multiple 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. Use --construncate to take
terminal gaps into account.
.TP
.\" .B --construncate
.\" when using the --consout option to build consensus sequences, do not
.\" ignore terminal gaps. That option skips terminal columns if they
.\" contain a majority of gaps, yielding shorter consensus sequences than
.\" when using --consout alone.
.\" .TP
.BI --id \0real
do not add the target to the cluster if the pairwise identity with the
centroid is lower than \fIreal\fR (value ranging from 0.0 to 1.0
included). The pairwise identity is defined as the number of (matching
columns) / (alignment length - terminal gaps). That definition can be
modified by --iddef.
.TP
.BI --iddef\~ "0|1|2|3|4"
change the pairwise identity definition used in --id. Values accepted
are:
.RS
.RS
.nr step 0 1
.IP \n[step]. 4
CD-HIT definition using shortest sequence as numerator.
.IP \n+[step].
edit distance.
.IP \n+[step].
edit distance excluding terminal gaps (default value).
.IP \n+[step].
Marine Biological Lab definition counting each extended gap as a
single difference.
.IP \n+[step].
BLAST, same as 2 for global pairwise alignments.
.RE
.RE
.TP
.BI --msaout \0filename
output multiple sequence alignments of each cluster to \fIfilename\fR.
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in sequences using the
\fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). Warning, when using \fIsoft\fR masking, clustering
becomes case sensitive. The default is to mask using \fIdust\fR.
.TP
.BI --strand\~ "plus|both"
when comparing sequences to the cluster seeds, check the \fIplus\fR
strand only (default) or check \fIboth\fR strands.
.TP
.BI --uc \0filename
output clustering results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each seed. \fBTO BE TESTED\fR.
.TP
.B --usersort
when using --cluster_smallmem, allows to use any sequence input order,
not only a decreasing length sorting.
.TP
Many searching options also apply to clustering:
.br
--alnout, --blast6out, --userout, --userfields, fastapairs, --matched,
--notmatched, --maxaccept, --maxreject, score filtering, gap
--penalties, masking, etc. (documentation in progress).
.RE
.PP
.\" ----------------------------------------------------------------------------
Dereplication options:
.RS
.TP 9
.BI --derep_fulllength \0filename
merge strictly identical sequences contained in
\fIfilename\fR. Identical sequences are defined as having the same
length and the same string of nucleotides (case insensitive, T and U
are considered as different). As \fBvsearch\fR needs to read
\fIfilename\fR twice, \fIfilename\fR must be a real file, not a
stream.
.TP
.BI --maxuniquesize\~ "positive integer"
discard sequences with an abundance value greater than \fIinteger\fR.
.TP
.BI --minuniquesize\~ "positive integer"
discard sequences with an abundance value smaller than \fIinteger\fR.
.TP
.BI --output \0filename
write the dereplicated sequences to \fIfilename\fR, in fasta format
and sorted by decreasing abundance. Identical sequences receive the
header of the first sequence of their group. If --sizeout is used, the
number of occurrences (i.e. abundance) is indicated at the end of the
fasta header using the pattern ";size=\fIinteger\fR".
.TP
.B --sizein
take into account the abundance annotations present in the input fasta
file (search for the pattern "[>;]size=\fIinteger\fR[;]").
.TP
.B --sizeout
add abundance annotations to the output fasta file (using the pattern
";size=\fIinteger\fR").
.TP
.BI --strand\~ "plus|both"
when searching for strictly identical sequences, check the \fIplus\fR
strand only (default) or check \fIboth\fR strands.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.TP
.BI --uc \0filename
output dereplication results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each query. In the context of dereplication, that option has no
effect.
.RE
.PP
.\" ----------------------------------------------------------------------------
Masking options:
.RS
.PP
An input sequence can be composed of lower- or uppercase
nucleotides. Lowercase nucleotides are silently converted to uppercase
before masking, unless the --qmask soft option is used. Here are the
results of combined masking options --qmask (or --dbmask for database
sequences) and --hardmask, assuming each input sequences contains both
lower and uppercase nucleotides:
.PP
.TS
tab(:);
c c c
l l l.
qmask:hardmask:action
_
none:off:no masking, lowercase converted to uppercase
none:on:idem
dust:off:masked symbols converted to lowercase, the rest converted to uppercase
dust:on:masked symbols replaced by Ns, the rest converted to upper case
soft:off:lowercase symbols considered masked, no case changes
soft:on:lowercase symbols considered masked and converted to Ns
.TE
.PP
.TP 9
.B --hardmask
mask low-complexity regions by replacing them with Ns instead of
setting them to lower case.
.TP
.BI --maskfasta \0filename
mask simple repeats and low-complexity regions in sequences contained
in \fIfilename\fR. The default is to mask using \fIdust\fR (see
--qmask to modify that behavior).
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in sequences using the
\fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). The default is to mask using \fIdust\fR.
.TP
.BI --output \0filename
write the masked sequences to \fIfilename\fR, in fasta format.
.RE
.PP
.\" ----------------------------------------------------------------------------
Shuffling options:
.RS
.TP 9
.BI --output \0filename
write the shuffled sequences to \fIfilename\fR, in fasta format.
.TP
.BI --seed\~ "positive integer"
when shuffling sequence order, use \fIinteger\fR as seed. Set to 0 to
use a pseudo-random seed (default behavior).
.TP
.BI --shuffle \0filename
pseudo-randomly shuffle the order of sequences contained in
\fIfilename\fR.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.RE
.PP
.\" ----------------------------------------------------------------------------
Sorting options:
.RS
.TP 9
.BI --maxsize\~ "positive integer"
when using --sortbysize, discard sequences with an abundance value
greater than \fIinteger\fR.
.TP
.BI --minsize\~ "positive integer"
when using --sortbysize, discard sequences with an abundance value
smaller than \fIinteger\fR.
.TP
.BI --output \0filename
write the sorted sequences to \fIfilename\fR, in fasta format.
.TP
.BI --relabel \0string
relabel sequence using the prefix \fIstring\fR and a ticker (1, 2, 3,
etc.) to construct the new headers. Use --sizeout to conserve the
abundance annotations.
.TP
.B --sizeout
when using --relabel, report abundance annotations to the output fasta
file (using the pattern ";size=\fIinteger\fR").
.TP
.BI --sortbylength \0filename
sort by decreasing length the sequences contained in
\fIfilename\fR. See the general options --minseqlength and
--maxseqlength to eliminate short and long sequences.
.TP
.BI --sortbysize \0filename
sort by decreasing abundance the sequences contained in \fIfilename\fR
(the pattern "[>;]size=\fIinteger\fR[;]" has to be present). See the
options --minsize and --maxsize to eliminate rare and dominant
sequences.
.TP
.BI --topn\~ "positive integer"
output only the top \fIinteger\fR sequences.
.RE
.PP
.\" ----------------------------------------------------------------------------
Searching options:
.RS
.TP 9
.BI --alnout \0filename
write pairwise global alignments to \fIfilename\fR using a
human-readable format. Use --rowlen to modify alignment length. Output
order may vary when using multiple threads.
.TP
.BI --blast6out \0filename
write search results to \fIfilename\fR using a blast-like
tab-separated format of twelve fields (listed below), with one line
per query-target matching (or lack of matching if --output_no_hits is
used). Output order may vary when using multiple threads. A similar
output can be obtain with --userout \fIfilename\fR and --userfields
query+target+id+alnlen+mism+opens+qlo+qhi+tlo+thi+evalue+bits. A
complete list and description is available in the section "Fields" of
this manual.
.RS
.RS
.nr step 1 1
.IP \n[step]. 4
\fIquery\fR: query label.
.IP \n+[step].
\fItarget\fR: target (database sequence) label. The field is set to
"*" if there is no alignment.
.IP \n+[step].
\fIid\fR: percentage of identity (real value ranging from 0.0 to
100.0). The percentage identity is defined as 100 * (matching columns)
/ (alignment length - terminal gaps). See fields id0 to id4 for other
definitions.
.IP \n+[step].
\fIalnlen\fR: length of the query-target alignment (number of
columns). The field is set to 0 if there is no alignment.
.IP \n+[step].
\fImism\fR: number of mismatches in the alignment (zero or positive
integer value).
.IP \n+[step].
\fIopens\fR: number of columns containing a gap opening (zero or
positive integer value).
.IP \n+[step].
\fIqlo\fR: first nucleotide of the query aligned with the
target. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIqhi\fR: last nucleotide of the query aligned with the
target. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fItlo\fR: first nucleotide of the target aligned with the
query. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIthi\fR: last nucleotide of the target aligned with the
query. Nucleotide numbering starts from 1. The field is set to 0 if
there is no alignment.
.IP \n+[step].
\fIevalue\fR: expectancy-value (not computed for nucleotidic
alignments). Always set to -1.
.IP \n+[step].
\fIbits\fR: bit score (not computed for nucleotidic
alignments). Always set to 0.
.RE
.RE
.TP
.BI --db \0filename
compare query sequences (--vsearch_global) to the fasta-formatted
target sequences contained in \fIfilename\fR, using global pairwise
alignment.
.TP
.BI --dbmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in target database
sequences using the \fIdust\fR or the \fIsoft\fR algorithms, or do not
mask (\fInone\fR). Warning, when using \fIsoft\fR masking search
commands become case sensitive. The default is to mask using
\fIdust\fR.
.TP
.BI --dbmatched \0filename
write database target sequences matching at least one query sequence
to \fIfilename\fR, in fasta format. If the option --sizeout is used,
the number of queries that matched each target sequence is indicated
using the pattern ";size=\fIinteger\fR".
.TP
.BI --dbnotmatched \0filename
write database target sequences not matching query sequences to
\fIfilename\fR, in fasta format.
.TP
.BI --fastapairs \0filename
write pairwise alignments of query and target sequences to
\fIfilename\fR, in fasta format.
.TP
.B --fulldp
dummy option. To maximize search sensitivity, \fBvsearch\fR uses a
8-way 16-bit SIMD vectorized full dynamic programming algorithm
(Needleman-Wunsch), whether or not --fulldp is specified.
.TP
.BI --gapext \0string
set penalties for a gap extension. See --gapopen for a complete
description of the penaly 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 terminal
gaps, in both query and target sequences (i.e. 2I/1E).
.TP
.BI --gapopen \0string
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 null
or positive integers, and "/" is use as separator.
.br
To simplify declarations, the location symbols (L, I, and R) can be
combined, the symbol (E) can be used to treat both extremities (L and
R) equally, and the symbols Q and T can be ommited to treat both
sequences equally. For instance, the default is to declare a penalty
of 20 for opening internal gaps and a penalty of 2 for opening
terminal gaps (left or right), in both query and target sequences
(i.e. 20I/2E). If only a numerical value is given, without any
sequence or location symbol, then the penalty applies to all gap
openings. To declare an infinite penalty value, the symbol "*" can be
used to indicate that gap openings are forbidden in that context.
.br
\fBvsearch\fR always initializes the six gap opening
penalties using the default parameters (20I/2E). The user is then free
to declare only the values he wants to modify. The \fIstring\fR is
scanned from left to right, accepted symbols are (0123456789/LIREQT*),
and later values override previous values.
.TP
.B --hardmask
mask low-complexity regions by replacing them with Ns instead of
setting them to lower case. For more information, please see the
Masking section.
.TP
.BI --id \0real
reject the sequence match if the pairwise identity is lower than
\fIreal\fR (value ranging from 0.0 to 1.0 included). The search
process sorts target sequences by decreasing number of \fIk\fR-mers
they have in common with the query sequence, using that information as
a proxy for sequence similarity. That efficient pre-filtering will
also prevent pairwise alignments with weakly matching targets, as
there needs to be at least 6 shared \fIk\fR-mers to start the pairwise
alignment, and at least one out of every 16 \fIk\fR-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 defined as the number of (matching columns) /
(alignment length - terminal gaps). That definition can be modified by
--iddef.
.TP
.BI --iddef\~ "0|1|2|3|4"
change the pairwise identity definition used in --id. Values accepted
are:
.RS
.RS
.nr step 0 1
.IP \n[step]. 4
CD-HIT definition using shortest sequence as numerator.
.IP \n+[step].
edit distance.
.IP \n+[step].
edit distance excluding terminal gaps (default value of --id).
.IP \n+[step].
Marine Biological Lab definition counting each extended gap as a
single difference.
.IP \n+[step].
BLAST, same as 2 for global pairwise alignments.
.RE
.RE
The option --userfields accepts the fields id0 to id4, in addition to
the field id, to report the pairwise identity values corresponding to
the different definitions.
.TP
.BI --idprefix\~ "positive integer"
reject the target sequence if the first \fIinteger\fR nucleotides do
not match the query sequence.
.TP
.BI --idsuffix\~ "positive integer"
reject the target sequence if the last \fIinteger\fR nucleotides do
not match the query sequence.
.TP
.B --leftjust
reject the target sequence if the alignment begins with gaps.
.TP
.BI --match\~ "integer"
score assigned to a match (i.e. identical nucleotides) in the pairwise
alignment. The default value is 2.
.TP
.BI --matched \0filename
write query sequences matching database target sequences to
\fIfilename\fR, in fasta format.
.TP
.BI --maxaccepts\~ "positive integer"
maximum number of hits to accept before stopping the search. The
default value is 1. That option works in pair with maxrejects. The
search process sorts target sequences by decreasing number of
\fIk\fR-mers they have in common with the query sequence, using that
information as a proxy for sequence similarity. If the first target
sequence passes the acceptation criteria, it is accepted as best hit
and the 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.
.TP
.BI --maxdiffs\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR substitutions, insertions or deletions.
.TP
.BI --maxgaps\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR insertions or deletions.
.TP
.BI --maxhits\~ "positive integer"
maximum number of hits to show once the search is terminated (hits are
sorted by decreasing identity). Unlimited by default value. \fBIt
applies to alnout, blast6out, uc, userout, fastapairs\fR.
.TP
.BI --maxid \0real
reject the target sequence if its percentage of identity with the
query is equal to or greater than \fIreal\fR.
.TP
.BI --maxqsize\~ "positive integer"
reject query sequences with an abundance equal to or greater than
\fIinteger\fR.
.TP
.BI --maxqt \0real
reject if the query/target sequence length ratio is equal to or
greater than \fIreal\fR.
.TP
.BI --maxrejects\~ "positive integer"
maximum number of non-matching target sequences to consider before
stopping the search. The default value is 32. That option works in
pair with maxaccepts. The search process sorts target sequences by
decreasing number of \fIk\fR-mers they have in common with the query
sequence, using that information as a proxy for sequence
similarity. If none of the first 32 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.
.TP
.BI --maxsizeratio \0real
reject if the query/target abundance ratio is equal to or greater than
\fIreal\fR.
.TP
.BI --maxsl \0real
reject if the shorter/longer sequence length ratio is equal to or
greater than \fIreal\fR.
.TP
.BI --maxsubs\~ "positive integer"
reject the target sequence if the alignment contains at least
\fIinteger\fR substitutions.
.TP
.BI --mid \0real
reject the alignment if the percentage of identity is lower than
\fIreal\fR (ignoring all gaps, internal and terminal).
.TP
.BI --mincols\~ "positive integer"
reject the target sequence if the alignment length is shorter than
\fIinteger\fR.
.TP
.BI --minqt \0real
reject if the query/target sequence length ratio is lower than
\fIreal\fR.
.TP
.BI --minsizeratio \0real
reject if the query/target abundance ratio is lower than \fIreal\fR.
.TP
.BI --minsl \0real
reject if the shorter/longer sequence length ratio is lower than
\fIreal\fR.
.TP
.BI --mintsize\~ "positive integer"
reject target sequences with an abundance lower than \fIinteger\fR.
.TP
.BI --mismatch\~ "integer"
score assigned to a mismatch (i.e. different nucleotides) in the
pairwise alignment. The default value is -4.
.TP
.BI --notmatched \0filename
write query sequences not matching database target sequences to
\fIfilename\fR, in fasta format.
.TP
.B --output_no_hits
write both matching and non-matching queries to --alnout, --blast6out,
and --userout output files (--uc and --uc_allhits output files always
feature non-matching queries). Non-matching queries are labelled "No
hits" in --alnout files.
.TP
.BI --qmask\~ "none|dust|soft"
mask simple repeats and low-complexity regions in query sequences
using the \fIdust\fR or the \fIsoft\fR algorithms, or do not mask
(\fInone\fR). Warning, when using \fIsoft\fR masking search commands
become case sensitive. The default is to mask using \fIdust\fR.
.TP
.BI --query_cov \0real
reject if the fraction of the query aligned to the target sequence is
lower than \fIreal\fR. The query coverage is computed as such: 100.0 *
(matches + mismatches) / query sequence length. Internal or terminal
gaps are not taken into account.
.TP
.B --rightjust
reject the target sequence if the alignment ends with gaps.
.TP
.BI --rowlen\~ "positive integer"
width of alignment lines in --alnout output. The default value is
64. Set to 0 to eliminate the wrapping.
.TP
.B --self
reject the alignment if the query and target labels are identical.
.TP
.B --selfid
reject the alignment if the query and target sequences are strictly
identical.
.TP
.B --sizeout
add abundance annotations to the output of the option --dbmatched
(using the pattern ";size=\fIinteger\fR").
.TP
.BI --strand\~ "plus|both"
when searching for similar sequences, check the \fIplus\fR strand only
(default) or check \fIboth\fR strands.
.TP
.BI --target_cov \0real
reject if the fraction of the target sequence aligned to the query
sequence is lower than \fIreal\fR. The target coverage is computed as
such: 100.0 * (matches + mismatches) / target sequence
length. Internal or terminal gaps are not taken into account.
.TP
.B --top_hits_only
output only the hits with the highest percentage of identity with the
query.
.TP
.BI --uc \0filename
output searching results in \fIfilename\fR using a uclust-like
format. See <http://www.drive5.com/usearch/manual/ucout.html> for a
description of the format. Output order may vary when using multiple
threads.
.TP
.B --uc_allhits
when using the --uc option, show all hits, not just the top hit for
each query. \fBTO BE TESTED\fR.
.TP
.BI --userfields \0string
when using --userout, select and order the fields written to the
output file. Fields are separated by "+" (e.g. query+target+id). See
the next section for a complete list of fields.
.TP
.BI --userout \0filename
write user-defined tab-separated output to \fIfilename\fR. Select the
fields with the option --userfields. Output order may vary when using
multiple threads. If --userfields is empty or not present,
\fIfilename\fR is empty.
.TP
.BI --vsearch_global \0filename
compare target sequences (--db) to the fasta-formatted query sequences
contained in \fIfilename\fR, using global pairwise alignment.
.TP
.BI --weak_id \0real
show hits with percentage of identity of at least \fIreal\fR, without
terminating the search. A normal search stops as soon as enough hits
are found (as defined 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, \fIreal\fR must be smaller than the value
indicated by --id.
.TP
.BI --wordlength\~ "positive integer"
length of words (i.e. \fIk\fR-mers) for database indexing. The range
of possible values goes from 3 to 15, but values near 8 are generally
recommended. Longer words may reduce the sensitivity for weak
similarities, but can increase accuracy. On the other hand, shorter
words may increase sensitivity, but can reduce accuracy. Computation
time will generally increase with shorter words and decrease with
longer words. Memory requirements for a part of the index increase
with a factor of 4 each time word length increases by one nucleotide,
and this generally becomes significant for long words (12 or
more). The default value is 8.
.RE
.PP
.\" ----------------------------------------------------------------------------
Fields accepted by the --userfields option:
.RS
.TP 9
.B 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 field if there is no alignment.
.TP
.B alnlen
Print the length of the query-target alignment (number of
columns). The field is set to 0 if there is no alignment.
.TP
.B bits
Bit score (not computed for nucleotidic alignments). Always set to 0.
.TP
.B caln
Compact representation of the pairwise alignment using the CIGAR
format (Compact Idiosyncratic Gapped Alignment Report): M (match), D
(deletion) and I (insertion). Empty field if there is no alignment.
.TP
.B evalue
E-value (not computed for nucleotidic alignments). Always set to -1.
.TP
.B exts
Number of columns containing a gap extension (zero or positive integer
value).
.TP
.B gaps
Number of columns containing a gap (zero or positive integer value).
.TP
.B id
Percentage of identity (real value ranging from 0.0 to 100.0). The
percentage identity is defined as 100 * (matching columns) /
(alignment length - terminal gaps).
.TP
.B id0
CD-HIT definition of the percentage of identity, using the shortest
sequence in the pairwise alignment as numerator (real value ranging
from 0.0 to 100.0).
.TP
.B id1
The percentage of identity (real value ranging from 0.0 to 100.0) is
defined as the edit distance: 100 * (matching columns) / (alignment
length).
.TP
.B id2
The percentage of identity (real value ranging from 0.0 to 100.0) is
defined as the edit distance, excluding terminal gaps. The field id2 is
an alias for the field id.
.TP
.B id3
Marine Biological Lab definition of the percentage of identity (real
value ranging from 0.0 to 100.0), counting each extended gap as a
single difference.
.TP
.B id4
BLAST definition of the percentage of identity (real value ranging
from 0.0 to 100.0), same as the field id2 for global pairwise
alignments.
.TP
.B ids
Number of matches in the alignment (zero or positive integer value).
.TP
.B mism
Number of mismatches in the alignment (zero or positive integer
value).
.TP
.B opens
Number of columns containing a gap opening (zero or positive integer
value).
.TP
.B 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).
.TP
.B pctgaps
Number of columns containing gaps expressed as a percentage of the
alignment length (real value ranging from 0.0 to 100.0).
.TP
.B pctpv
Percentage of positive columns. When working with nucleotidic
sequences, this is equivalent to the percentage of matches (real value
ranging from 0.0 to 100.0).
.TP
.B pv
Number of positive columns. When working with nucleotidic sequences,
this is equivalent to the number of matches (zero or positive integer
value).
.TP
.B qcov
Fraction of the query sequence that is aligned with the target
sequence (real value ranging from 0.0 to 100.0). The query coverage is
computed as such: 100.0 * (matches + mismatches) / query sequence
length. Internal or terminal gaps are not taken into account. The
field is set to 0.0 if there is no alignment.
.TP
.B qframe
Query frame (-3 to +3). That field only concerns coding sequences and
is not computed by \fBvsearch\fR. Always set to +0.
.TP
.B qhi
Last nucleotide of the query aligned with the target. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B ql
Query sequence length (positive integer value). The field is set to 0
if there is no alignment.
.TP
.B qlo
First nucleotide of the query aligned with the target. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B qrow
Print the sequence of the query segment as seen in the pairwise
alignment (i.e. with gap insertions if need be). Empty field if there
is no alignment.
.TP
.B qs
Query segment length. Always equal to query sequence length.
.\" The meaning of that field is not clear to us. 
.TP
.B qstrand
Query strand orientation (+ or - for nucleotidic sequences). Empty
field if there is no alignment.
.TP
.B query
Query label.
.TP
.B raw
Raw alignment score (negative, null or positive integer value). The
score is the sum of match rewards minus mismatch penalties, gap
openings and gap extensions. The field is set to 0 if there is no
alignment.
.TP
.B target
Target label. The field is set to "*" if there is no alignment.
.TP
.B tcov
Fraction of the target sequence that is aligned with the query
sequence (real value ranging from 0.0 to 100.0). The target coverage
is computed as such: 100.0 * (matches + mismatches) / target sequence
length. Internal or terminal gaps are not taken into account. The
field is set to 0.0 if there is no alignment.
.TP
.B tframe
Target frame (-3 to +3). That field only concerns coding sequences and
is not computed by \fBvsearch\fR. Always set to +0.
.TP
.B thi
Last nucleotide of the target aligned with the query. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B tl
Target sequence length (positive integer value). The field is set to 0
if there is no alignment.
.TP
.B tlo
First nucleotide of the target aligned with the query. Nucleotide
numbering starts from 1. The field is set to 0 if there is no
alignment.
.TP
.B trow
Print the sequence of the target segment as seen in the pairwise
alignment (i.e. with gap insertions if need be). Empty field if there
is no alignment.
.TP
.B ts
Target segment length. Always equal to target sequence length. The
field is set to 0 if there is no alignment.
.TP
.B tstrand
Target strand orientation (+ or - for nucleotidic sequences). Always
set to "+", so reverse strand matches have tstrand "+" and qstrand
"-". Empty field if there is no alignment.
.RE
.PP
.\" ============================================================================
.SH DELIBERATE CHANGES
If you are a usearch user, our objective is to make you feel at
home. That's why \fBvsearch\fR was designed to behave like usearch, to
some extend. Like any complex software, usearch is not free from
quirks and inconsistencies. We decided not to reproduce some of them,
and for complete transparency, to document here the deliberate changes
we made.
.PP
During a search with usearch, when using the options --blast6out and
--output_no_hits, for queries with no match the number of fields
reported is 13, where it should be 12. This is corrected in
\fBvsearch\fR.
.PP
The fields qlo, qhi, tlo, thi and raw of the --userfields option are
not informative in usearch. This is corrected in \fBvsearch\fR.
.PP
In usearch, when using the option --output_no_hits, queries that
receive no match are reported in blast6out file, but not in the
alignment output file. This is corrected in \fBvsearch\fR.
.PP
\fBvsearch\fR reintroduces with --iddef alternative pairwise identity
definitions that were removed from usearch.
.PP
\fBvsearch\fR extends the --topn option to sorting commands.
.PP
\fBvsearch\fR extends the --rowlen option to the chimera command
(--uchimealns option).
.PP
.\" ============================================================================
.SH NOVELTIES
\fBvsearch\fR introduces new options not present in usearch. They are
{'fraction_non_alphanumeric': 0.10677396254354343, 'fraction_numerical': 0.00921239485853694, 'mean_word_length': 3.6087151087990157, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5234825', 'n_tokens_mistral': 25036, 'n_tokens_neox': 23129, 'n_words': 11922}