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