README

   1 ------------------------------------------------------------
   2 README : BAMTOOLS
   3 ------------------------------------------------------------
   4
   5 BamTools: a C++ API & toolkit for reading/writing/manipulating BAM files.
   6
   7 I. Introduction
   8     a. The API
   9     b. The Toolkit
  10
  11 II. Usage
  12     a. The API
  13     b. The Toolkit
  14
  15 III. Contact
  16
  17 ------------------------------------------------------------
  18
  19 I. Introduction:
  20 BamTools provides both a programmer's API and an end-user's toolkit for handling
  21 BAM files.
  22
  23 Ia. The API
  24 The API consists of 2 main modules - BamReader and BamWriter. As you would expect,
  25 BamReader provides read-access to BAM files, while BamWriter does the writing of BAM
  26 files. BamReader provides an interface for random-access (jumping) in a BAM file,
  27 as well as generating BAM index files.
  28
  29 BamMultiReader is an extra module that allows you to manage multiple open BAM file
  30 for reading. It provides some validation & bookkeeping under the hood to keep all
  31 files sync'ed for
  32
  33 An additional file, BamAux.h, is included as well.
  34 This file contains the common data structures and typedefs used throught the API.
  35
  36 BGZF.h & BGZF.cpp contain our implementation of the Broad Institute's
  37 BGZF compression format.
  38
  39
  40 Ib. The Toolkit
  41 If you've been using BamTools since the early days, you'll notice that our 'toy' API
  42 examples (BamConversion, BamDump, and BamTrim) are now gone.  In their place is a set
  43 of features we hope you find useful.
  44
  45 ** More explanation here **
  46
  47 usage: bamtools [--help] COMMAND [ARGS]
  48
  49 Available bamtools commands:
  50         convert         Converts between BAM and a number of other formats
  51         count           Prints number of alignments in BAM file
  52         coverage        Prints coverage statistics from the input BAM file
  53         filter          Filters BAM file(s) by user-specified criteria
  54         header          Prints BAM header information
  55         index           Generates index for BAM file
  56         merge           Merge multiple BAM files into single file
  57         sam             Prints the BAM file in SAM (text) format
  58         sort            Sorts the BAM file according to some criteria
  59         stats           Prints some basic statistics from the input BAM file
  60
  61 See 'bamtools help COMMAND' for more information on a specific command.
  62
  63 ** Follow-up explanation here **
  64
  65 ------------------------------------------------------------
  66
  67 II. Usage :
  68
  69 ** General usage information - perhaps explain common terms, point to SAM/BAM spec, etc **
  70
  71
  72 IIa. The API
  73
  74 To use this API, you simply need to do 3 things:
  75
  76     1 - Drop the BamTools files somewhere the compiler can find them.
  77         (i.e. in your source tree, or somewhere else in your include path)
  78
  79     2 - Import BamTools API with the following lines of code
  80         #include "BamReader.h"     // as needed
  81         #include "BamWriter.h"     // as needed
  82         using namespace BamTools;
  83
  84     3 - Compile with '-lz' ('l' as in Lima) to access ZLIB compression library
  85             (For VS users, I can provide you zlib headers - just contact me).
  86
  87 See any included programs and Makefile for more specific compiling/usage examples.
  88 See comments in the header files for more detailed API documentation.
  89
  90
  91 IIb. The Toolkit
  92
  93 ** More indepth overview for the toolkit commands **
  94
  95 ------------------------------------------------------------
  96
  97 III. Contact :
  98
  99 Feel free to contact me with any questions, comments, suggestions, bug reports, etc.
 100   - Derek Barnett
 101
 102 Marth Lab
 103 Biology Dept., Boston College
 104
 105 Email: barnetde@bc.edu
 106 Project Websites: http://github.com/pezmaster31/bamtools   (ACTIVE SUPPORT)
 107                   http://sourceforge.net/projects/bamtools (major updates only)