1 ------------------------------------------------------------
3 ------------------------------------------------------------
5 BamTools: a C++ API & toolkit for reading/writing/manipulating BAM files.
21 ------------------------------------------------------------
25 BamTools provides both a programmer's API and an end-user's toolkit for handling
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.
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.
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.
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:
53 usage: bamtools [--help] COMMAND [ARGS]
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)
67 See 'bamtools help COMMAND' for more information on a specific command.
69 ** Follow-up explanation here **
71 ------------------------------------------------------------
75 ** General usage information - perhaps explain common terms, point to SAM/BAM spec, etc **
80 To use this API, you simply need to do 3 things:
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)
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;
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).
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.
99 ** More indepth overview for the toolkit commands **
101 ------------------------------------------------------------
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.
109 ------------------------------------------------------------
111 IV. Acknowledgements :
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.
117 ------------------------------------------------------------
121 Feel free to contact me with any questions, comments, suggestions, bug reports, etc.
125 Biology Dept., Boston College
127 Email: barnetde@bc.edu
128 Project Websites: http://github.com/pezmaster31/bamtools (ACTIVE SUPPORT)
129 http://sourceforge.net/projects/bamtools (major updates only)