Ray man page

Ray — assemble genomes in parallel using the message-passing interface


mpiexec -n NUMBER_OF_RANKS Ray -k KMERLENGTH -p l1_1.fastq l1_2.fastq -p l2_1.fastq l2_2.fastq -o test

mpiexec -n NUMBER_OF_RANKS Ray Ray.conf # with commands in a file


The Ray genome assembler is built on top of the RayPlatform, a generic plugin-based
distributed and parallel compute engine that uses the message-passing interface
for passing messages.

Ray targets several applications:

- de novo genome assembly (with Ray vanilla)
- de novo meta-genome assembly (with Ray Méta)
- de novo transcriptome assembly (works, but not tested a lot)
- quantification of contig abundances
- quantification of microbiome consortia members (with Ray Communities)
- quantification of transcript expression
- taxonomy profiling of samples (with Ray Communities)
- gene ontology profiling of samples (with Ray Ontologies)


Displays this help page.
Displays Ray version and compilation options.

Using a configuration file

Ray can be launched with
mpiexec -n 16 Ray Ray.conf
The configuration file can include comments (starting with #).

K-mer length

-k kmerLength
Selects the length of k-mers. The default value is 21.
It must be odd because reverse-complement vertices are stored together.
The maximum length is defined at compilation by MAXKMERLENGTH
Larger k-mers utilise more memory.


-p leftSequenceFile rightSequenceFile [averageOuterDistance standardDeviation]
Provides two files containing paired-end reads.
averageOuterDistance and standardDeviation are automatically computed if not provided.
-i interleavedSequenceFile [averageOuterDistance standardDeviation]
Provides one file containing interleaved paired-end reads.
averageOuterDistance and standardDeviation are automatically computed if not provided.
-s sequenceFile
Provides a file containing single-end reads.


-o outputDirectory
Specifies the directory for outputted files. Default is RayOutput

Assembly options (defaults work well)

Disables read recycling during the assembly
reads will be set free in 3 cases:
1. the distance did not match for a pair
2. the read has not met its mate
3. the library population indicates a wrong placement
see Constrained traversal of repeats with paired sequences.
Sébastien Boisvert, Élénie Godzaridis, François Laviolette & Jacques Corbeil.
First Annual RECOMB Satellite Workshop on Massively Parallel Sequencing, March 26-27 2011, Vancouver, BC, Canada.
Disables the scaffolder.
-minimum-contig-length minimumContigLength
Changes the minimum contig length, default is 100 nucleotides
Runs in color-space
Needs csfasta files. Activated automatically if csfasta files are provided.
-use-maximum-seed-coverage maximumSeedCoverageDepth
Ignores any seed with a coverage depth above this threshold.
The default is 4294967295.
-use-minimum-seed-coverage minimumSeedCoverageDepth
Sets the minimum seed coverage depth.
Any path with a coverage depth lower than this will be discarded. The default is 0.

Distributed storage engine (all these values are for each MPI rank)

-bloom-filter-bits bits
Sets the number of bits for the Bloom filter
Default is 268435456 bits, 0 bits disables the Bloom filter.
-hash-table-buckets buckets
Sets the initial number of buckets. Must be a power of 2 !
Default value: 268435456
-hash-table-buckets-per-group buckets
Sets the number of buckets per group for sparse storage
Default value: 64, Must be between >=1 and <= 64
-hash-table-load-factor-threshold threshold
Sets the load factor threshold for real-time resizing
Default value: 0.75, must be >= 0.5 and < 1
Activates verbosity for the distributed storage engine

Biological abundances

-search searchDirectory
Provides a directory containing fasta files to be searched in the de Bruijn graph.
Biological abundances will be written to RayOutput/BiologicalAbundances
See Documentation/BiologicalAbundances.txt
Sets one color per file instead of one per sequence.
By default, each sequence in each file has a different color.
For files with large numbers of sequences, using one single color per file may be more efficient.

Taxonomic profiling with colored de Bruijn graphs

-with-taxonomy Genome-to-Taxon.tsv TreeOfLife-Edges.tsv Taxon-Names.tsv
Provides a taxonomy.
Computes and writes detailed taxonomic profiles.
See Documentation/Taxonomy.txt for details.
-gene-ontology OntologyTerms.txt Annotations.txt
Provides an ontology and annotations.
OntologyTerms.txt is fetched from http://geneontology.org
Annotations.txt is a 2-column file (EMBL_CDS handle & gene ontology identifier)
See Documentation/GeneOntology.txt
Other outputs
Computes contig neighborhoods in the de Bruijn graph
Output file: RayOutput/NeighbourhoodRelations.txt
Writes the AMOS file called RayOutput/AMOS.afg
An AMOS file contains read positions on contigs.
Can be opened with software with graphical user interface.
Writes k-mer graph to RayOutput/kmers.txt
The resulting file is not utilised by Ray.
The resulting file is very large.
Writes read markers to disk.
Writes seed DNA sequences to RayOutput/Rank<rank>.RaySeeds.fasta
Writes extension DNA sequences to RayOutput/Rank<rank>.RayExtensions.fasta
Writes contig paths with coverage values
to RayOutput/Rank<rank>.RayContigPaths.txt
Writes marker statistics.

Memory usage

Shows memory usage. Data is fetched from /proc on GNU/Linux
Needs __linux__
Shows memory allocation events

Algorithm verbosity

Shows the choice made (with other choices) during the extension.
Shows the ending context of each extension.
Shows the children of the vertex where extension was too difficult.
Shows summary of outer distances used for an extension path.
Shows the consensus when a choice is done.


-write-checkpoints checkpointDirectory
Write checkpoint files
-read-checkpoints checkpointDirectory
Read checkpoint files
-read-write-checkpoints checkpointDirectory
Read and write checkpoint files

Message routing for large number of cores

Enables the Ray message router. Disabled by default.
Messages will be routed accordingly so that any rank can communicate directly with only a few others.
Without -route-messages, any rank can communicate directly with any other rank.
Files generated: Routing/Connections.txt, Routing/Routes.txt and Routing/RelayEvents.txt
and Routing/Summary.txt
-connection-type type
Sets the connection type for routes.
Accepted values are debruijn, hypercube, polytope, group, random, kautz and complete. Default is debruijn.
debruijn: a full de Bruijn graph a given alphabet and diameter
hypercube: a hypercube, alphabet is {0,1} and the vertices is a power of 2
polytope: a convex regular polytope, alphabet is {0,1,...,B-1} and the vertices is a power of B
group: silly model where one representative per group can communicate with outsiders
random: Erdős-Rényi model
kautz: a full de Kautz graph, which is a subgraph of a de Bruijn graph
complete: a full graph with all the possible connections
With the type debruijn, the number of ranks must be a power of something.
Examples: 256 = 16*16, 512=8*8*8, 49=7*7, and so on.
Otherwise, don't use debruijn routing but use another one
With the type kautz, the number of ranks n must be n=(k+1)*k^(d-1) for some k and d
-routing-graph-degree degree
Specifies the outgoing degree for the routing graph.
See Documentation/Routing.txt

Hardware testing

Tests the network and returns.
Writes one additional file per rank detailing the network test.
-exchanges NumberOfExchanges
Sets the number of exchanges
Skips the network test.


Checks message data reliability for any non-empty message.
add '-D CONFIG_SSE_4_2' in the Makefile to use hardware instruction (SSE 4.2)
Runs the profiler as the code runs. By default, only show granularity warnings.
Running the profiler increases running times.
Shows number of messages sent and received in each methods during in each time slices (epochs). Needs -run-profiler.
Shows all messages sent and received.
Shows read placement in the graph during the extension.
Debugs bubble code.
Bubbles can be due to heterozygous sites or sequencing errors or other (unknown) events
Debugs seed code.
Seeds are paths in the graph that are likely unique.
Debugs fusion code.
Debug the scaffolder.


Input files

Note: file format is determined with file extension.

.fasta.gz (needs HAVE_LIBZ=y at compilation)
.fasta.bz2 (needs HAVE_LIBBZ2=y at compilation)
.fastq.gz (needs HAVE_LIBZ=y at compilation)
.fastq.bz2 (needs HAVE_LIBBZ2=y at compilation)
.sff (paired reads must be extracted manually)
.csfasta (color-space reads)

Outputted files


The scaffold sequences in FASTA format
The components of each scaffold
The length of each scaffold
Scaffold links


Contiguous sequences in FASTA format
The lengths of contiguous sequences


Overall numbers for the assembly

de Bruijn graph

The distribution of coverage values
Analysis of the coverage distribution
Distribution of ingoing and outgoing degrees
k-mer graph, required option: -write-kmers
The resulting file is not utilised by Ray.
The resulting file is very large.

Assembly steps

Distribution of seed length
Read markers.
Seed DNA sequences, required option: -write-seeds
Extension DNA sequences, required option: -write-extensions
Contig paths with coverage values, required option: -write-contig-paths

Paired reads

Estimation of outer distances for paired reads
Frequencies for observed outer distances (insert size + read lengths)


Number of reads in each file
Sequence partition

Ray software

The version of Ray
The exact same command provided


Assembly representation in AMOS format, required option: -amos


RayOutput/MessagePassingInterface.txt Number of messages sent
RayOutput/NetworkTest.txt Latencies in microseconds
RayOutput/Rank<rank>NetworkTestData.txt Network test raw data


- mpiexec -n 1 Ray -help|less (always up-to-date)
- This help page (always up-to-date)
- The directory Documentation/
- Manual (Portable Document Format): InstructionManual.tex (in Documentation)
- Mailing list archives: http://sourceforge.net/mailarchive/foru…


Written by Sébastien Boisvert.

Reporting Bugs

Report bugs to denovoassembler-users@lists.sourceforge.net
Home page: <http://denovoassembler.sourceforge.net/>


Ray 2.1.0 November 2012