README : BAMTOOLS
------------------------------------------------------------
-BamTools: a C++ API for reading/writing BAM files.
+BamTools: a C++ API & toolkit for reading/writing/manipulating BAM files.
+I. Introduction
+ a. The API
+ b. The Toolkit
+
+II. Usage
+ a. The API
+ b. The Toolkit
+
+III. Contact
+
+------------------------------------------------------------
+
+I. Introduction:
+BamTools provides both a programmer's API and an end-user's toolkit for handling
+BAM files.
+
+Ia. The API
The API consists of 2 main modules - BamReader and BamWriter. As you would expect,
BamReader provides read-access to BAM files, while BamWriter does the writing of BAM
-files. BamReader provides an interface for random-access (jumping) in a BAM file.
+files. BamReader provides an interface for random-access (jumping) in a BAM file,
+as well as generating BAM index files.
+BamMultiReader is an extra module that allows you to manage multiple open BAM file
+for reading. It provides some validation & bookkeeping under the hood to keep all
+files sync'ed for
+
An additional file, BamAux.h, is included as well.
This file contains the common data structures and typedefs used throught the API.
+BGZF.h & BGZF.cpp contain our implementation of the Broad Institute's
+BGZF compression format.
+
+
+Ib. The Toolkit
+If you've been using BamTools since the early days, you'll notice that our 'toy' API
+examples (BamConversion, BamDump, and BamTrim) are now gone. In their place is a set
+of features we hope you find useful.
+
+** More explanation here **
+
+usage: bamtools [--help] COMMAND [ARGS]
+
+Available bamtools commands:
+ convert Converts between BAM and a number of other formats
+ count Prints number of alignments in BAM file
+ coverage Prints coverage statistics from the input BAM file
+ filter Filters BAM file(s) by user-specified criteria
+ header Prints BAM header information
+ index Generates index for BAM file
+ merge Merge multiple BAM files into single file
+ sam Prints the BAM file in SAM (text) format
+ sort Sorts the BAM file according to some criteria
+ stats Prints some basic statistics from the input BAM file
+
+See 'bamtools help COMMAND' for more information on a specific command.
+
+** Follow-up explanation here **
+
------------------------------------------------------------
+II. Usage :
+
+** General usage information - perhaps explain common terms, point to SAM/BAM spec, etc **
+
+
+IIa. The API
+
To use this API, you simply need to do 3 things:
1 - Drop the BamTools files somewhere the compiler can find them.
- (i.e. in source directory, or somewhere in include path)
+ (i.e. in your source tree, or somewhere else in your include path)
2 - Import BamTools API with the following lines of code
#include "BamReader.h" // as needed
#include "BamWriter.h" // as needed
using namespace BamTools;
- 3 - Compile with '-lz' ('l' as in 'lion') to access ZLIB compression library
+ 3 - Compile with '-lz' ('l' as in Lima) to access ZLIB compression library
+ (For VS users, I can provide you zlib headers - just contact me).
See any included programs and Makefile for more specific compiling/usage examples.
-See documentation & comments in header files for API details.
+See comments in the header files for more detailed API documentation.
+
+
+IIb. The Toolkit
+
+** More indepth overview for the toolkit commands **
------------------------------------------------------------
+III. Contact :
+
Feel free to contact me with any questions, comments, suggestions, bug reports, etc.
- Derek Barnett
-
-http://sourceforge.net/projects/bamtools
+
+Marth Lab
+Biology Dept., Boston College
+
+Email: barnetde@bc.edu
+Project Websites: http://github.com/pezmaster31/bamtools (ACTIVE SUPPORT)
+ http://sourceforge.net/projects/bamtools (major updates only)
projects / bamtools.git / blobdiff