vsearch

Versatile open-source tool for microbiome analysis

View on GitHub

NAME

vsearch --fastx_syncpairs — reorder paired reads so that mates appear in the same order in both files

SYNOPSIS

vsearch --fastx_syncpairs fastxfile --reverse fastxfile (--fastaout | --fastqout) filename [options]

DESCRIPTION

The vsearch command --fastx_syncpairs reorders paired-end reads so that the two mates of each pair appear at the same position in the forward and reverse files. Forward reads are given as the argument to --fastx_syncpairs, and the reverse reads are specified with --reverse. Both files must be in the same format, either fasta or fastq (not a mix). See vsearch-fasta(5) and vsearch-fastq(5) for more information on these formats.

Two reads form a pair when they share the same matching key. The key is the read header, truncated at the first whitespace, with a trailing /1 or /2 mate marker removed (see --read_separators). For example, the Casava 1.8+ headers instrument:42 1:N:0:7 and instrument:42 2:N:0:7 share the key instrument:42, and the older headers instrument:42/1 and instrument:42/2 share the key instrument:42.

The reverse file is read once and kept in memory; the forward file is then read entry by entry, and the matching reverse read is retrieved. Synchronized pairs are written in the order of the forward file: the forward reads to --fastaout and/or --fastqout, and their mates to --fastaout_rev and/or --fastqout_rev. Neither input file needs to be seekable, so both may be compressed or read from a pipe.

A read whose key appears in only one of the two files is called an orphan. By default orphans are discarded. They can instead be written out with --fastaout_orphans and --fastqout_orphans (forward orphans, in forward-file order) and --fastaout_orphans_rev and --fastqout_orphans_rev (reverse orphans, in reverse-file order).

Read labels are expected to be unique within each file. A duplicated label is reported as an error when it makes the pairing ambiguous: always for the reverse file, and for the forward file when two reads claim the same reverse mate.

Note that reads are only reordered: they are not joined, merged, or modified. To join non-overlapping paired-end reads, see vsearch-fastq_join(1). To merge overlapping paired-end reads, see vsearch-fastq_mergepairs(1).

OPTIONS

mandatory options

--reverse filename
Specify the fasta or fastq file containing the reverse reads. The format must match that of the forward reads.

At least one output file must also be specified.

core options

--fastaout filename
Write the synchronized forward reads to filename, in fasta format (see vsearch-fasta(5)). Quality scores are not written.

--fastaout_rev filename
Write the synchronized reverse reads to filename, in fasta format.

--fastqout filename
Write the synchronized forward reads to filename, in fastq format (see vsearch-fastq(5)). The input must be in fastq format.

--fastqout_rev filename
Write the synchronized reverse reads to filename, in fastq format. The input must be in fastq format.

--fastaout_orphans filename
Write the forward reads that have no reverse mate to filename, in fasta format.

--fastaout_orphans_rev filename
Write the reverse reads that have no forward mate to filename, in fasta format.

--fastqout_orphans filename
Write the forward reads that have no reverse mate to filename, in fastq format. The input must be in fastq format.

--fastqout_orphans_rev filename
Write the reverse reads that have no forward mate to filename, in fastq format. The input must be in fastq format.

--read_separators string
Specify the set of characters that, when immediately followed by the mate number 1 or 2 at the end of the matching key, mark a trailing mate marker to be stripped. The default is /, which removes the /1 and /2 markers of older Illumina headers. A whitespace always ends the matching key, regardless of this option, so Casava 1.8+ headers are handled without any configuration.

secondary options

--bzip2_decompress
Specify that the input pipe is streaming data compressed using Huffman coding. See bzip2(1) for more details. This option is not needed when reading from a regular file compressed with bzip2.

--fasta_width positive integer
Set the maximal width of sequences when writing fasta files. Longer sequences are folded and written on several lines. Default width is 80 nucleotides. Set to zero (0) to suppress folding.

--gzip_decompress
Specify that the input pipe is streaming data compressed using Lempel-Ziv coding. See gzip(1) for more details. This option is not needed when reading from a regular file compressed with gzip.

--log filename
Write messages to filename. Messages include program version, start and finish times, elapsed time, amount of memory available, maximum amount of memory consumed, number of cores and command line options, and if need be, command-specific informational messages, warnings, and errors.

--no_progress
Suppress the gradually increasing progress indicator normally written to the standard error stderr(3).

--quiet
Suppress messages to the standard output stdout(3) and standard error stderr(3), except for warnings and error messages.

ignored options

Reads are reordered without inspecting their quality scores, so the following quality-related options are accepted (for instance in a pipeline) but have no effect.

--fastq_ascii 33|64
Option is ignored and has no effect.

--fastq_qmax positive integer
Option is ignored and has no effect.

--fastq_qmin positive integer
Option is ignored and has no effect.

--threads positive non-null integer
Command is not multithreaded, option has no effect.

EXAMPLES

Reorder the reads of R1.fastq and R2.fastq so that mates line up, writing the synchronized reads to R1_sorted.fastq and R2_sorted.fastq:

vsearch \
    --fastx_syncpairs R1.fastq \
    --reverse R2.fastq \
    --fastqout R1_sorted.fastq \
    --fastqout_rev R2_sorted.fastq

Same as above, but also keep the unpaired reads in separate files:

vsearch \
    --fastx_syncpairs R1.fastq \
    --reverse R2.fastq \
    --fastqout R1_sorted.fastq \
    --fastqout_rev R2_sorted.fastq \
    --fastqout_orphans R1_orphans.fastq \
    --fastqout_orphans_rev R2_orphans.fastq

Synchronize reads whose headers carry the mate number after an underscore (for example readid_1 and readid_2):

vsearch \
    --fastx_syncpairs R1.fastq \
    --reverse R2.fastq \
    --read_separators _ \
    --fastqout R1_sorted.fastq \
    --fastqout_rev R2_sorted.fastq

SEE ALSO

vsearch-fastq_join(1) for joining non-overlapping paired-end reads, vsearch-fastq_mergepairs(1) for merging overlapping paired-end reads. vsearch-fasta(5), vsearch-fastq(5)

CITATION

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

REPORTING BUGS

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

AVAILABILITY

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

COPYRIGHT

Copyright (C) 2014-2026, Torbjørn Rognes, Frédéric Mahé and Tomás Flouri

All rights reserved.

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

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

GNU General Public License version 3

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

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

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

The BSD 2-Clause License

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

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following 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 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ACKNOWLEDGMENTS

We would like to thank the authors of the following projects for making their source code available: