-** General usage information - perhaps explain common terms, point to SAM/BAM
-spec, etc **
-
-----------------------------------------
-IIa. The API
-----------------------------------------
-
-The API, as noted above, contains 2 main modules - BamReader & BamWriter - for
-dealing with BAM files. Alignment data is made available through the
-BamAlignment data structure.
-
-A simple (read-only) scenario for accessing BAM data would look like the
-following:
-
- // open our BamReader
- BamReader reader;
- reader.Open("someData.bam", "someData.bam.bai");
-
- // define our region of interest
- // in this example: bases 0-500 on the reference "chrX"
- int id = reader.GetReferenceID("chrX");
- BamRegion region(id, 0, id, 500);
- reader.SetRegion(region);
-
- // iterate through alignments in this region,
- // ignoring alignments with a MQ below some cutoff
- BamAlignment al;
- while ( reader.GetNextAlignment(al) ) {
- if ( al.MapQuality >= 50 )
- // do something
- }
-
- // close the reader
- reader.Close();
-
-To use this API in your application, you simply need to do 3 things:
-
- 1 - Drop the BamTools API files somewhere the compiler can find them.
-
- 2 - Import BamTools API with the following lines of code
- #include "BamReader.h" // (or "BamMultiReader.h") as needed
- #include "BamWriter.h" // as needed
- using namespace BamTools; // all of BamTools classes/methods live in
- // this namespace
-
- 3 - Link with '-lz' ('l' as in Lima) to access ZLIB compression library
- (For MSVC users, I can provide you modified zlib headers - just contact
- me if needed).
-
-See any included programs and Makefile for more specific compiling/usage
-examples. See comments in the header files for more detailed API documentation.
-
-----------------------------------------
-IIb. The Toolkit
-----------------------------------------
-
-BamTools provides a small, but powerful suite of command-line utility programs
-for manipulating and querying BAM files for data.
-
---------------------
-Input/Output
---------------------
-
-All BamTools utilities handle I/O operations using a common set of arguments.
-These include:
-
- -in <BAM file>
-
-The input BAM files(s).
-
- If a tool accepts multiple BAM files as input, each file gets its own "-in"
- option on the command line. If no "-in" is provided, the tool will attempt
- to read BAM data from stdin.
-
- To read a single BAM file, use a single "-in" option:
- > bamtools *tool* -in myData1.bam ...ARGS...
-
- To read multiple BAM files, use multiple "-in" options:
- > bamtools *tool* -in myData1.bam -in myData2.bam ...ARGS...
-
- To read from stdin (if supported), omit the "-in" option:
- > bamtools *tool* ...ARGS...
-
- -out <BAM file>
-
-The output BAM file.
-
- If a tool outputs a result BAM file, specify the filename using this option.
- If none is provided, the tool will typically write to stdout.
-
- *Note: Not all tools output BAM data (e.g. count, header, etc.)
-
- -region <REGION>
-
-A region of interest. See below for accepted 'REGION string' formats.
-
- Many of the tools accept this option, which allows a user to only consider
- alignments that overlap this region (whether counting, filtering, merging,
- etc.).
-
- An alignment is considered to overlap a region if any part of the alignments
- intersects the left/right boundaries. Thus, a 50bp alignment at position 70
- will overlap a region beginning at position 100.
-
- REGION string format
- ----------------------
- A proper REGION string can be formatted like any of the following examples:
- where 'chr1' is the name of a reference (not its ID)and '' is any valid
- integer position within that reference.