]> git.donarmstrong.com Git - bamtools.git/blob - README
Updated README
[bamtools.git] / 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   -region <REGION>                  genomic region. Index file is recommended
319                                        for better performance, and is used
320                                        automatically if it exists. See
321                                        'bamtools help index' for more details
322                                        on creating one
323
324 Help:
325   --help, -h                        shows this help text
326
327 ----------
328 coverage
329 ----------
330
331 Description: prints coverage data for a single BAM file.
332
333 Usage: bamtools coverage [-in <filename>] [-out <filename>]
334
335 Input & Output:
336   -in <BAM filename>                the input BAM file [stdin]
337   -out <filename>                   the output file [stdout]
338
339 Help:
340   --help, -h                        shows this help text
341
342 ----------
343 filter
344 ----------
345
346 Description: filters BAM file(s).
347
348 Usage: bamtools filter [-in <filename> -in <filename> ...]
349                        [-out <filename> | [-forceCompression]]
350                        [-region <REGION>]
351                        [ [-script <filename] | [filterOptions] ]
352
353 Input & Output:
354   -in <BAM filename>                the input BAM file(s) [stdin]
355   -out <BAM filename>               the output BAM file [stdout]
356   -region <REGION>                  only read data from this genomic region (see
357                                        README for more details)
358   -script <filename>                the filter script file (see README for more
359                                        details)
360   -forceCompression                 if results are sent to stdout (like when
361                                        piping to another tool), default behavior
362                                        is to leave output uncompressed. Use this
363                                        flag to override and force compression
364
365 General Filters:
366   -alignmentFlag <int>              keep reads with this *exact* alignment flag
367                                        (for more detailed queries, see below)
368   -insertSize <int>                 keep reads with insert size that matches
369                                        pattern
370   -mapQuality <[0-255]>             keep reads with map quality that matches
371                                        pattern
372   -name <string>                    keep reads with name that matches pattern
373   -queryBases <string>              keep reads with motif that matches pattern
374   -tag <TAG:VALUE>                  keep reads with this key=>value pair
375
376 Alignment Flag Filters:
377   -isDuplicate <true/false>         keep only alignments that are marked as
378                                        duplicate [true]
379   -isFailedQC <true/false>          keep only alignments that failed QC [true]
380   -isFirstMate <true/false>         keep only alignments marked as first mate
381                                        [true]
382   -isMapped <true/false>            keep only alignments that were mapped [true]
383   -isMateMapped <true/false>        keep only alignments with mates that mapped
384                                        [true]
385   -isMateReverseStrand <true/false> keep only alignments with mate on reverse
386                                        strand [true]
387   -isPaired <true/false>            keep only alignments that were sequenced as
388                                        paired [true]
389   -isPrimaryAlignment <true/false>  keep only alignments marked as primary
390                                        [true]
391   -isProperPair <true/false>        keep only alignments that passed paired-end
392                                        resolution [true]
393   -isReverseStrand <true/false>     keep only alignments on reverse strand
394                                        [true]
395   -isSecondMate <true/false>        keep only alignments marked as second mate
396                                        [true]
397
398 Help:
399   --help, -h                        shows this help text
400
401   *****************
402   * Filter Script *
403   *****************
404
405 The BamTools filter tool allows you to use an external filter script to define
406 complex filtering behavior.  This script uses what I'm calling properties,
407 filters, and a rule - all implemented in a JSON syntax.
408
409   ** Properties **
410
411 A 'property' is a typical JSON entry of the form:
412
413     "propertyName" : "value"
414
415 Here are the property names that BamTools will recognize:
416
417     alignmentFlag
418     cigar
419     insertSize
420     isDuplicate
421     isFailedQC
422     isFirstMate
423     isMapped
424     isMateMapped
425     isMateReverseStrand
426     isPaired
427     isPrimaryAlignment
428     isProperPair
429     isReverseStrand
430     isSecondMate
431     mapQuality
432     matePosition
433     mateReference
434     name
435     position
436     queryBases
437     reference
438     tag
439
440 For properties with boolean values, use the words "true" or "false".
441 For example,
442
443    "isMapped" : "true"
444
445 will keep only alignments that are flagged as 'mapped'.
446
447 For properties with numeric values, use the desired number with optional
448 comparison operators ( >, >=, <, <=, !). For example,
449
450     "mapQuality" : ">=75"
451
452 will keep only alignments with mapQuality greater than or equal to 75.
453
454 If you're familiar with JSON, you know that integers can be bare (without
455 quotes). However, if you a comparison operator, be sure to enclose in quotes.
456
457 For string-based properties, the above operators are available.  In addition,
458  you can also use some basic pattern-matching operators.  For example,
459
460     "reference" : "ALU*"  // reference starts with 'ALU'
461     "name" : "*foo"       // name ends with 'foo'
462     "cigar" : "*D*"       // cigar contains a 'D' anywhere
463
464 Notes -
465 The reference property refers to the reference name, not the BAM reference
466 numeric ID.
467
468 The tag property has an extra layer, so that the syntax will look like this:
469
470     "tag" : "XX:value"
471
472 where XX is the 2-letter SAM/BAM tag and value is, well, the value.
473 Comparison operators can still apply to values, so tag properties of:
474
475     "tag" : "AS:>60"
476     "tag" : "RG:foo*"
477
478 are perfectly valid.
479
480  ** Filters **
481
482 A 'filter' is a JSON container of properties that will be AND-ed together. For
483 example,
484
485 {
486    "reference" : "chr1",
487    "mapQuality" : ">50",
488    "tag" : "NM:<4"
489 }
490
491 would result in an output BAM file containing only alignments from chr1 with a
492 mapQuality >50 and edit distance of less than 4.
493
494 A single, unnamed filter like this is the minimum necessary for a complete
495 filter script.  Save this file and use as the -script parameter and you should
496 be all set.
497
498 Moving on to more potent filtering...
499
500 You can also define multiple filters.
501 To do so, you just need to use the "filters" keyword along with JSON array
502 syntax, like this:
503
504 {
505    "filters" :
506       [
507         {
508           "reference" : "chr1",
509           "mapQuality" : ">50"
510         },
511         {
512           "reference" : "chr1",
513           "isReverseStrand" : "true"
514         }
515       ]
516 }
517
518 These filters will be (inclusive) OR-ed together by default. So you'd get a
519 resulting BAM with only alignments from chr1 that had either mapQuality >50 or
520 on the reverse strand (or both).
521
522  ** Rule **
523
524 Alternatively to anonymous OR-ed filters, you can also provide what I've called
525 a "rule". By giving each filter an "id", using this "rule" keyword you can
526 describe boolean relationships between your filter sets.
527
528 Available rule operators:
529
530     &   // and
531     |   // or
532     !   // not
533
534 This might sound a little fuzzy at this point, so let's get back to an example:
535
536 {
537    "filters" :
538       [
539         {
540           "id" : "filter1",
541           "reference" : "chr1",
542           "mapQuality" : ">50"
543         },
544         {
545           "id" : "filter2",
546           "reference" : "chr1",
547           "isReverseStrand" : "true"
548         },
549         {
550           "id" : "filter3",
551           "reference" : "chr1",
552           "queryBases" : "AGCT*"
553         }
554       ],
555
556    "rule" : " (filter1 | filter2) & !filter3 "
557 }
558
559 In this case, we would only retain aligments that passed filter 1 OR filter 2,
560 AND also NOT filter 3.
561
562 These are dummy examples, and don't make much sense as an actual query case. But
563 hopefully this serves an adequate primer to get you started and discover the
564 potential flexibility here.
565
566 ----------
567 header
568 ----------
569
570 Description: prints header from BAM file(s).
571
572 Usage: bamtools header [-in <filename> -in <filename> ...]
573
574 Input & Output:
575   -in <BAM filename>                the input BAM file(s) [stdin]
576
577 Help:
578   --help, -h                        shows this help text
579
580 ----------
581 index
582 ----------
583
584 Description: creates index for BAM file.
585
586 Usage: bamtools index [-in <filename>] [-bti]
587
588 Input & Output:
589   -in <BAM filename>                the input BAM file [stdin]
590   -bti                              create (non-standard) BamTools index file
591                                        (*.bti). Default behavior is to create
592                                        standard BAM index (*.bai)
593
594 Help:
595   --help, -h                        shows this help tex
596
597 ----------
598 merge
599 ----------
600
601 Description: merges multiple BAM files into one.
602
603 Usage: bamtools merge [-in <filename> -in <filename> ...]
604                       [-out <filename> | [-forceCompression]] [-region <REGION>]
605
606 Input & Output:
607   -in <BAM filename>                the input BAM file(s)
608   -out <BAM filename>               the output BAM file
609   -forceCompression                 if results are sent to stdout (like when
610                                        piping to another tool), default behavior
611                                        is to leave output uncompressed. Use this
612                                        flag to override and force compression
613   -region <REGION>                  genomic region. See README for more details
614
615 Help:
616   --help, -h                        shows this help text
617
618 ----------
619 random
620 ----------
621
622 Description: grab a random subset of alignments.
623
624 Usage: bamtools random [-in <filename> -in <filename> ...]
625                        [-out <filename>] [-forceCompression] [-n]
626                        [-region <REGION>]
627
628 Input & Output:
629   -in <BAM filename>                the input BAM file [stdin]
630   -out <BAM filename>               the output BAM file [stdout]
631   -forceCompression                 if results are sent to stdout (like when
632                                        piping to another tool), default behavior
633                                        is to leave output uncompressed. Use this
634                                        flag to override and force compression
635   -region <REGION>                  only pull random alignments from within this
636                                        genomic region. Index file is
637                                        recommended for better performance, and
638                                        is used automatically if it exists. See
639                                        'bamtools help index' for more details
640                                        on creating one
641
642 Settings:
643   -n <count>                        number of alignments to grab. Note that no
644                                        duplicate checking is performed [10000]
645
646 Help:
647   --help, -h                        shows this help text
648
649 ----------
650 sort
651 ----------
652
653 Description: sorts a BAM file.
654
655 Usage: bamtools sort [-in <filename>] [-out <filename>] [sortOptions]
656
657 Input & Output:
658   -in <BAM filename>                the input BAM file [stdin]
659   -out <BAM filename>               the output BAM file [stdout]
660
661 Sorting Methods:
662   -byname                           sort by alignment name
663
664 Memory Settings:
665   -n <count>                        max number of alignments per tempfile
666                                        [10000]
667   -mem <Mb>                         max memory to use [1024]
668
669 Help:
670   --help, -h                        shows this help text
671
672 ----------
673 split
674 ----------
675
676 Description: splits a BAM file on user-specified property, creating a new BAM
677 output file for each value found.
678
679 Usage: bamtools split [-in <filename>] [-stub <filename stub>]
680                       < -mapped | -paired | -reference | -tag <TAG> >
681
682 Input & Output:
683   -in <BAM filename>                the input BAM file [stdin]
684   -stub <filename stub>             prefix stub for output BAM files (default
685                                        behavior is to use input filename,
686                                        without .bam extension, as stub). If
687                                        input is stdin and no stub provided, a
688                                        timestamp is generated as the stub.
689
690 Split Options:
691   -mapped                           split mapped/unmapped alignments
692   -paired                           split single-end/paired-end alignments
693   -reference                        split alignments by reference
694   -tag <tag name>                   splits alignments based on all values of TAG
695                                        encountered (i.e. -tag RG creates a BAM
696                                        file for each read group in original
697                                        BAM file)
698
699 Help:
700   --help, -h                        shows this help text
701
702 ----------
703 stats
704 ----------
705
706 Description: prints general alignment statistics.
707
708 Usage: bamtools stats [-in <filename> -in <filename> ...] [statsOptions]
709
710 Input & Output:
711   -in <BAM filename>                the input BAM file [stdin]
712
713 Additional Stats:
714   -insert                           summarize insert size data
715
716 Help:
717   --help, -h                        shows this help text
718
719 --------------------------------------------------------------------------------
720 III. License :
721 --------------------------------------------------------------------------------
722
723 Both the BamTools API and toolkit are released under the MIT License.
724 Copyright (c) 2009-2010 Derek Barnett, Erik Garrison, Gabor Marth,
725     Michael Stromberg
726
727 See included file LICENSE for details.
728
729 --------------------------------------------------------------------------------
730 IV. Acknowledgements :
731 --------------------------------------------------------------------------------
732
733  * Aaron Quinlan for several key feature ideas and bug fix contributions
734  * Baptiste Lepilleur for the public-domain JSON parser (JsonCPP)
735  * Heng Li, author of SAMtools - the original C-language BAM API/toolkit.
736
737 --------------------------------------------------------------------------------
738 V. Contact :
739 --------------------------------------------------------------------------------
740
741 Feel free to contact me with any questions, comments, suggestions, bug reports,
742     etc.
743
744 Derek Barnett
745 Marth Lab
746 Biology Dept., Boston College
747
748 Email: barnetde@bc.edu
749 Project Websites: http://github.com/pezmaster31/bamtools   (ACTIVE SUPPORT)
750                   http://sourceforge.net/projects/bamtools (major updates only)