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: 23 December 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 namespace Internal {\r
  24     class BamMultiReaderPrivate;\r
  25 } // namespace Internal\r
  26 \r
  27 class API_EXPORT BamMultiReader {\r
  28 \r
  29     // constructor / destructor\r
  30     public:\r
  31         BamMultiReader(void);\r
  32         ~BamMultiReader(void);\r
  33 \r
  34     // public interface\r
  35     public:\r
  36 \r
  37         // ----------------------\r
  38         // BAM file operations\r
  39         // ----------------------\r
  40 \r
  41         // close BAM files\r
  42         void Close(void);\r
  43         // opens BAM files (and optional BAM index files, if provided)\r
  44         // @openIndexes - triggers index opening, useful for suppressing\r
  45         // error messages during merging of files in which we may not have\r
  46         // indexes.\r
  47         // @coreMode - setup our first alignments using GetNextAlignmentCore();\r
  48         // also useful for merging\r
  49         // @preferStandardIndex - look for standard BAM index ".bai" first.  If false,\r
  50         // will look for BamTools index ".bti".\r
  51         bool Open(const std::vector<std::string>& filenames,\r
  52                   bool openIndexes = true,\r
  53                   bool coreMode = false,\r
  54                   bool preferStandardIndex = false);\r
  55         // returns whether underlying BAM readers ALL have an index loaded\r
  56         // this is useful to indicate whether Jump() or SetRegion() are possible\r
  57         bool IsIndexLoaded(void) const;\r
  58         // performs random-access jump to reference, position\r
  59         bool Jump(int refID, int position = 0);\r
  60         // list files associated with this multireader\r
  61         void PrintFilenames(void) const;\r
  62         // sets the target region\r
  63         bool SetRegion(const BamRegion& region);\r
  64         bool SetRegion(const int& leftRefID,\r
  65                        const int& leftBound,\r
  66                        const int& rightRefID,\r
  67                        const int& rightBound);\r
  68         // returns file pointers to beginning of alignments\r
  69         bool Rewind(void);\r
  70 \r
  71         // ----------------------\r
  72         // access alignment data\r
  73         // ----------------------\r
  74 \r
  75         // retrieves next available alignment (returns success/fail) from all files\r
  76         bool GetNextAlignment(BamAlignment& alignment);\r
  77         // retrieves next available alignment (returns success/fail) from all files\r
  78         // and populates the support data with information about the alignment\r
  79         // *** BUT DOES NOT PARSE CHARACTER DATA FROM THE ALIGNMENT\r
  80         bool GetNextAlignmentCore(BamAlignment& alignment);\r
  81         // ... should this be private?\r
  82         bool HasOpenReaders(void);\r
  83         // set sort order for merging BAM files (i.e. which alignment from the files is 'next'?)\r
  84         // default behavior is to sort by position, use this method to handle BAMs sorted by read name\r
  85         enum SortOrder { SortedByPosition = 0, SortedByReadName};\r
  86         void SetSortOrder(const SortOrder& order);\r
  87 \r
  88         // ----------------------\r
  89         // access auxiliary data\r
  90         // ----------------------\r
  91 \r
  92         // returns unified SAM header text for all files\r
  93         const std::string GetHeaderText(void) const;\r
  94         // returns number of reference sequences\r
  95         const int GetReferenceCount(void) const;\r
  96         // returns vector of reference objects\r
  97         const BamTools::RefVector GetReferenceData(void) const;\r
  98         // returns reference id (used for BamMultiReader::Jump()) for the given reference name\r
  99         const int GetReferenceID(const std::string& refName) const;\r
 100 \r
 101         // ----------------------\r
 102         // BAM index operations\r
 103         // ----------------------\r
 104 \r
 105         // creates index for BAM files which lack them, saves to files (default = bamFilename + ".bai")\r
 106         bool CreateIndexes(bool useStandardIndex = true);\r
 107         // sets the index caching mode for the readers\r
 108         void SetIndexCacheMode(const BamIndex::BamIndexCacheMode mode);\r
 109 \r
 110     // private implementation\r
 111     private:\r
 112         Internal::BamMultiReaderPrivate* d;\r
 113 };\r
 114 \r
 115 } // namespace BamTools\r
 116 \r
 117 #endif // BAMMULTIREADER_H\r