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: 5 April 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 (hypothetical) BTI_1_2 would 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                  };
 100
 101     // ctor & dtor
 102     public:
 103         BamToolsIndex(Internal::BamReaderPrivate* reader);
 104         ~BamToolsIndex(void);
 105
 106     // BamIndex implementation
 107     public:
 108         // builds index from associated BAM file & writes out to index file
 109         bool Create(void);
 110         // returns whether reference has alignments or no
 111         bool HasAlignments(const int& referenceID) const;
 112         // attempts to use index data to jump to @region, returns success/fail
 113         // a "successful" jump indicates no error, but not whether this region has data
 114         //   * thus, the method sets a flag to indicate whether there are alignments
 115         //     available after the jump position
 116         bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion);
 117         // loads existing data from file into memory
 118         bool Load(const std::string& filename);
 119         // change the index caching behavior
 120         void SetCacheMode(const BamIndex::IndexCacheMode& mode);
 121     public:
 122         // returns format's file extension
 123         static const std::string Extension(void);
 124
 125     // internal file ops
 126     private:
 127         bool CheckMagicNumber(void);
 128         bool CheckVersion(void);
 129         void CloseFile(void);
 130         bool IsFileOpen(void) const;
 131         bool OpenFile(const std::string& filename, const char* mode);
 132         bool Seek(const int64_t& position, const int& origin);
 133         int64_t Tell(void) const;
 134
 135     // internal BTI index building methods
 136     private:
 137         void ClearReferenceEntry(BtiReferenceEntry& refEntry);
 138
 139     // internal random-access methods
 140     private:
 141         bool GetOffset(const BamRegion& region, int64_t& offset, bool* hasAlignmentsInRegion);
 142
 143     // internal BTI summary data methods
 144     private:
 145         void InitializeFileSummary(const int& numReferences);
 146         bool LoadFileSummary(void);
 147         bool LoadHeader(void);
 148         bool LoadNumBlocks(int& numBlocks);
 149         bool LoadNumReferences(int& numReferences);
 150         bool LoadReferenceSummary(BtiReferenceSummary& refSummary);
 151         bool SkipBlocks(const int& numBlocks);
 152
 153     // internal BTI full index input methods
 154     private:
 155         bool ReadBlock(BtiBlock& block);
 156         bool ReadBlocks(const BtiReferenceSummary& refSummary, BtiBlockVector& blocks);
 157         bool ReadReferenceEntry(BtiReferenceEntry& refEntry);
 158
 159     // internal BTI full index output methods
 160     private:
 161         bool WriteBlock(const BtiBlock& block);
 162         bool WriteBlocks(const BtiBlockVector& blocks);
 163         bool WriteHeader(void);
 164         bool WriteReferenceEntry(const BtiReferenceEntry& refEntry);
 165
 166     // data members
 167     private:
 168         FILE* m_indexStream;
 169         bool  m_isBigEndian;
 170         BamIndex::IndexCacheMode m_cacheMode;
 171         BtiFileSummary m_indexFileSummary;
 172         int m_blockSize;
 173         int32_t m_inputVersion; // Version is serialized as int
 174         Version m_outputVersion;
 175
 176     // static constants
 177     private:
 178         static const int 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