src/api/internal/BamToolsIndex_p.h

   1 // ***************************************************************************
   2 // BamToolsIndex.h (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // All rights reserved.
   5 // ---------------------------------------------------------------------------
   6 // Last modified: 5 April 2011 (DB)
   7 // ---------------------------------------------------------------------------
   8 // Provides index operations for the BamTools index format (".bti")
   9 // ***************************************************************************
  10
  11 #ifndef BAMTOOLS_INDEX_FORMAT_H
  12 #define BAMTOOLS_INDEX_FORMAT_H
  13
  14 //  -------------
  15 //  W A R N I N G
  16 //  -------------
  17 //
  18 // This file is not part of the BamTools API.  It exists purely as an
  19 // implementation detail.  This header file may change from version to
  20 // version without notice, or even be removed.
  21 //
  22 // We mean it.
  23
  24 #include <api/BamAux.h>
  25 #include <api/BamIndex.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 (hypothetical) BTI_1_2 would 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                  };
 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 file ops
 127     private:
 128         bool CheckMagicNumber(void);
 129         bool CheckVersion(void);
 130         void CloseFile(void);
 131         bool IsFileOpen(void) const;
 132         bool OpenFile(const std::string& filename, const char* mode);
 133         bool Seek(const int64_t& position, const int& origin);
 134         int64_t Tell(void) const;
 135
 136     // internal BTI index building methods
 137     private:
 138         void ClearReferenceEntry(BtiReferenceEntry& refEntry);
 139
 140     // internal random-access methods
 141     private:
 142         bool GetOffset(const BamRegion& region, int64_t& offset, bool* hasAlignmentsInRegion);
 143
 144     // internal BTI summary data methods
 145     private:
 146         void InitializeFileSummary(const int& numReferences);
 147         bool LoadFileSummary(void);
 148         bool LoadHeader(void);
 149         bool LoadNumBlocks(int& numBlocks);
 150         bool LoadNumReferences(int& numReferences);
 151         bool LoadReferenceSummary(BtiReferenceSummary& refSummary);
 152         bool SkipBlocks(const int& numBlocks);
 153
 154     // internal BTI full index input methods
 155     private:
 156         bool ReadBlock(BtiBlock& block);
 157         bool ReadBlocks(const BtiReferenceSummary& refSummary, BtiBlockVector& blocks);
 158         bool ReadReferenceEntry(BtiReferenceEntry& refEntry);
 159
 160     // internal BTI full index output methods
 161     private:
 162         bool WriteBlock(const BtiBlock& block);
 163         bool WriteBlocks(const BtiBlockVector& blocks);
 164         bool WriteHeader(void);
 165         bool WriteReferenceEntry(const BtiReferenceEntry& refEntry);
 166
 167     // data members
 168     private:
 169         FILE* m_indexStream;
 170         bool  m_isBigEndian;
 171         BamIndex::IndexCacheMode m_cacheMode;
 172         BtiFileSummary m_indexFileSummary;
 173         int m_blockSize;
 174         int32_t m_inputVersion; // Version is serialized as int
 175         Version m_outputVersion;
 176
 177     // static constants
 178     private:
 179         static const int DEFAULT_BLOCK_LENGTH;
 180         static const std::string BTI_EXTENSION;
 181         static const char* const BTI_MAGIC;
 182         static const int SIZEOF_BLOCK;
 183 };
 184
 185 } // namespace Internal
 186 } // namespace BamTools
 187
 188 #endif // BAMTOOLS_INDEX_FORMAT_H