|
6
|
1 // ***************************************************************************
|
|
|
2 // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg
|
|
|
3 // Marth Lab, Department of Biology, Boston College
|
|
|
4 // All rights reserved.
|
|
|
5 // ---------------------------------------------------------------------------
|
|
|
6 // Last modified: 19 November 2010 (DB)
|
|
|
7 // ---------------------------------------------------------------------------
|
|
|
8 // Provides the basic functionality for reading BAM files
|
|
|
9 // ***************************************************************************
|
|
|
10
|
|
|
11 #ifndef BAMREADER_H
|
|
|
12 #define BAMREADER_H
|
|
|
13
|
|
|
14 #include <api_global.h>
|
|
|
15 #include <BamAlignment.h>
|
|
|
16 #include <BamIndex.h>
|
|
|
17 #include <string>
|
|
|
18
|
|
|
19 namespace BamTools {
|
|
|
20
|
|
|
21 namespace Internal {
|
|
|
22 class BamReaderPrivate;
|
|
|
23 } // namespace Internal
|
|
|
24
|
|
|
25 class API_EXPORT BamReader {
|
|
|
26
|
|
|
27 // constructor / destructor
|
|
|
28 public:
|
|
|
29 BamReader(void);
|
|
|
30 ~BamReader(void);
|
|
|
31
|
|
|
32 // public interface
|
|
|
33 public:
|
|
|
34
|
|
|
35 // ----------------------
|
|
|
36 // BAM file operations
|
|
|
37 // ----------------------
|
|
|
38
|
|
|
39 // close BAM file
|
|
|
40 void Close(void);
|
|
|
41 // returns whether reader is open for reading or not
|
|
|
42 bool IsOpen(void) const;
|
|
|
43 // performs random-access jump using (reference, position) as a left-bound
|
|
|
44 bool Jump(int refID, int position = 0);
|
|
|
45 // opens BAM file (and optional BAM index file, if provided)
|
|
|
46 // @lookForIndex - if no indexFilename provided, look in BAM file's directory for an existing index file
|
|
|
47 // default behavior is to skip index file search if no index filename given
|
|
|
48 // @preferStandardIndex - if true, give priority in index file searching to standard BAM index (*.bai)
|
|
|
49 // default behavior is to prefer the BamToolsIndex (*.bti) if both are available
|
|
|
50 bool Open(const std::string& filename,
|
|
|
51 const std::string& indexFilename = "",
|
|
|
52 const bool lookForIndex = false,
|
|
|
53 const bool preferStandardIndex = false);
|
|
|
54 // returns file pointer to beginning of alignments
|
|
|
55 bool Rewind(void);
|
|
|
56 // sets a region of interest (with left & right bound reference/position)
|
|
|
57 // returns success/failure of seeking to left bound of region
|
|
|
58 bool SetRegion(const BamRegion& region);
|
|
|
59 bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound);
|
|
|
60
|
|
|
61 // ----------------------
|
|
|
62 // access alignment data
|
|
|
63 // ----------------------
|
|
|
64
|
|
|
65 // retrieves next available alignment (returns success/fail)
|
|
|
66 bool GetNextAlignment(BamAlignment& bAlignment);
|
|
|
67 // retrieves next available alignment core data (returns success/fail)
|
|
|
68 // ** DOES NOT parse any character data (read name, bases, qualities, tag data) **
|
|
|
69 // useful for operations requiring ONLY aligner-related information
|
|
|
70 // (refId/position, alignment flags, CIGAR, mapQuality, etc)
|
|
|
71 bool GetNextAlignmentCore(BamAlignment& bAlignment);
|
|
|
72
|
|
|
73 // ----------------------
|
|
|
74 // access auxiliary data
|
|
|
75 // ----------------------
|
|
|
76
|
|
|
77 // returns SAM header text
|
|
|
78 const std::string GetHeaderText(void) const;
|
|
|
79 // returns number of reference sequences
|
|
|
80 int GetReferenceCount(void) const;
|
|
|
81 // returns vector of reference objects
|
|
|
82 const BamTools::RefVector& GetReferenceData(void) const;
|
|
|
83 // returns reference id (used for BamReader::Jump()) for the given reference name
|
|
|
84 int GetReferenceID(const std::string& refName) const;
|
|
|
85 // returns the name of the file associated with this BamReader
|
|
|
86 const std::string GetFilename(void) const;
|
|
|
87
|
|
|
88 // ----------------------
|
|
|
89 // BAM index operations
|
|
|
90 // ----------------------
|
|
|
91
|
|
|
92 // creates index for BAM file, saves to file
|
|
|
93 // default behavior is to create the BAM standard index (".bai")
|
|
|
94 // set flag to false to create the BamTools-specific index (".bti")
|
|
|
95 bool CreateIndex(bool useStandardIndex = true);
|
|
|
96 // returns whether index data is available for reading
|
|
|
97 // (e.g. if true, BamReader should be able to seek to a region)
|
|
|
98 bool HasIndex(void) const;
|
|
|
99 // change the index caching behavior
|
|
|
100 // default BamReader/Index mode is LimitedIndexCaching
|
|
|
101 // @mode - can be either FullIndexCaching, LimitedIndexCaching,
|
|
|
102 // or NoIndexCaching. See BamIndex.h for more details
|
|
|
103 void SetIndexCacheMode(const BamIndex::BamIndexCacheMode mode);
|
|
|
104
|
|
|
105 // deprecated methods
|
|
|
106 public:
|
|
|
107
|
|
|
108 // deprecated (but still available): prefer HasIndex() instead
|
|
|
109 //
|
|
|
110 // Deprecated purely for API semantic clarity - HasIndex() should be clearer
|
|
|
111 // than IsIndexLoaded() in light of the new caching modes that may clear the
|
|
|
112 // index data from memory, but leave the index file open for later random access
|
|
|
113 // seeks.
|
|
|
114 //
|
|
|
115 // For example, what would (IsIndexLoaded() == true) mean when cacheMode has been
|
|
|
116 // explicitly set to NoIndexCaching? This is confusing at best, misleading about
|
|
|
117 // current memory behavior at worst.
|
|
|
118 //
|
|
|
119 // returns whether index data is available
|
|
|
120 // (e.g. if true, BamReader should be able to seek to a region)
|
|
|
121 bool IsIndexLoaded(void) const;
|
|
|
122
|
|
|
123 // private implementation
|
|
|
124 private:
|
|
|
125 Internal::BamReaderPrivate* d;
|
|
|
126 };
|
|
|
127
|
|
|
128 } // namespace BamTools
|
|
|
129
|
|
|
130 #endif // BAMREADER_H
|
