src/api/BamMultiReader.h

   1 // ***************************************************************************
   2 // BamMultiReader.h (c) 2010 Erik Garrison, Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 14 January 2013 (DB)
   6 // ---------------------------------------------------------------------------
   7 // Convenience class for reading multiple BAM files.
   8 // ***************************************************************************
   9
  10 #ifndef BAMMULTIREADER_H
  11 #define BAMMULTIREADER_H
  12
  13 #include "api/api_global.h"
  14 #include "api/BamReader.h"
  15 #include <map>
  16 #include <sstream>
  17 #include <string>
  18 #include <utility>
  19
  20 namespace BamTools {
  21
  22 namespace Internal {
  23     class BamMultiReaderPrivate;
  24 } // namespace Internal
  25
  26 class API_EXPORT BamMultiReader {
  27
  28     // enums
  29     public:
  30         // possible merge order strategies
  31         enum MergeOrder { RoundRobinMerge = 0
  32                         , MergeByCoordinate
  33                         , MergeByName
  34                         };
  35
  36     // constructor / destructor
  37     public:
  38         BamMultiReader(void);
  39         ~BamMultiReader(void);
  40
  41     // public interface
  42     public:
  43
  44         // ----------------------
  45         // BAM file operations
  46         // ----------------------
  47
  48         // closes all open BAM files
  49         bool Close(void);
  50         // close only the requested BAM file
  51         bool CloseFile(const std::string& filename);
  52         // returns list of filenames for all open BAM files
  53         const std::vector<std::string> Filenames(void) const;
  54         // returns curent merge order strategy
  55         BamMultiReader::MergeOrder GetMergeOrder(void) const;
  56         // returns true if multireader has any open BAM files
  57         bool HasOpenReaders(void) const;
  58         // performs random-access jump within current BAM files
  59         bool Jump(int refID, int position = 0);
  60         // opens BAM files
  61         bool Open(const std::vector<std::string>& filenames);
  62         // opens a single BAM file, adding to any other current BAM files
  63         bool OpenFile(const std::string& filename);
  64         // returns file pointers to beginning of alignments
  65         bool Rewind(void);
  66         // sets an explicit merge order, regardless of the BAM files' SO header tag
  67         void SetExplicitMergeOrder(BamMultiReader::MergeOrder order);
  68         // sets the target region of interest
  69         bool SetRegion(const BamRegion& region);
  70         // sets the target region of interest
  71         bool SetRegion(const int& leftRefID,
  72                        const int& leftPosition,
  73                        const int& rightRefID,
  74                        const int& rightPosition);
  75
  76         // ----------------------
  77         // access alignment data
  78         // ----------------------
  79
  80         // retrieves next available alignment
  81         bool GetNextAlignment(BamAlignment& alignment);
  82         // retrieves next available alignment (without populating the alignment's string data fields)
  83         bool GetNextAlignmentCore(BamAlignment& alignment);
  84
  85         // ----------------------
  86         // access auxiliary data
  87         // ----------------------
  88
  89         // returns unified SAM header for all files
  90         SamHeader GetHeader(void) const;
  91         // returns unified SAM header text for all files
  92         std::string GetHeaderText(void) const;
  93         // returns number of reference sequences
  94         int GetReferenceCount(void) const;
  95         // returns all reference sequence entries.
  96         const BamTools::RefVector GetReferenceData(void) const;
  97         // returns the ID of the reference with this name.
  98         int GetReferenceID(const std::string& refName) const;
  99
 100         // ----------------------
 101         // BAM index operations
 102         // ----------------------
 103
 104         // creates index files for current BAM files
 105         bool CreateIndexes(const BamIndex::IndexType& type = BamIndex::STANDARD);
 106         // returns true if all BAM files have index data available
 107         bool HasIndexes(void) const;
 108         // looks for index files that match current BAM files
 109         bool LocateIndexes(const BamIndex::IndexType& preferredType = BamIndex::STANDARD);
 110         // opens index files for current BAM files.
 111         bool OpenIndexes(const std::vector<std::string>& indexFilenames);
 112
 113         // ----------------------
 114         // error handling
 115         // ----------------------
 116
 117         // returns a human-readable description of the last error that occurred
 118         std::string GetErrorString(void) const;
 119
 120     // private implementation
 121     private:
 122         Internal::BamMultiReaderPrivate* d;
 123 };
 124
 125 } // namespace BamTools
 126
 127 #endif // BAMMULTIREADER_H