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 // ***************************************************************************
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"
32 // contains data for each 'block' in a BTI index
36 int32_t MaxEndPosition;
38 int32_t StartPosition;
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)
50 // convenience typedef for describing a a list of BTI blocks on a reference
51 typedef std::vector<BtiBlock> BtiBlockVector;
53 // contains all fields necessary for building, loading, & writing
54 // full BTI index data for a single reference
55 struct BtiReferenceEntry {
59 BtiBlockVector Blocks;
62 BtiReferenceEntry(const int& id = -1)
67 // provides (persistent) summary of BtiReferenceEntry's index data
68 struct BtiReferenceSummary {
72 uint64_t FirstBlockFilePosition;
75 BtiReferenceSummary(void)
77 , FirstBlockFilePosition(0)
81 // convenience typedef for describing a full BTI index file summary
82 typedef std::vector<BtiReferenceSummary> BtiFileSummary;
84 class BamToolsIndex : public BamIndex {
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
90 // so a change introduced in BTI_1_2 may be handled from then on by:
92 // if ( indexVersion >= BTI_1_2 )
96 enum Version { BTI_1_0 = 1
104 BamToolsIndex(Internal::BamReaderPrivate* reader);
105 ~BamToolsIndex(void);
107 // BamIndex implementation
109 // builds index from associated BAM file & writes out to index file
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 BamIndex::IndexType Type(void) const { return BamIndex::BAMTOOLS; }
122 // returns format's file extension
123 static const std::string Extension(void);
129 void CheckMagicNumber(void);
130 void CheckVersion(void);
131 void CloseFile(void);
132 bool IsFileOpen(void) const;
133 void OpenFile(const std::string& filename, const char* mode);
134 void Seek(const int64_t& position, const int& origin);
135 int64_t Tell(void) const;
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);
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);
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);
162 BtiFileSummary m_indexFileSummary;
163 uint32_t m_blockSize;
164 int32_t m_inputVersion; // Version is serialized as int
165 Version m_outputVersion;
172 RaiiWrapper Resources;
176 static const uint32_t DEFAULT_BLOCK_LENGTH;
177 static const std::string BTI_EXTENSION;
178 static const char* const BTI_MAGIC;
179 static const int SIZEOF_BLOCK;
182 } // namespace Internal
183 } // namespace BamTools
185 #endif // BAMTOOLS_INDEX_FORMAT_H