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. License
  16
  17 IV.  Acknowledgements
  18
  19 V.   Contact
  20
  21 ------------------------------------------------------------
  22
  23 I. Introduction:
  24
  25 BamTools provides both a programmer's API and an end-user's toolkit for handling
  26 BAM files.
  27
  28
  29 Ia. The API:
  30
  31 The API consists of 2 main modules - BamReader and BamWriter. As you would expect,
  32 BamReader provides read-access to BAM files, while BamWriter handles writing data to
  33 BAM files. BamReader provides an interface for random-access (jumping) in a BAM file,
  34 as well as generating BAM index files.
  35
  36 BamMultiReader is an extra module that allows you to manage multiple open BAM file
  37 for reading. It provides some validation & bookkeeping under the hood to keep all
  38 files sync'ed up for you.
  39
  40 Additional files used by the API:
  41  - BamAux.h   : contains the common data structures and typedefs used throught the API.
  42  - BamIndex.* : implements both the standard BAM format index (".bai") as well as a
  43                 new BamTools-specific index (".bti").
  44  - BGZF.*     : contains our implementation of the Broad Institute's BGZF compression format.
  45
  46
  47 Ib. The Toolkit:
  48
  49 If you've been using the BamTools since the early days, you'll notice that our 'toy' API
  50 examples (BamConversion, BamDump, BamTrim,...) are now gone.  We dumped these in favor of
  51 a suite of small utilities that we hope both developers and end-users find useful:
  52
  53 usage: bamtools [--help] COMMAND [ARGS]
  54
  55 Available bamtools commands:
  56         convert         Converts between BAM and a number of other formats
  57         count           Prints number of alignments in BAM file(s)
  58         coverage        Prints coverage statistics from the input BAM file
  59         filter          Filters BAM file(s) by user-specified criteria
  60         header          Prints BAM header information
  61         index           Generates index for BAM file
  62         merge           Merge multiple BAM files into single file
  63         random          Select random alignments from existing BAM file(s)
  64         sort            Sorts the BAM file according to some criteria
  65         stats           Prints some basic statistics from input BAM file(s)
  66
  67 See 'bamtools help COMMAND' for more information on a specific command.
  68
  69 ** Follow-up explanation here **
  70
  71 ------------------------------------------------------------
  72
  73 II. Usage :
  74
  75 ** General usage information - perhaps explain common terms, point to SAM/BAM spec, etc **
  76
  77
  78 IIa. The API
  79
  80 To use this API, you simply need to do 3 things:
  81
  82     1 - Drop the BamTools API files somewhere the compiler can find them.
  83         (i.e. in your project's source tree, or somewhere else in your include path)
  84
  85     2 - Import BamTools API with the following lines of code
  86         #include "BamReader.h"     // or "BamMultiReader.h", as needed
  87         #include "BamWriter.h"     // as needed
  88         using namespace BamTools;
  89
  90     3 - Compile with '-lz' ('l' as in Lima) to access ZLIB compression library
  91         (For MSVC users, I can provide you modified zlib headers - just contact me).
  92
  93 See any included programs and Makefile for more specific compiling/usage examples.
  94 See comments in the header files for more detailed API documentation.
  95
  96
  97 IIb. The Toolkit
  98
  99 ** More indepth overview for the toolkit commands **
 100
 101 ------------------------------------------------------------
 102
 103 III. License :
 104
 105 Both the BamTools API and toolkit are released under the MIT License.
 106 Copyright (c) 2009-2010 Derek Barnett, Erik Garrison, Gabor Marth, Michael Stromberg
 107 See file LICENSE for details.
 108
 109 ------------------------------------------------------------
 110
 111 IV. Acknowledgements :
 112
 113  * Aaron Quinlan for several key feature ideas and bug fix contributions
 114  * Baptiste Lepilleur for the public-domain JSON parser (JsonCPP)
 115  * Heng Li, author of SAMtools - the original C-language BAM API/toolkit.
 116
 117 ------------------------------------------------------------
 118
 119 V. Contact :
 120
 121 Feel free to contact me with any questions, comments, suggestions, bug reports, etc.
 122   - Derek Barnett
 123
 124 Marth Lab
 125 Biology Dept., Boston College
 126
 127 Email: barnetde@bc.edu
 128 Project Websites: http://github.com/pezmaster31/bamtools   (ACTIVE SUPPORT)
 129                   http://sourceforge.net/projects/bamtools (major updates only)
 130