src/api/internal/index/BamToolsIndex_p.h

   1 // ***************************************************************************
   2 // BamToolsIndex.h (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 10 October 2011 (DB)
   6 // ---------------------------------------------------------------------------
   7 // Provides index operations for the BamTools index format (".bti")
   8 // ***************************************************************************
   9
  10 #ifndef BAMTOOLS_INDEX_FORMAT_H
  11 #define BAMTOOLS_INDEX_FORMAT_H
  12
  13 //  -------------
  14 //  W A R N I N G
  15 //  -------------
  16 //
  17 // This file is not part of the BamTools API.  It exists purely as an
  18 // implementation detail.  This header file may change from version to
  19 // version without notice, or even be removed.
  20 //
  21 // We mean it.
  22
  23 #include "api/BamAux.h"
  24 #include "api/BamIndex.h"
  25 #include "api/IBamIODevice.h"
  26 #include <map>
  27 #include <string>
  28 #include <vector>
  29
  30 namespace BamTools {
  31 namespace Internal {
  32
  33 // contains data for each 'block' in a BTI index
  34 struct BtiBlock {
  35
  36     // data members
  37     int32_t MaxEndPosition;
  38     int64_t StartOffset;
  39     int32_t StartPosition;
  40
  41     // ctor
  42     BtiBlock(const int32_t& maxEndPosition = 0,
  43              const int64_t& startOffset    = 0,
  44              const int32_t& startPosition  = 0)
  45         : MaxEndPosition(maxEndPosition)
  46         , StartOffset(startOffset)
  47         , StartPosition(startPosition)
  48     { }
  49 };
  50
  51 // convenience typedef for describing a a list of BTI blocks on a reference
  52 typedef std::vector<BtiBlock> BtiBlockVector;
  53
  54 // contains all fields necessary for building, loading, & writing
  55 // full BTI index data for a single reference
  56 struct BtiReferenceEntry {
  57
  58     // data members
  59     int32_t ID;
  60     BtiBlockVector Blocks;
  61
  62     // ctor
  63     BtiReferenceEntry(const int& id = -1)
  64         : ID(id)
  65     { }
  66 };
  67
  68 // provides (persistent) summary of BtiReferenceEntry's index data
  69 struct BtiReferenceSummary {
  70
  71     // data members
  72     int NumBlocks;
  73     uint64_t FirstBlockFilePosition;
  74
  75     // ctor
  76     BtiReferenceSummary(void)
  77         : NumBlocks(0)
  78         , FirstBlockFilePosition(0)
  79     { }
  80 };
  81
  82 // convenience typedef for describing a full BTI index file summary
  83 typedef std::vector<BtiReferenceSummary> BtiFileSummary;
  84
  85 class BamToolsIndex : public BamIndex {
  86
  87     // keep a list of any supported versions here
  88     // (might be useful later to handle any 'legacy' versions if the format changes)
  89     // listed for example like: BTI_1_0 = 1, BTI_1_1 = 2, BTI_1_2 = 3, BTI_2_0 = 4, and so on
  90     //
  91     // so a change introduced in BTI_1_2 may be handled from then on by:
  92     //
  93     // if ( indexVersion >= BTI_1_2 )
  94     //   do something new
  95     // else
  96     //   do the old thing
  97     enum Version { BTI_1_0 = 1
  98                  , BTI_1_1
  99                  , BTI_1_2
 100                  , BTI_2_0
 101                  };
 102
 103     // ctor & dtor
 104     public:
 105         BamToolsIndex(Internal::BamReaderPrivate* reader);
 106         ~BamToolsIndex(void);
 107
 108     // BamIndex implementation
 109     public:
 110         // builds index from associated BAM file & writes out to index file
 111         bool Create(void);
 112         // returns whether reference has alignments or no
 113         bool HasAlignments(const int& referenceID) const;
 114         // attempts to use index data to jump to @region, returns success/fail
 115         // a "successful" jump indicates no error, but not whether this region has data
 116         //   * thus, the method sets a flag to indicate whether there are alignments
 117         //     available after the jump position
 118         bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion);
 119         // loads existing data from file into memory
 120         bool Load(const std::string& filename);
 121     public:
 122         // returns format's file extension
 123         static const std::string Extension(void);
 124
 125     // internal methods
 126     private:
 127
 128         // index file ops
 129         void CheckMagicNumber(void);
 130         void CheckVersion(void);
 131         void CloseFile(void);
 132         bool IsDeviceOpen(void) const;
 133         void OpenFile(const std::string& filename, IBamIODevice::OpenMode mode);
 134         void Seek(const int64_t& position, const int origin);
 135         int64_t Tell(void) const;
 136
 137         // index-creation methods
 138         void ClearReferenceEntry(BtiReferenceEntry& refEntry);
 139         void WriteBlock(const BtiBlock& block);
 140         void WriteBlocks(const BtiBlockVector& blocks);
 141         void WriteHeader(void);
 142         void WriteReferenceEntry(const BtiReferenceEntry& refEntry);
 143
 144         // random-access methods
 145         void GetOffset(const BamRegion& region, int64_t& offset, bool* hasAlignmentsInRegion);
 146         void ReadBlock(BtiBlock& block);
 147         void ReadBlocks(const BtiReferenceSummary& refSummary, BtiBlockVector& blocks);
 148         void ReadReferenceEntry(BtiReferenceEntry& refEntry);
 149
 150         // BTI summary data methods
 151         void InitializeFileSummary(const int& numReferences);
 152         void LoadFileSummary(void);
 153         void LoadHeader(void);
 154         void LoadNumBlocks(int& numBlocks);
 155         void LoadNumReferences(int& numReferences);
 156         void LoadReferenceSummary(BtiReferenceSummary& refSummary);
 157         void SkipBlocks(const int& numBlocks);
 158
 159     // data members
 160     private:
 161         bool  m_isBigEndian;
 162         BtiFileSummary m_indexFileSummary;
 163         uint32_t m_blockSize;
 164         int32_t m_inputVersion; // Version is serialized as int
 165         Version m_outputVersion;
 166
 167         struct RaiiWrapper {
 168             FILE* IndexStream;
 169             IBamIODevice* Device;
 170             RaiiWrapper(void);
 171             ~RaiiWrapper(void);
 172         };
 173         RaiiWrapper m_resources;
 174
 175     // static constants
 176     private:
 177         static const uint32_t DEFAULT_BLOCK_LENGTH;
 178         static const std::string BTI_EXTENSION;
 179         static const char* const BTI_MAGIC;
 180         static const int SIZEOF_BLOCK;
 181 };
 182
 183 } // namespace Internal
 184 } // namespace BamTools
 185
 186 #endif // BAMTOOLS_INDEX_FORMAT_H