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 // ***************************************************************************
11 #ifndef BAMTOOLS_INDEX_FORMAT_H
12 #define BAMTOOLS_INDEX_FORMAT_H
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.
24 #include <api/BamAux.h>
25 #include <api/BamIndex.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 (hypothetical) BTI_1_2 would be handled from then on by:
93 // if ( indexVersion >= BTI_1_2 )
97 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 // change the index caching behavior
121 void SetCacheMode(const BamIndex::IndexCacheMode& mode);
123 // returns format's file extension
124 static const std::string Extension(void);
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;
136 // internal BTI index building methods
138 void ClearReferenceEntry(BtiReferenceEntry& refEntry);
140 // internal random-access methods
142 bool GetOffset(const BamRegion& region, int64_t& offset, bool* hasAlignmentsInRegion);
144 // internal BTI summary data methods
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);
154 // internal BTI full index input methods
156 bool ReadBlock(BtiBlock& block);
157 bool ReadBlocks(const BtiReferenceSummary& refSummary, BtiBlockVector& blocks);
158 bool ReadReferenceEntry(BtiReferenceEntry& refEntry);
160 // internal BTI full index output methods
162 bool WriteBlock(const BtiBlock& block);
163 bool WriteBlocks(const BtiBlockVector& blocks);
164 bool WriteHeader(void);
165 bool WriteReferenceEntry(const BtiReferenceEntry& refEntry);
171 BamIndex::IndexCacheMode m_cacheMode;
172 BtiFileSummary m_indexFileSummary;
174 int32_t m_inputVersion; // Version is serialized as int
175 Version m_outputVersion;
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;
185 } // namespace Internal
186 } // namespace BamTools
188 #endif // BAMTOOLS_INDEX_FORMAT_H