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