src/api/BamReader.h

   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
  10 \r
  11 #ifndef BAMREADER_H\r
  12 #define BAMREADER_H\r
  13 \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
  18 #include <string>\r
  19 \r
  20 namespace BamTools {\r
  21   \r
  22 namespace Internal {\r
  23     class BamReaderPrivate;\r
  24 } // namespace Internal\r
  25 \r
  26 class API_EXPORT BamReader {\r
  27 \r
  28     // constructor / destructor\r
  29     public:\r
  30         BamReader(void);\r
  31         ~BamReader(void);\r
  32 \r
  33     // public interface\r
  34     public:\r
  35 \r
  36         // ----------------------\r
  37         // BAM file operations\r
  38         // ----------------------\r
  39 \r
  40         // close BAM file\r
  41         void Close(void);\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
  56         bool Rewind(void);\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
  61 \r
  62         // ----------------------\r
  63         // access alignment data\r
  64         // ----------------------\r
  65 \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
  73 \r
  74         // ----------------------\r
  75         // access auxiliary data\r
  76         // ----------------------\r
  77 \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
  90 \r
  91         // ----------------------\r
  92         // BAM index operations\r
  93         // ----------------------\r
  94 \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
 107         \r
 108     // deprecated methods\r
 109     public:\r
 110         \r
 111         // deprecated (but still available): prefer HasIndex() instead\r
 112         //\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
 116         // seeks.\r
 117         //\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
 121         //\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
 125         \r
 126     // private implementation\r
 127     private:\r
 128         Internal::BamReaderPrivate* d;\r
 129 };\r
 130 \r
 131 } // namespace BamTools\r
 132 \r
 133 #endif // BAMREADER_H\r