.TH abyss-pe "1" "2015-May" "abyss-pe (ABySS) 2.3.1" "User Commands"
.SH NAME
abyss-pe - assemble reads into contigs
.SH SYNOPSIS
.B abyss-pe
[\fIOPTION\fR]...  [\fIPARAMETER\fR=\fIVALUE\fR]...  [\fIMAKE_TARGET\fR]...
.SH DESCRIPTION
Assemble the reads of the input files into contigs. The reads may be
in FASTA, FASTQ, qseq, export, SRA, SAM or BAM format and may be
compressed with gz, bz2 or xz and may be tarred.

abyss-pe is a Makefile script. Any options of make may also be used
with abyss-pe.

.SS "Parameters of abyss-pe"
.TP
\fBname\fR, \fBJOB_NAME\fR
The name of this assembly. The resulting scaffolds will be stored in
${name}-scaffolds.fa.
.TP
.B in
input files. Use this variable when assembling data from a single
library.
.TP
.B lib
a quoted list of whitespace-separated paired-end library names. Use
this variable when assembling data from multiple paired-end libraries.
For each library name in lib, the user must define a variable on
the command line with the same name, which indicates the read files for
that library. See \fBEXAMPLES\fR below for a concrete example of usage.
.TP
.B pe
list of paired-end libraries that will be used only for merging
unitigs into contigs and will not contribute toward the consensus
sequence.
.TP
.B mp
list of mate-pair libraries that will be used for scaffolding.
Mate-pair libraries do not contribute toward the consensus sequence.
.TP
.B long
list of long sequence libraries that will be used for rescaffolding.
long sequence libraries do not contribute toward the consensus sequence.
.TP
.B se
files containing single-end reads
.TP
.B a
maximum number of branches of a bubble [2]
.TP
.B b
maximum length of a bubble (bp) [""]
.br
abyss-pe has two bubble popping stages. The default limits are 3*k bp
for ABYSS and 10000 bp for PopBubbles.
.TP
.B c
minimum mean k-mer coverage of a unitig [sqrt(median)]
.TP
.B d
allowable error of a distance estimate (bp) [6]
.TP
.B e
minimum erosion k-mer coverage [round(sqrt(median))]
.TP
.B E
minimum erosion k-mer coverage per strand [1 if sqrt(median) > 2 else 0]
.TP
.B j
number of threads [2]
.TP
.B k
size of a k-mer (when K is not set) or the span of a k-mer pair (when K is set)
.TP
.B K
size of a single k-mer in a k-mer pair (bp)
.TP
.B l
minimum alignment length of a read (bp) [40]
.TP
.B m
minimum overlap of two unitigs (bp) [k-1]
.TP
.B n
minimum number of pairs required for building contigs [10]
.TP
.B N
minimum number of pairs required for building scaffolds [n]
.TP
.B p
minimum sequence identity of a bubble [0.9]
.TP
.B q
minimum base quality when trimming [3]
.br
Trim bases from the ends of reads whose quality is less q.
.TP
.B Q
minimum base quality [0]
.br
Mask all bases of reads whose quality is less than Q as `N'.
.TP
.B s
minimum unitig size required for building contigs (bp) [1000]
.br
The seed length should be at least twice the value of k. If more
sequence is assembled than the expected genome size, try increasing s.
.TP
.B S
minimum contig size required for building scaffolds (bp) [1000-10000]
.TP
.B SS
SS=--SS to assemble in strand-specific mode
.br
Requires that all libraries are strand-specific RNA-Seq libraries.
Assumes that the first read in a read pair is reversed WRT the
transcripts sequenced.
.TP
.B t
maximum length of blunt contigs to trim [k]
.TP
.B v
v=-v to enable verbose logging
.TP
\fBnp\fR, \fBNSLOTS\fR
the number of processes of an MPI assembly
.TP
.B mpirun
the path to mpirun
.TP
.B aligner
The program to use to align the reads to the contigs [map].
.br
Permitted values are: map, kaligner, bwa, bwasw, bowtie, bowtie2, dida.
See the \fBDIDA\fR section below for further info on the dida option.
.TP
.B cs
convert colour-space contigs to nucleotide contigs following assembly
.SS "Options of make"
.TP
\fB-n\fR, \fB--dry-run\fR
Print the commands that would be executed, but do not execute them.
.SS "Make targets for abyss-pe"
.TP
.B default
Equivalent to `scaffolds scaffolds-dot stats'.
.TP
.B unitigs
Assemble unitigs.
.TP
.B unitigs-dot
Output the unitig overlap graph.
.TP
.B pe-sam
Map paired-end reads to the unitigs and output a SAM file. SAM file
will only contain reads mapping to different contigs, and the read
ID, sequence and quality strings will be replaced with '*'
characters.
.TP
.B pe-bam
Map paired-end reads to the unitigs and output a BAM file. BAM file
will only contain reads mapping to different contigs, and the read
ID, sequence and quality strings will be replaced with '*'
characters.
.TP
.B pe-index
Generate an index of the unitigs used by abyss-map.
.TP
.B contigs
Assemble contigs.
.TP
.B contigs-dot
Output the contig overlap graph.
.TP
.B mp-sam
Map mate-pair reads to the contigs and output a SAM file. SAM file
will only contain reads mapping to different contigs, and the read
ID, sequence and quality strings will be replaced with '*'
characters.
.TP
.B mp-bam
Map mate-pair reads to the contigs and output a BAM file. BAM file
will only contain reads mapping to different contigs, and the read
ID, sequence and quality strings will be replaced with '*'
characters.
.TP
.B mp-index
Generate an index of the contigs used by abyss-map.
.TP
.B scaffolds
Assemble scaffolds.
.TP
.B scaffolds-dot
Output the scaffold overlap graph.
.TP
.B scaftigs
Break scaffolds and generate AGP file.
.TP
.B long-scaffs
Rescaffold using RNA-Seq assembled contigs.
.TP
.B long-scaffs-dot
Output the RNA scaffold overlap graph.
.TP
.B stats
Display assembly contiguity statistics.
.TP
.B clean
Remove intermediate files.
.TP
.B version
Display the version of abyss-pe.
.TP
.B versions
Display the versions of all programs used by abyss-pe.
.TP
.B help
Display a helpful message.

