     [file package.texi not included]

This file documents the Gk-Arrays library.

Copyright © 2010-2013 -- IRB/INSERM (Institut de Recherches en Biothérapie / Institut National de la Santé et de la Recherche Médicale), LIFL/INRIA (Laboratoire d'Informatique Fondamentale de Lille / Institut National de Recherche en Informatique et Automatique), LIRMM/CNRS (Laboratoire d'Informatique, de Robotique et de Microélectronique de Montpellier / Centre National de la Recherche Scientifique), LITIS (Laboratoire d'Informatique, du Traitement de l'Information et des Systèmes).

Authors: Nicolas PHILIPPE nicolas.philippe@lirmm.fr, Mikaël SALSON mikael.salson@lifl.fr, Thierry LECROQ thierry.lecroq@univ-rouen.fr, Martine LÉONARD Martine.Leonard@univ-rouen.fr, Eric RIVALS eric.rivals@lirmm.fr

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation as circulated by CÉA, CNRS and INRIA at the following URL http://www.cecill.info.

Documentation for the version VERSION of the Gk-Arrays library.

How to Read This Manual
***********************

  * In the Developing section, we explain how to use the Gk-arrays library in your code.

  * You will find in the Copying section the CeCILL-C License.

Developing
**********

The Gk-arrays library is dedicated to indexing millions of reads from high-throughput sequencing experiments. This library can index variable-length (as produced by Roche 454) or fixed-length reads. It provides several functions to find reads or occurrences in reads of k-mers where k is specified at index creation.

If you use Gk-arrays, please don't forget to cite:

N. Philippe, M. Salson, T. Lecroq, M. Léonard, T. Commes, É. Rivals. Querying large read collections in main memory: a versatile data structure. In BMC Bioinformatics, 2011, doi:10.1186/1471-2105-12-242.

Installing Gk-arrays
====================

Installation from the source code
---------------------------------

 1. Unpack the archive

 2. Enter the directory libGkArrays-version-number

 3. Type ./configure

 4. If everything went fine, run make

 5. To install the library on your machine, type make install as an administrator

 6. Afterwards, you may want to run ldconfig as an administrator

You can specify parameters to the configure script. For instance you can choose to build a static version (quicker) of the library rather than a shared version. Typing ./configure --help will provide you the list of available options.

Installation from the deb package
---------------------------------

You just need to install the package using a dedicated program on your distribution or by typing dpkg -i package-name This will install the library and source file headers.

Using Gk-arrays in your code
============================

First, you need to include the header file that defines all the functions in the Gk-arrays:
#include <libGkArrays/gkArrays.h>

The Gk-arrays consist of a C++ class. To build an index on a new collection of reads, you first need to build a new object from that class. The class is called gkArrays in the namespace gkarrays.

The constructor of that class has two compulsory parameters and one optional:

 1. The name of the file containing the reads in raw, FASTA, FASTQ format. The file can also be gunzipped.

 2. The length of the k-mer you want to use, ie the value of k.

 3. (optional) The length of the reads. The length of the reads is automatically detected but you may want to specify a shorter length (cannot be larger than the actual length).

Hence, if filename holds the name of a file and 10 is the desired value of k, a valid index creation would be:
gkarrays::gkArrays *reads = new gkarrays::gkArrays(filename, 10);

Then the main methods are (but you can report to the full documentation in the docs/documentation directory of the project or to the online documentation http://crac.gforge.inria.fr/gkarrays/doc):

Method   Purpose
getNbTags()   Number of reads indexed
getTag(i)   Return a char* containing the read itself
getTagNumWithFactor(r, l)   Read numbers (indexed from 0) containing the same k-mer as in read r at position l.
getTagsWithFactor(r, l)   Same as above but return the occurrences
as a pair (read number, position in the read).
getNbTagsWithFactor(r, l, m)   Return the number of occurrences
returned by getTagsWithFactor(r, l) (if m is true) or by
getTagNumWithFactor(r, l) (if m is false).

Compiling your code
===================

At compilation time, you need to specify that you are using the Gk-arrays library. This can be done by specifying -lGkArrays during the linking. You may have to specify where the library is installed using the -L flag if you didn't install the library in the default library directory.

Example
=======

#include <iostream>
#include <cstdlib>
#include <libGkArrays/gkArrays.h>
#include <cstdio>

int main(int argc, char **argv) {

  if (argc < 2) {
    std::cerr << "Usage: " << argv[0] << " filename" << std::endl;
    exit(1);
  }

  // Default k-mer length
  int k = 5;
  // Building the index
  gkarrays::gkArrays *reads = new gkarrays::gkArrays(argv[1], k);
  // Retrieving the first k-mer of the first read
  char *kmer = reads->getTagFactor(0, 0, k);

  // Displaying the number of indexed reads
  printf("%d reads in the collection\n", reads->getNbTags());

  // Displaying the number of reads with a given k-mer
  printf("%d read(s) share the k-mer %s\n",
         reads->getNbTagsWithFactor(0, 0, false),
         kmer);

  // Displaying the read numbers that contain that specific k-mer
  printf("Read containing the occurrences:\n");
  uint *read_occurrences = reads->getTagNumWithFactor(0, 0);
  for (uint i = 0; i < reads->getNbTagsWithFactor(0, 0, false); i++)
    printf("%d\t", read_occurrences[i]);
  printf("\n");

  // Displaying the occurrences (read number, position in the read)
  // for that specific k-mer.
  printf("All the occurrences:\n");
  std::pair<uint, uint> *occurrences = reads->getTagsWithFactor(0, 0);
  for (uint i = 0; i < reads->getNbTagsWithFactor(0, 0, true); i++) {
    printf("(%d,%d)\t", occurrences[i].first, occurrences[i].second);
  }
  printf("\n");

  // Free-ing memory.
  free(read_occurrences);
  delete [] occurrences;
  delete reads;
  delete [] kmer;
  exit(0);
}

If you store this example in a file called test.cpp, you can compile it with g++  -Wall -pedantic -O3 test4.cpp -o test4 -lGkArrays. Note that a more complete example is given in the src directory in the file buildTables.cpp.

     [file CeCILL-C.texi not included]

Reporting Bugs
**************

If you find a bug in Gk-arrays library, please send electronic mail to crac-gkarrays@lists.gforge.inria.fr.  Include the version number. Also include in your message the output that the program produced and the output you expected.

If you have other questions, comments or suggestions about the GkArrays library, contact the authors via electronic mail to crac-gkarrays@lists.gforge.inria.fr.  The authors will try to help you out, although they may not have time to fix your problems.