1 // ***************************************************************************
2 // BamToolsIndex.h (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // ---------------------------------------------------------------------------
5 // Last modified: 10 November 2011 (DB)
6 // ---------------------------------------------------------------------------
7 // Provides index operations for the BamTools index format (".bti")
8 // ***************************************************************************
10 #ifndef BAMTOOLS_INDEX_FORMAT_H
11 #define BAMTOOLS_INDEX_FORMAT_H
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.
23 #include "api/BamAux.h"
24 #include "api/BamIndex.h"
25 #include "api/IBamIODevice.h"
33 // contains data for each 'block' in a BTI index
37 int32_t MaxEndPosition;
39 int32_t StartPosition;
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)
51 // convenience typedef for describing a a list of BTI blocks on a reference
52 typedef std::vector<BtiBlock> BtiBlockVector;
54 // contains all fields necessary for building, loading, & writing
55 // full BTI index data for a single reference
56 struct BtiReferenceEntry {
60 BtiBlockVector Blocks;
63 BtiReferenceEntry(const int& id = -1)
68 // provides (persistent) summary of BtiReferenceEntry's index data
69 struct BtiReferenceSummary {
73 uint64_t FirstBlockFilePosition;
76 BtiReferenceSummary(void)
78 , FirstBlockFilePosition(0)
82 // convenience typedef for describing a full BTI index file summary
83 typedef std::vector<BtiReferenceSummary> BtiFileSummary;
85 class BamToolsIndex : public BamIndex {
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
91 // so a change introduced in BTI_1_2 may be handled from then on by:
93 // if ( indexVersion >= BTI_1_2 )
97 enum Version { BTI_1_0 = 1
105 BamToolsIndex(Internal::BamReaderPrivate* reader);
106 ~BamToolsIndex(void);
108 // BamIndex implementation
110 // builds index from associated BAM file & writes out to index file
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 BamIndex::IndexType Type(void) const { return BamIndex::BAMTOOLS; }
123 // returns format's file extension
124 static const std::string Extension(void);
130 void CheckMagicNumber(void);
131 void CheckVersion(void);
132 void CloseFile(void);
133 bool IsDeviceOpen(void) const;
134 void OpenFile(const std::string& filename, IBamIODevice::OpenMode mode);
135 void Seek(const int64_t& position, const int origin);
136 int64_t Tell(void) const;
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);
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);
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);
163 BtiFileSummary m_indexFileSummary;
164 uint32_t m_blockSize;
165 int32_t m_inputVersion; // Version is serialized as int
166 Version m_outputVersion;
169 IBamIODevice* Device;
173 RaiiWrapper m_resources;
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;
183 } // namespace Internal
184 } // namespace BamTools
186 #endif // BAMTOOLS_INDEX_FORMAT_H