src/api/BamMultiReader.h

   1 // ***************************************************************************\r
   2 // BamMultiReader.h (c) 2010 Erik Garrison, Derek Barnett\r
   3 // Marth Lab, Department of Biology, Boston College\r
   4 // All rights reserved.\r
   5 // ---------------------------------------------------------------------------\r
   6 // Last modified: 19 November 2010 (DB)\r
   7 // ---------------------------------------------------------------------------\r
   8 // Functionality for simultaneously reading multiple BAM files\r
   9 // ***************************************************************************\r
  10 \r
  11 #ifndef BAMMULTIREADER_H\r
  12 #define BAMMULTIREADER_H\r
  13 \r
  14 #include <api/api_global.h>\r
  15 #include <api/BamReader.h>\r
  16 #include <map>\r
  17 #include <sstream>\r
  18 #include <string>\r
  19 #include <utility>\r
  20 \r
  21 namespace BamTools {\r
  22 \r
  23 // index mapping reference/position pairings to bamreaders and their alignments\r
  24 typedef std::multimap<std::pair<int, int>, std::pair<BamReader*, BamAlignment*> > AlignmentIndex;\r
  25 \r
  26 class API_EXPORT BamMultiReader {\r
  27 \r
  28     // constructor / destructor\r
  29     public:\r
  30         BamMultiReader(void);\r
  31         ~BamMultiReader(void);\r
  32 \r
  33     // public interface\r
  34     public:\r
  35 \r
  36         // positioning\r
  37         int CurrentRefID;\r
  38         int CurrentLeft;\r
  39 \r
  40         // region under analysis, specified using SetRegion\r
  41         BamRegion Region;\r
  42 \r
  43         // ----------------------\r
  44         // BAM file operations\r
  45         // ----------------------\r
  46 \r
  47         // close BAM files\r
  48         void Close(void);\r
  49 \r
  50         // opens BAM files (and optional BAM index files, if provided)\r
  51         // @openIndexes - triggers index opening, useful for suppressing\r
  52         // error messages during merging of files in which we may not have\r
  53         // indexes.\r
  54         // @coreMode - setup our first alignments using GetNextAlignmentCore();\r
  55         // also useful for merging\r
  56         // @preferStandardIndex - look for standard BAM index ".bai" first.  If false, \r
  57         // will look for BamTools index ".bti".  \r
  58         bool Open(const std::vector<std::string>& filenames, bool openIndexes = true, bool coreMode = false, bool preferStandardIndex = false);\r
  59 \r
  60         // returns whether underlying BAM readers ALL have an index loaded\r
  61         // this is useful to indicate whether Jump() or SetRegion() are possible\r
  62         bool IsIndexLoaded(void) const;\r
  63         \r
  64         // performs random-access jump to reference, position\r
  65         bool Jump(int refID, int position = 0);\r
  66 \r
  67         // sets the target region\r
  68         bool SetRegion(const BamRegion& region);\r
  69         bool SetRegion(const int&, const int&, const int&, const int&); // convenience function to above\r
  70 \r
  71         // returns file pointers to beginning of alignments\r
  72         bool Rewind(void);\r
  73 \r
  74         // ----------------------\r
  75         // access alignment data\r
  76         // ----------------------\r
  77         // updates the reference id marker to match the lower limit of our readers\r
  78         void UpdateReferenceID(void);\r
  79 \r
  80         // retrieves next available alignment (returns success/fail) from all files\r
  81         bool GetNextAlignment(BamAlignment&);\r
  82         // retrieves next available alignment (returns success/fail) from all files\r
  83         // and populates the support data with information about the alignment\r
  84         // *** BUT DOES NOT PARSE CHARACTER DATA FROM THE ALIGNMENT\r
  85         bool GetNextAlignmentCore(BamAlignment&);\r
  86         // ... should this be private?\r
  87         bool HasOpenReaders(void);\r
  88 \r
  89         // ----------------------\r
  90         // access auxiliary data\r
  91         // ----------------------\r
  92 \r
  93         // returns unified SAM header text for all files\r
  94         const std::string GetHeaderText(void) const;\r
  95         // returns number of reference sequences\r
  96         const int GetReferenceCount(void) const;\r
  97         // returns vector of reference objects\r
  98         const BamTools::RefVector GetReferenceData(void) const;\r
  99         // returns reference id (used for BamMultiReader::Jump()) for the given reference name\r
 100         const int GetReferenceID(const std::string& refName) const;\r
 101         // validates that we have a congruent set of BAM files that are aligned against the same reference sequences\r
 102         void ValidateReaders() const;\r
 103 \r
 104         // ----------------------\r
 105         // BAM index operations\r
 106         // ----------------------\r
 107 \r
 108         // creates index for BAM files which lack them, saves to files (default = bamFilename + ".bai")\r
 109         bool CreateIndexes(bool useStandardIndex = true);\r
 110 \r
 111         // sets the index caching mode for the readers\r
 112         void SetIndexCacheMode(const BamIndex::BamIndexCacheMode mode);\r
 113 \r
 114         //const int GetReferenceID(const string& refName) const;\r
 115 \r
 116         // utility\r
 117         void PrintFilenames(void);\r
 118         void DumpAlignmentIndex(void);\r
 119         void UpdateAlignments(void); // updates our alignment cache\r
 120 \r
 121     // private implementation\r
 122     private:\r
 123 \r
 124         // the set of readers and alignments which we operate on, maintained throughout the life of this class\r
 125         std::vector<std::pair<BamReader*, BamAlignment*> > readers;\r
 126 \r
 127         // readers and alignments sorted by reference id and position, to keep track of the lowest (next) alignment\r
 128         // when a reader reaches EOF, its entry is removed from this index\r
 129         AlignmentIndex alignments;\r
 130 \r
 131         std::vector<std::string> fileNames;\r
 132 };\r
 133 \r
 134 } // namespace BamTools\r
 135 \r
 136 #endif // BAMMULTIREADER_H\r