General options¶

-h, --help

display this help and exit successfully.

-t, --threads positive integer

number of computation threads to use. Values between 1 and 256 are accepted, but we recommend to use a number of threads lesser or equal to the number of available CPU cores. Default number of threads is 1.

-v, --version

output version information and exit successfully.

--

delimit the option list. Later arguments, if any, are treated as operands even if they begin with "-". For example, "swarm -- -file.fasta" reads from the file "-file.fasta".

Clustering options¶

-d, --differences zero or positive integer

maximum number of differences allowed between two amplicons, meaning that two amplicons will be grouped if they have integer (or less) differences. This is swarm's most important parameter. The number of differences is calculated as the number of mismatches (substitutions, insertions or deletions) between the two amplicons once the optimal pairwise global alignment has been found (see "pairwise alignment advanced options" to influence that step). Any integer between 0 and 256 can be used, but high d values will decrease the taxonomical resolution of swarm results. Commonly used d values are 1, 2 or 3, rarely higher. When using d = 0, swarm will output results corresponding to a strict dereplication of the dataset, i.e. merging identical amplicons. Warning, whatever the d value, swarm requires fasta entries to present abundance values. Default number of differences d is 1.

-n, --no-otu-breaking

deactivate the built-in OTU refinement (not recommended). Amplicon abundance values are used to identify transitions among in-contact OTUs and to separate them, yielding higher-resolution clustering results. That option prevents that separation, and in practice, allows the creation of a link between amplicons A and B, even if the abundance of B is higher than the abundance of A.

Fastidious options¶

-b, --boundary positive integer

when using the option --fastidious (-f), define the minimum mass of a large OTU. By default, an OTU with a mass of 3 or more is considered large. Conversely, an OTU is small if it has a mass of less than 3, meaning that it is composed of either one amplicon of abundance 2, or two amplicons of abundance 1. Any positive value greater than 1 can be specified. Using higher boundary values will speed up the second pass, but also reduce the taxonomical resolution of swarm results. Default mass of a large OTU is 3.

-c, --ceiling positive integer

when using the option --fastidious (-f), define swarm's maximum memory footprint (in megabytes). swarm will adjust the --bloom-bits (-y) value of the Bloom filter to fit within the specified amount of memory.

-f, --fastidious

when working with d = 1, perform a second clustering pass to reduce the number of small OTUs (recommended option). During the first clustering pass, an intermediate amplicon can be missing for purely stochastic reasons, interrupting the aggregation process. The fastidious option will create virtual amplicons, allowing to graft small OTUs upon bigger ones. By default, an OTU is small if it has a mass of 2 or less (see the --boundary option to modify that value). To speed things up, swarm uses a Bloom filter to store intermediate results. Warning, the second clustering pass can be 2 to 3 times slower than the first pass and requires much more memory to store the virtual amplicons in Bloom filters. See the options --bloom-bits (-y) or --ceiling (-c) to control the memory footprint of the Bloom filter. The fastidious option modifies clustering results: the output files produced by the options --log (-l), --output-file (-o), --mothur (-r), --uclust-file, and --seeds (-w) are updated to reflect these modifications; the file --statistics-file (-s) is partially updated (columns 6 and 7 are not updated); the output file --internal-structure (-i) is not updated.

-y, --bloom-bits positive integer

when using the option --fastidious (-f), define the size (in bits) of each entry in the Bloom filter. That option allows to balance the efficiency (i.e. speed) and the memory footprint of the Bloom filter. Large values will make the Bloom filter more efficient but will require more memory. Any value between 2 and 64 can be used. Default value is 16. See the --ceiling (-c) option for an alternative way to control the memory footprint.

Input/output options¶

-a, --append-abundance positive integer

set abundance value to use when some or all amplicons in the input file lack abundance values. Warning, it is not recommended to use swarm on datasets where abundance values are all identical. We provide that option as a courtesy to advanced users, please use it carefully. swarm exits with an error message if abundance values are missing and if this option is not used.

-i, --internal-structure filename

output all pairs of nearly-identical amplicons to filename using a five-columns tab-delimited format:

-l, --log filename

output all messages to filename instead of standard error, with the exception of error messages of course. That option is useful in situations where writing to standard error is problematic (for example, with certain job schedulers).

-o, --output-file filename

output clustering results to filename. Results consist of a list of OTUs, one OTU per line. An OTU is a list of amplicon identifiers separated by spaces. That output format can be modified by the option --mothur (-r). Default is to write to standard output.

-r, --mothur

output clustering results in a format compatible with Mothur. That option modifies swarm's default output format.

-s, --statistics-file filename

output statistics to filename. The file is a tab-separated table with one OTU per row and seven columns of information:

-u, --uclust-file filename

output clustering results in uclust-like file format to the specified file. That option does not modify swarm's default output format.

-w, --seeds filename

output OTU representatives to filename in fasta format. The abundance value of each OTU representative is the sum of the abundances of all the amplicons in the OTU.

-z, --usearch-abundance

accept amplicon abundance values in usearch/vsearch's style (>label;size=integer[;]). That option influences the abundance annotation style used in output files.

Pairwise alignment advanced options¶

As swarm focuses on close relationships (e.g., d = 2 or 3), clustering results are resilient to pairwise alignment model parameters modifications. When clustering using a higher d value, modifying model parameters has a stronger impact.