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 I. Introduction:
  23 --------------------------------------------------------------------------------
  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
  32 The API consists of 2 main modules: BamReader and BamWriter. As you would
  33 expect, BamReader provides read-access to BAM files, while BamWriter handles
  34 writing data to BAM files. BamReader provides the interface for random-access
  35 (jumping) in a BAM file, as well as generating BAM index files.
  36
  37 BamMultiReader is an extra module that allows you to manage multiple open BAM
  38 files for reading. It provides some validation & bookkeeping under the hood to
  39 keep all files sync'ed up for you.
  40
  41 Additional files used by the API:
  42
  43  - BamAlignment.* : implements the BamAlignment data structure
  44
  45  - BamAux.h       : contains various constants, data structures and utility
  46                     methods used throught the API.
  47
  48  - BamIndex.*     : implements both the standard BAM format index (".bai") as
  49                     well as a new BamTools-specific index (".bti").
  50
  51  - BGZF.*         : contains our implementation of the Broad Institute's BGZF
  52                     compression format.
  53
  54 ----------------------------------------
  55 Ib. The Toolkit:
  56 ----------------------------------------
  57
  58 If you've been using the BamTools since the early days, you'll notice that our
  59 'toy' API examples (BamConversion, BamDump, BamTrim,...) are now gone.  We have
  60 dumped these in favor of a suite of small utilities that we hope both
  61 developers and end-users find useful:
  62
  63 usage: bamtools [--help] COMMAND [ARGS]
  64
  65 Available bamtools commands:
  66
  67         convert         Converts between BAM and a number of other formats
  68         count           Prints number of alignments in BAM file(s)
  69         coverage        Prints coverage statistics from the input BAM file
  70         filter          Filters BAM file(s) by user-specified criteria
  71         header          Prints BAM header information
  72         index           Generates index for BAM file
  73         merge           Merge multiple BAM files into single file
  74         random          Select random alignments from existing BAM file(s)
  75         sort            Sorts the BAM file according to some criteria
  76         split           Splits a BAM file on user-specifed property, creating a
  77                             new BAM output file for each value found
  78         stats           Prints some basic statistics from input BAM file(s)
  79
  80 See 'bamtools help COMMAND' for more information on a specific command.
  81
  82 --------------------------------------------------------------------------------
  83 II. Usage :
  84 --------------------------------------------------------------------------------
  85
  86 ** General usage information - perhaps explain common terms, point to SAM/BAM
  87 spec, etc **
  88
  89 ----------------------------------------
  90 IIa. The API
  91 ----------------------------------------
  92
  93 The API, as noted above, contains 2 main modules - BamReader & BamWriter - for
  94 dealing with BAM files. Alignment data is made available through the
  95 BamAlignment data structure.
  96
  97 A simple (read-only) scenario for accessing BAM data would look like the
  98 following:
  99
 100         // open our BamReader
 101         BamReader reader;
 102         reader.Open("someData.bam", "someData.bam.bai");
 103
 104         // define our region of interest
 105         // in this example: bases 0-500 on the reference "chrX"
 106         int id = reader.GetReferenceID("chrX");
 107         BamRegion region(id, 0, id, 500);
 108         reader.SetRegion(region);
 109
 110         // iterate through alignments in this region,
 111         // ignoring alignments with a MQ below some cutoff
 112         BamAlignment al;
 113         while ( reader.GetNextAlignment(al) ) {
 114             if ( al.MapQuality >= 50 )
 115                 // do something
 116         }
 117
 118         // close the reader
 119         reader.Close();
 120
 121 To use this API in your application, you simply need to do 3 things:
 122
 123     1 - Drop the BamTools API files somewhere the compiler can find them.
 124
 125     2 - Import BamTools API with the following lines of code
 126         #include "BamReader.h"     // (or "BamMultiReader.h") as needed
 127         #include "BamWriter.h"     // as needed
 128         using namespace BamTools;  // all of BamTools classes/methods live in
 129                                    // this namespace
 130
 131     3 - Link with '-lz' ('l' as in Lima) to access ZLIB compression library
 132         (For MSVC users, I can provide you modified zlib headers - just contact
 133         me if needed).
 134
 135 See any included programs and Makefile for more specific compiling/usage
 136 examples. See comments in the header files for more detailed API documentation.
 137
 138 ----------------------------------------
 139 IIb. The Toolkit
 140 ----------------------------------------
 141
 142 BamTools provides a small, but powerful suite of command-line utility programs
 143 for manipulating and querying BAM files for data.
 144
 145 --------------------
 146 Input/Output
 147 --------------------
 148
 149 All BamTools utilities handle I/O operations using a common set of arguments.
 150 These include:
 151
 152  -in <BAM file>
 153
 154 The input BAM files(s).
 155
 156     If a tool accepts multiple BAM files as input, each file gets its own "-in"
 157     option on the command line. If no "-in" is provided, the tool will attempt
 158     to read BAM data from stdin.
 159
 160     To read a single BAM file, use a single "-in" option:
 161     > bamtools *tool* -in myData1.bam ...ARGS...
 162
 163     To read multiple BAM files, use multiple "-in" options:
 164     > bamtools *tool* -in myData1.bam -in myData2.bam ...ARGS...
 165
 166     To read from stdin (if supported), omit the "-in" option:
 167     > bamtools *tool* ...ARGS...
 168
 169   -out <BAM file>
 170
 171 The output BAM file.
 172
 173     If a tool outputs a result BAM file, specify the filename using this option.
 174     If none is provided, the tool will typically write to stdout.
 175
 176     *Note: Not all tools output BAM data (e.g. count, header, etc.)
 177
 178  -region <REGION>
 179
 180 A region of interest. See below for accepted 'REGION string' formats.
 181
 182     Many of the tools accept this option, which allows a user to only consider
 183     alignments that overlap this region (whether counting, filtering, merging,
 184     etc.).
 185
 186     An alignment is considered to overlap a region if any part of the alignments
 187     intersects the left/right boundaries. Thus, a 50bp alignment at position 70
 188     will overlap a region beginning at position 100.
 189
 190     REGION string format
 191     ----------------------
 192     A proper REGION string can be formatted like any of the following examples:
 193         where 'chr1' is the name of a reference (not its ID)and '' is any valid
 194         integer position within that reference.
 195
 196     To read
 197     chr1               - only alignments on (entire) reference 'chr1'
 198     chr1:500           - only alignments overlapping the region starting at
 199                          chr1:500 and continuing to the end of chr1
 200     chr1:500..1000     - only alignments overlapping the region starting at
 201                          chr1:500 and continuing to chr1:1000
 202     chr1:500..chr3:750 - only alignments overlapping the region starting at
 203                          chr1:500 and continuing to chr3:750. This 'spanning'
 204                          region assumes that the reference specified as the
 205                          right boundary will occur somewhere in the file after
 206                          the left boundary. On a sorted BAM, a REGION of
 207                          'chr4:500..chr2:1500' will produce undefined
 208                          (incorrect) results.  So don't do it. :)
 209
 210     *Note: Most of the tools that accept a REGION string will perform without an
 211            index file, but typically at great cost to performance (having to
 212            plow through the entire file until the region of interest is found).
 213            For optimum speed, be sure that index files are available for your
 214            data.
 215
 216  -forceCompression
 217
 218 Force compression of BAM output.
 219
 220     When tools are piped together (see details below), the default behavior is
 221     to turn off compression. This can greatly increase performance when the data
 222     does not have to be constantly decompressed and recompressed. This is
 223     ignored any time an output BAM file is specified using "-out".
 224
 225 --------------------
 226 Piping
 227 --------------------
 228
 229 Many of the tools in BamTools can be chained together by piping.  Any tool that
 230 accepts stdin can be piped into, and any that can output stdout can be piped
 231 from. For example:
 232
 233 > bamtools filter -in data1.bam -in data2.bam -mapQuality ">50" | bamtools count
 234
 235 will give a count of all alignments in your 2 BAM files with a mapQuality of
 236 greater than 50. And of course, any tool writing to stdout can be piped into
 237 other utilities.
 238
 239 --------------------
 240 The Tools
 241 --------------------
 242
 243     convert         Converts between BAM and a number of other formats
 244     count           Prints number of alignments in BAM file(s)
 245     coverage        Prints coverage statistics from the input BAM file
 246     filter          Filters BAM file(s) by user-specified criteria
 247     header          Prints BAM header information
 248     index           Generates index for BAM file
 249     merge           Merge multiple BAM files into single file
 250     random          Select random alignments from existing BAM file(s)
 251     sort            Sorts the BAM file according to some criteria
 252     split           Splits a BAM file on user-specifed property, creating a new
 253                        BAM output file for each value found
 254     stats           Prints some basic statistics from input BAM file(s)
 255
 256 ----------
 257 convert
 258 ----------
 259
 260 Description: converts BAM to a number of other formats
 261
 262 Usage: bamtools convert -format <FORMAT> [-in <filename> -in <filename> ...]
 263                         [-out <filename>] [other options]
 264
 265 Input & Output:
 266   -in <BAM filename>               the input BAM file(s) [stdin]
 267   -out <BAM filename>              the output BAM file [stdout]
 268   -format <FORMAT>                 the output file format - see below for
 269                                        supported formats
 270
 271 Filters:
 272   -region <REGION>                 genomic region. Index file is recommended for
 273                                        better performance, and is read
 274                                        automatically if it exists. See 'bamtools
 275                                        help index' for more details on creating
 276                                        one.
 277
 278 Pileup Options:
 279   -fasta <FASTA filename>          FASTA reference file
 280   -mapqual                         print the mapping qualities
 281
 282 SAM Options:
 283   -noheader                        omit the SAM header from output
 284
 285 Help:
 286   --help, -h                       shows this help text
 287
 288 ** Notes **
 289
 290     - Currently supported output formats ( BAM -> X )
 291
 292         Format type   FORMAT (command-line argument)
 293         ------------  -------------------------------
 294         BED           bed
 295         FASTA         fasta
 296         FASTQ         fastq
 297         JSON          json
 298         Pileup        pileup
 299         SAM           sam
 300         YAML          yaml
 301
 302         Usage example:
 303         > bamtools convert -format json -in myData.bam -out myData.json
 304
 305     - Pileup Options have no effect on formats other than "pileup"
 306       SAM Options have no effect on formats other than "sam"
 307
 308 ----------
 309 count
 310 ----------
 311
 312 Description: prints number of alignments in BAM file(s).
 313
 314 Usage: bamtools count [-in <filename> -in <filename> ...] [-region <REGION>]
 315
 316 Input & Output:
 317   -in <BAM filename>               the input BAM file(s) [stdin]
 318
 319 Filters:
 320   -region <REGION>                 genomic region. Index file is required and
 321                                        is read automatically if it exists. See
 322                                        'bamtools help index' for more details
 323                                        on creating one.
 324
 325 Help:
 326   --help, -h                       shows this help text
 327
 328
 329 ----------
 330 coverage
 331 ----------
 332
 333
 334 ----------
 335 filter
 336 ----------
 337
 338
 339 ----------
 340 header
 341 ----------
 342
 343
 344 ----------
 345 index
 346 ----------
 347
 348
 349 ----------
 350 merge
 351 ----------
 352
 353
 354 ----------
 355 random
 356 ----------
 357
 358
 359 ----------
 360 sort
 361 ----------
 362
 363
 364 ----------
 365 split
 366 ----------
 367
 368
 369 ----------
 370 stats
 371 ----------
 372
 373
 374 --------------------------------------------------------------------------------
 375 III. License :
 376 --------------------------------------------------------------------------------
 377
 378 Both the BamTools API and toolkit are released under the MIT License.
 379 Copyright (c) 2009-2010 Derek Barnett, Erik Garrison, Gabor Marth,
 380     Michael Stromberg
 381
 382 See included file LICENSE for details.
 383
 384 --------------------------------------------------------------------------------
 385 IV. Acknowledgements :
 386 --------------------------------------------------------------------------------
 387
 388  * Aaron Quinlan for several key feature ideas and bug fix contributions
 389  * Baptiste Lepilleur for the public-domain JSON parser (JsonCPP)
 390  * Heng Li, author of SAMtools - the original C-language BAM API/toolkit.
 391
 392 --------------------------------------------------------------------------------
 393 V. Contact :
 394 --------------------------------------------------------------------------------
 395
 396 Feel free to contact me with any questions, comments, suggestions, bug reports,
 397     etc.
 398
 399 Derek Barnett
 400 Marth Lab
 401 Biology Dept., Boston College
 402
 403 Email: barnetde@bc.edu
 404 Project Websites: http://github.com/pezmaster31/bamtools   (ACTIVE SUPPORT)
 405                   http://sourceforge.net/projects/bamtools (major updates only)
 406