annotate spp/src/BamReader.h @ 6:ce08b0efa3fd draft

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