% TODO: add new options in Ray 1.6.2 
% ./Ray -help lists options

\documentclass{article}
\usepackage{hyperref}
\usepackage{html}

\usepackage{graphicx}
\usepackage{fullpage}
\usepackage[utf8]{inputenc}


\begin{document}


\author{Sébastien Boisvert}
\title{Instruction Manual for the Ray \emph{de novo} genome assembler software}
\maketitle


\vspace{2cm}
Ray version 1.6.2-devel

\vspace{2cm}

Website: \url{http://denovoassembler.sf.net}

\vspace{0.4cm}

Git source tree: \url{http://github.com/sebhtml/ray}

\vspace{2cm}

Reference to cite: 
\vspace{2cm}

\noindent
Sébastien Boisvert, François Laviolette \& Jacques Corbeil.\\
Ray: simultaneous assembly of reads from a mix of high-throughput sequencing technologies.\\
\emph{Journal of Computational Biology} (Mary Ann Liebert, Inc. publishers, New York, U.S.A.).\\
November 2010, Volume 17, Issue 11, Pages 1519-1533.\\
doi:10.1089/cmb.2009.0238\\
\url{http://dx.doi.org/doi:10.1089/cmb.2009.0238}


\newpage
\tableofcontents
\newpage

\section{Abstract}

Ray is documented in the manual (InstructionManual.tex; available
online and in Portable Document Format), 
on
\url{http://github.com/sebhtml/ray}
 (with the README.md), in the 
C++ code using Doxygen and in the journal paper as well.
Enjoy the manual.

\section{Installation}

To install Ray, you need a C++ compiler (standard 1998), make and a message-passing-interface (MPI) implementation compliant
with the MPI standard 2.2.

The software below are readily (and freely) available in most GNU/Linux distributions (I use Ubuntu, CentOS, and Fedora); 
see Table~\ref{software}).


\begin{table}[h]
\caption{Suggested software}\label{software}
\begin{tabular}{ll}
\hline
Software & Name \\
\hline
C++ compiler & GNU g++ \\
MPI implementation & Open-MPI \\
make & GNU make \\
\hline
\end{tabular}
\end{table}

There are some compilation options that can be changed. These are listed below in Table~\ref{flags}.
They can be changed in the Makefile or provided on the command line.

\begin{table}[h]
\caption{Compilation options}\label{flags}
\begin{tabular}{lll}
\hline
Option & Value & Description \\
\hline
PREFIX & path & where 'make install' will install Ray \\
MAXKMERLENGTH & integer & maximum k-mer length \\
HAVE\_LIBZ & y/n & enable support for .gz files \\
HAVE\_LIBBZ2 & y/n& enable support for .bz2 files \\
FORCE\_PACKING & y/n& enable packing of structures and classes\\
ASSERT & y/n& enable assertions in the code \\
HAVE\_CLOCK\_GETTIME & y/n& get time at a nanosecond precision -- real-time \\
VIRTUAL\_SEQUENCER & y/n& will generate a program called VirtualNextGenSequencer \\
INTEL\_COMPILER & y/n& use mpiicpc \\
\hline
\end{tabular}
\end{table}

To compile Ray, enter these commands.

\begin{verbatim}
make PREFIX=build
make install
ls build/Ray
\end{verbatim}


You need to have mpic++ in your path, otherwise edit the Makefile to change MPICXX.
You may also provide MPICXX on the command line.

\begin{verbatim}
make PREFIX=build MPICXX=/software/openmpi-1.4.3/bin/mpic++
make install
ls build/Ray
\end{verbatim}

You can also provide all compilation options as follows.

\begin{verbatim}
make  PREFIX=build MPICXX=/software/openmpi-1.4.3/bin/mpic++ \
MAXKMERLENGTH=64 HAVE_LIBZ=n HAVE_LIBBZ2=n \
HAVE_CLOCK_GETTIME=n INTEL_COMPILER=n ASSERT=n FORCE_PACKING=y
#wait 
make install
\end{verbatim}


No configure script exists because it is too much of a mess to maintain.
Furthermore, autoconf and automake just don't work on a Lustre filesystem (used on most
super computers) when the network file system disallows file locking.
The Makefile of Ray utilises the Linux kernel syntax (obj-y += object.o).

\subsection{Use longer k-mers}

\begin{verbatim}
	make PREFIX=Ray-Large-k-mers MAXKMERLENGTH=64
	# wait
	make install
	mpirun -np 512 Ray-Large-k-mers/Ray -k 63 -p lib1_1.fastq lib1_2.fastq \
	-p lib2_1.fastq lib2_2.fastq -o DeadlyBug,Assembler=Ray,K=63
	# wait
	ls DeadlyBug,Assembler=Ray,K=63.Scaffolds.fasta
\end{verbatim}

Note: longer k-mers utilise more memory.

\section{General guide lines for launching Ray}

\subsection{Communication}

Ray is a high-performance peer-to-peer software. It runs on numerous computers simultaneously.
Ray instances are called MPI ranks. The MPI ranks are usually mapped to processes and they communicate using available bit transfer layers.
Bit transfer layers are (in Open-MPI):

\begin{itemize}
\item \textbf{Direct memory} copy is used when an MPI rank communicates with itself;
\item \textbf{Shared memory} is used when an MPI rank communicates with another MPI rank located on the same computer;
\item \textbf{TCP/IP} is used when an MPI rank communicates with another MPI rank located on a different computer.
\end{itemize}

If you use a high-performance network:

\begin{itemize}
\item \textbf{Infiniband} is used when an MPI rank communicates with another MPI rank located on a different computer.
\end{itemize}

\subsection{Scheduling a MPI job}

One thing that should be avoided is sharing cluster nodes between users for any given MPI job.
Otherwise, your MPI job may fail simply because other users sharing your job nodes may make one of your job nodes crash (load factor is too high or 
memory usage is not respectful).

If you use Oracle Grid Engine (previously known as Sun Grid Engine), you should submit your MPI jobs to a queue with an allocation rule (allocation\_rule) equal to
the number of cores per node. This simple configuration will ensure that no cluster node is shared between users for any MPI job.

\section{Inputs}

For a most up-to-date list of Ray parameters, run:

\begin{verbatim}
Ray -help|less
\end{verbatim}

The input files for Ray contain sequences. The files must be formatted in one of the supported formats.
These formats are listed in Table~\ref{formats}. Note that the file extension is obligatory and Ray uses it
to select the file format.

\begin{table}[h]
\caption{File formats compatible with the Ray \emph{de novo} genome assembler software}\label{formats}
\begin{tabular}{ll}
\hline
Format & Mandatory extension \\
\hline
Fasta format & .fasta\\
Fasta format, compressed with GNU zip (gzip) & .fasta.gz \\
Fasta format, compressed with bzip2 & .fasta.bz2 \\
Fastq format & .fastq\\
Fastq format, compressed with GNU zip (gzip) & .fastq.gz \\
Fastq format, compressed with bzip2 & .fastq.bz2 \\
Standard flowgram format & .sff \\
Color-space & .csfasta \\
\hline
\end{tabular}
\end{table}

Keep in mind that these formats are *just* containers.
To use 454 mate-pairs in an SFF file, you must extract them
and provide Ray with the 2 resulting fastq files.


Ray assembles color-space reads and generate color-space contigs.
Files must have the .csfasta extension. Nucleotide reads can not be mixed
with color-space reads. This is an experimental feature.

\subsection{Unknown nucleotides (not A, T, C, G)}

Unknown nucleotides at the ends of reads are removed and unknown nucleotides inside reads
are converted to A.

\section{Parameters}

Ray assembles reads (paired or not) to produce an assembly.
Paired reads must be on opposite strands (forward \& reverse or reverse \& forward).

For a paired library, paired reads can be provided as two files (with -p) or as one file containing interleaved
sequences (with -i).
With both, the average outer distance and the standard deviation can be provided by the user. Otherwise, these values are
computed by Ray. Ray may fail to compute and average outer distance when the later is too high.
In that case, provide the value.
The maximum  number of paired libraries allowed by Ray is 499.

\subsection{      
 -debug-bubbles
}
              Debugs bubble code.

\subsection{
-write-kmers
}
Ray will write k-mers to PREFIX.kmers.txt.

\subsection{      
       -debug-seeds
}
              Debugs seed code.

\subsection{      
       -show-memory-usage (only available in GNU/Linux)
}
              Shows memory usage. Data is fetched from /proc on GNU/Linux

\subsection{      
       -show-ending-context
}
              Shows the ending context of each extension.

\subsection{      
       -run-profiler
}
              Runs the profiler as the code runs. Needs a real-time POSIX system (HAVE\_CLOCK\_GETTIME = y)

\subsection{-amos}

Generates an AMOS file containing read locations on contigs. This file can be opened with AMOS Hawkeye, Tablet and other assembly browser
software. The generated file is PREFIX.AMOS.afg.



\subsection{
-help
}
Shows options available.


\subsection{-minimumCoverage minimumCoverage}

Sets manually the minimum coverage. 
If not provided, it is computed by Ray automatically.

\subsection{-peakCoverage peakCoverage}

Sets manually the peak coverage.
If not provided, it is computed by Ray automatically.


\subsection{-repeatCoverage repeatCoverage}

Sets manually the repeat coverage.
If not provided, it is computed by Ray automatically.

\subsection{$k$-mer length with -k}

Ray builds a distributed catalog of all occuring $k$-mers in the reads and their reverse-complement. $k$ must be greater or equal to 15 and lower or equal to MAXKMERLENGTH (provided at compilation). The $k$-mer length must be an odd number.

\subsection{Output prefix with -o}

Output files are named according to the prefix provided by the option -o.

\subsection{Single-end reads with -s}

\begin{verbatim}
-s <sequencesFile>
\end{verbatim}

\subsection{Paired-end reads and mate-pair reads with -p}

Average outer distance and standard deviation are computed by Ray if omitted.

\begin{verbatim}
-p <leftSequencesFile> <rightSequencesFile>  

OR

-p <leftSequencesFile> <rightSequencesFile>  <averageFragmentLength> <standardDeviation> 
\end{verbatim}

Example for paired-end reads (the ends of DNA fragments):

\begin{verbatim}
-p lib1_1.fastq lib1_2.fastq -p lib2_1.fastq lib2_2.fastq
\end{verbatim}

Example for mate-pair reads:

\begin{verbatim}
-p s_20000_1.fastq s_20000_2.fastq
\end{verbatim}

Example with metagenomic data and user-provided average outer distance and standard deviation

\begin{verbatim}
-p s_1.fastq s_2.fastq 300 30
\end{verbatim}

\subsection{Paired-end reads and mate-pair reads with -i (interleaved sequences)}


Average outer distance and standard deviation are computed by Ray if omitted.

\begin{verbatim}
-i <sequencesFile>

OR

-i <sequencesFile>  <averageFragmentLength> <standardDeviation> 
\end{verbatim}

In the interleaved file (example is for a fasta file):

\begin{verbatim}
>200_1_1234/1
ATCGATCGATCGACTCAGACACGTACG
>200_1_1234/2
ACTGACGACGTACGACGTCATGCAACT
...
\end{verbatim}



\section{Outputs}

Outputted files are listed in Table~\ref{outputs}.

\begin{table}[h]
\caption{Files generated by the Ray \emph{de novo} genome assembler software}\label{outputs}
\begin{tabular}{ll}
\hline
File& Description\\
\hline
PREFIX.Contigs.fasta & Contiguous sequences in FASTA format\\
PREFIX.ContigLengths.txt & The lengths of contiguous sequences\\
PREFIX.Scaffolds.fasta & The scaffold sequences in FASTA format \\
PREFIX.ScaffoldComponents.txt & The components of each scaffold\\
PREFIX.ScaffoldLengths.txt & The length of each scaffold \\
PREFIX.ScaffoldLinks.txt & Scaffold links \\
PREFIX.RayCommand.txt & The exact same command provided \\
PREFIX.RayVersion.txt & The version of Ray\\
PREFIX.CoverageDistribution.txt & The distribution of coverage values \\
PREFIX.CoverageDistributionAnalysis.txt & Analysis of the coverage distribution \\
PREFIX.LibraryStatistics.txt & Number of reads in each file \\
 & and estimation of outer distances for paired reads \\
PREFIX.SeedLengthDistribution.txt & The distribution of seed lengths \\
PREFIX.OutputNumbers.txt & Overall numbers for the assembly\\
PREFIX.AMOS.afg & Assembly representation in AMOS format (-amos) \\
PREFIX.kmers.txt & K-mer graph (-write-kmers) \\
PREFIX.degreeDistribution.txt & Distribution of ingoing and outgoing degrees \\
PREFIX.MessagePassingInterface.txt & Contains the number of messages sent \\
PREFIX.NetworkTest.txt & Contains the result of the network test \\
\hline
\end{tabular}
\end{table}

The file PREFIX.CoverageDistributionAnalysis.txt contains an estimation of the genome length.


\newpage

\section{Validation of assemblies}

In the scripts/ directory, the script ValidateGenomeAssembly.sh can validate an assembly against the corresponding
reference. To run it, you will need MUMmer and some other programs from AMOS (Google them).


\section{Examples}

Examples are available in system-tests/tests

\subsection{Bacterial genome with paired-end and mate-pair short reads}

The command:

\begin{verbatim}
mpirun -np 32 ./build-99/Ray \
-p /home/boiseb01/nuccore/Large-Ecoli/200_1.fastq \
   /home/boiseb01/nuccore/Large-Ecoli/200_2.fastq \
-p /home/boiseb01/nuccore/Large-Ecoli/1000_1.fastq \
   /home/boiseb01/nuccore/Large-Ecoli/1000_2.fastq \
-p /home/boiseb01/nuccore/Large-Ecoli/4000_1.fastq \
   /home/boiseb01/nuccore/Large-Ecoli/4000_2.fastq \
-p /home/boiseb01/nuccore/Large-Ecoli/10000_1.fastq \
   /home/boiseb01/nuccore/Large-Ecoli/10000_2.fastq \
-o BacterialGenome | tee RayLog
\end{verbatim}

\section{Virtual sequencer \& simulations}

The Ray package includes a simulator for paired reads.
To build it, you must provide VIRTUAL\_SEQUENCER=y.
Note that you need boost to compile this tool.

To compile it, type these commands:

\begin{verbatim}

make PREFIX=build VIRTUAL_SEQUENCER=y
# wait
make install
./build/VirtualNextGenSequencer 
\end{verbatim}

To use it:

\begin{verbatim}
N=6000000
readLength=50
errorRate=0.005
ref=~/nuccore/Ecoli-k12-mg1655.fasta

./build/VirtualNextGenSequencer $ref $errorRate 200 20 $N $readLength L1_1.fasta L1_2.fasta
\end{verbatim}

You can then assemble these reads with Ray.

\begin{verbatim}

mpirun -np 64 ./build/Ray -k 31 -p L1_1.fasta L2_2.fasta -o DeadlyBug

\end{verbatim}

\section{Exploring the source code}

The source code of Ray (and all the changes since its inception) is on github.
github is a place where people code socially.
There, you can browse the source code easily.

\url{http://github.com/sebhtml/ray}

Feel free to fork my tree and send me a pull request if you have some
interesting changes to the code base.

The Ray source code is documented with Doxygen tags.

The command below generates code documentation.

\begin{verbatim}
cd code
doxygen DoxygenConfigurationFile
\end{verbatim}

To browse it, use this command:

\begin{verbatim}
firefox DoxygenDocumentation/html/index.html
\end{verbatim}

\section{Submitting patches}

See code/Submit-a-patch.txt

\section{Reporting bugs \& crashes}

If Ray crashed, you should send a bug report.
However, be sure that you can reproduce the bug when Ray is compiled with
ASSERT=y. Assertions are useful to catch those pesky bugs.

\begin{verbatim}
On the mailing list:

denovoassembler-users # lists DOT sourceforge.net

(replace # with @)

\end{verbatim}

\noindent
Elements to send:

\begin{enumerate}
 \item Ray command including mpirun
  \item Ray standard output: mpirun -np 32 /path/to/Ray -p p\_1.fastq p\_2.fastq -o Out $|$\& tee Log; gzip Log; ls -lh Log.gz
    \item  C++ compiler name (examples: GNU g++, Intel ICC, or other) and version (usually $--$version)
   \item  MPI library name (examples: Open-MPI, MPICH2, or other) and version (usually $--$version)
    \item  Sequencer vendor and model that generated reads
    \item  Total physical memory of the system and physical memory available for each MPI ranks
\item Job scheduler (examples: Grid Engine, PBS, none or other)
\end{enumerate}

\noindent
Also, if you have access to compute nodes:

\begin{enumerate}
\setcounter{enumi}{7}
   \item Memory page size: getconf PAGESIZE $>$ pagesize
   \item Central processing unit: cat /proc/cpuinfo|gzip$>$ cpuinfo.gz
   \item Memory information: cat /proc/meminfo|gzip$>$ meminfo.gz
   \item Kernel: uname -a$>$ uname-a 
\end{enumerate}


THE END

\end{document}