.SH "DIDA"
ABySS supports the use of DIDA (Distributed Indexing Dispatched
Alignment), an MPI-based alignment framework for computing sequence
alignments across multiple machines. To use DIDA with ABySS, first
download and install DIDA from http://www.bcgsc.ca/platform/bioinfo/software/dida,
then specify `dida` as the value of the \fBaligner\fR parameter to
\fBabyss-pe\fR.

.SS "DIDA-related abyss-pe parameters"
.TP
.B DIDA_MPIRUN
The `mpirun` command used to run DIDA jobs.
.TP
.B DIDA_RUN_OPTIONS
Runtime options such as number of threads per MPI rank
and values for environment variables (e.g. PATH, LD_LIBRARY_PATH).
Run `abyss-dida --help` for a list of available options.
.TP
.B DIDA_OPTIONS
Options that are passed directly to the DIDA binary. For example,
this can be used to control the minimum alignment length threshold.
Run `dida-wrapper --help` for a list of available options.

.SS "MPI COMPATIBILITY"
Due to its use of multi-threading, DIDA has known deadlocking issues
with OpenMPI.  Using the MPICH MPI library is strongly recommended
when running assemblies with DIDA. Testing was done with MPICH 3.1.3,
compiled with --enable-threads=funneled.

.SS "EXAMPLE"
The recommended runtime configuration for DIDA is 1 MPI rank per
machine and 1 thread per CPU core. For example, to run an
assembly across 3 cluster nodes with 12 cores each, do:

	abyss-pe k=64 name=ecoli in='reads1.fa reads2.fa' aligner=dida DIDA_RUN_OPTIONS='-j12' DIDA_MPIRUN='mpirun -np 3 -ppn 1 -bind-to board'

This example uses the MPICH command line options for `mpirun`.
Here, `-np 3` indicates the number of MPI ranks, `-ppn 1` indicates
the number of MPI ranks per "node", and `-bind-to board` defines
a "node" to be a motherboard (i.e. a full machine).

.SH "ENVIRONMENT VARIABLES"
Any parameter that may be specified on the command line may also be
specified in an environment variable.
.TP
.B PATH
must contain the directory where the ABySS executables are installed.
Use `abyss-pe versions` to check that PATH is configured correctly.
.TP
.B TMPDIR
specifies a directory to use for temporary files
.SS "Scheduler integration"
ABySS integrates well with cluster job schedulers, such as:
 * SGE (Sun Grid Engine)
 * Portable Batch System (PBS)
 * Load Sharing Facility (LSF)
 * IBM LoadLeveler

The SGE environment variables JOB_NAME, SGE_TASK_ID and NSLOTS may be
used to specify the parameters name, k and np, respectively, and
similarly for other schedulers.
.SH EXAMPLES
.SS "One paired-end library"
 abyss-pe k=64 name=ecoli in='reads1.fa reads2.fa'
.SS "Multiple paired-end libraries"
 abyss-pe k=64 name=ecoli lib='lib1 lib2' \\
.br
	lib1='lib1_1.fa lib1_2.fa' lib2='lib2_1.fa lib2_2.fa' \\
.br
	se='se1.fa se2.fa'
.SS "Paired-end and mate-pair libraries
 abyss-pe k=64 name=ecoli lib='pe1 pe2' mp='mp1 mp2' \\
.br
	pe1='pe1_1.fa pe1_2.fa' pe2='pe2_1.fa pe2_2.fa' \\
.br
	mp1='mp1_1.fa mp1_2.fa' mp2='mp2_1.fa mp2_2.fa' \\
.br
	se='se1.fa se2.fa'
.SS "Including RNA-Seq assemblies
 abyss-pe k=64 name=ecoli lib=pe1 mp=mp1 long=long1 \\
.br
	pe1='pe1_1.fa pe1_2.fa' mp1='mp1_1.fa mp1_2.fa' \\
.br
	long1=long1.fa
.SS MPI
 abyss-pe np=8 k=64 name=ecoli in='reads1.fa reads2.fa'
.SS SGE
 qsub -N ecoli -t 64 -pe openmpi 8 \\
.br
	abyss-pe n=10 in='reads1.fa reads2.fa'
.SH "SEE ALSO"
make(1), ABYSS(1)
.SH AUTHOR
Written by Shaun Jackman.
.SH "REPORTING BUGS"
Report bugs to <abyss-users@googlegroups.com>.
.SH COPYRIGHT
Copyright 2015 Canada's Michael Smith Genome Sciences Centre