X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamIndex.h;h=067244ec2d2fd845458d7868dbee553771388be7;hb=2e1822c9ed231b25fd474117a01a1492d4209fa4;hp=b9ce7d03121b34f8fdb3c2640fe689c41b0954ec;hpb=0180d7256f5c781364b04559b39ed2db41585787;p=bamtools.git diff --git a/src/api/BamIndex.h b/src/api/BamIndex.h index b9ce7d0..067244e 100644 --- a/src/api/BamIndex.h +++ b/src/api/BamIndex.h @@ -1,120 +1,93 @@ // *************************************************************************** // BamIndex.h (c) 2009 Derek Barnett // Marth Lab, Department of Biology, Boston College -// All rights reserved. // --------------------------------------------------------------------------- -// Last modified: 17 August 2010 (DB) +// Last modified: 6 October 2011 (DB) // --------------------------------------------------------------------------- -// Provides index functionality - both for the default (standardized) BAM -// index format (.bai) as well as a BamTools-specific (nonstandard) index -// format (.bti). +// Provides basic BAM index interface // *************************************************************************** #ifndef BAM_INDEX_H #define BAM_INDEX_H +#include +#include #include -#include -#include "BamAux.h" namespace BamTools { -class BamReader; -class BgzfData; - -// -------------------------------------------------- -// BamIndex base class -class BamIndex { +namespace Internal { + class BamReaderPrivate; +} // namespace Internal - public: - BamIndex(BamTools::BgzfData* bgzf, - BamTools::BamReader* reader, - bool isBigEndian); - virtual ~BamIndex(void) { } +/*! \class BamTools::BamIndex + \brief Provides methods for generating & loading BAM index files. - public: - // creates index data (in-memory) from current reader data - virtual bool Build(void) =0; - // calculates offset(s) for a given region - virtual bool GetOffsets(const BamTools::BamRegion& region, const bool isRightBoundSpecified, std::vector& offsets) =0; - // loads existing data from file into memory - virtual bool Load(const std::string& filename) =0; - // returns whether reference has alignments or no - virtual bool HasAlignments(const int& referenceID); - // writes in-memory index data out to file - // N.B. - (this is the original BAM filename, method will modify it to use applicable extension) - virtual bool Write(const std::string& bamFilename) =0; - - protected: - BamTools::BgzfData* m_BGZF; - BamTools::BamReader* m_reader; - BamTools::RefVector m_references; - bool m_isBigEndian; -}; + This class straddles the line between public API and internal + implementation detail. Most client code should never have to use this + class directly. + + It is exposed to the public API to allow advanced users to implement + their own custom indexing schemes. + + More documentation on methods & enums coming soon. +*/ -// -------------------------------------------------- -// BamDefaultIndex class -// -// implements default (per SAM/BAM spec) index file ops -class BamDefaultIndex : public BamIndex { +class API_EXPORT BamIndex { + // enums + public: + // specify index-caching behavior + enum IndexCacheMode { FullIndexCaching = 0 // store entire index file contents in memory + , LimitedIndexCaching // store only index data for current reference + , NoIndexCaching // do not store any index data between jumps + }; + + // list of supported BamIndex types + enum IndexType { BAMTOOLS = 0 + , STANDARD + }; // ctor & dtor public: - BamDefaultIndex(BamTools::BgzfData* bgzf, - BamTools::BamReader* reader, - bool isBigEndian); - ~BamDefaultIndex(void); + BamIndex(Internal::BamReaderPrivate* reader) : m_reader(reader) { } + virtual ~BamIndex(void) { } - // interface (implements BamIndex virtual methods) + // index interface public: - // creates index data (in-memory) from current reader data - bool Build(void); - // calculates offset(s) for a given region - bool GetOffsets(const BamTools::BamRegion& region, const bool isRightBoundSpecified, std::vector& offsets); - // loads existing data from file into memory - bool Load(const std::string& filename); - // writes in-memory index data out to file - // N.B. - (this is the original BAM filename, method will modify it to use applicable extension) - bool Write(const std::string& bamFilename); - - // internal implementation - private: - struct BamDefaultIndexPrivate; - BamDefaultIndexPrivate* d; -}; + // builds index from associated BAM file & writes out to index file + virtual bool Create(void) =0; -// -------------------------------------------------- -// BamToolsIndex class -// -// implements BamTools-specific index file ops -class BamToolsIndex : public BamIndex { + // returns a human-readable description of the last error encountered + std::string GetErrorString(void) { return m_errorString; } - // ctor & dtor - public: - BamToolsIndex(BamTools::BgzfData* bgzf, - BamTools::BamReader* reader, - bool isBigEndian); - ~BamToolsIndex(void); - - // interface (implements BamIndex virtual methods) - public: - // creates index data (in-memory) from current reader data - bool Build(void); - // calculates offset(s) for a given region - bool GetOffsets(const BamTools::BamRegion& region, const bool isRightBoundSpecified, std::vector& offsets); - // loads existing data from file into memory - bool Load(const std::string& filename); - // writes in-memory index data out to file - // N.B. - (this is the original BAM filename, method will modify it to use applicable extension) - bool Write(const std::string& bamFilename); - - // internal implementation - private: - struct BamToolsIndexPrivate; - BamToolsIndexPrivate* d; + // returns whether reference has alignments or no + virtual bool HasAlignments(const int& referenceID) const =0; + + // attempts to use index data to jump to @region, returns success/fail + // a "successful" jump indicates no error, but not whether this region has data + // * thus, the method sets a flag to indicate whether there are alignments + // available after the jump position + virtual bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion) =0; + + // loads existing data from file into memory + virtual bool Load(const std::string& filename) =0; + + // change the index caching behavior + virtual void SetCacheMode(const BamIndex::IndexCacheMode& mode) =0; + + // internal methods + protected: + void SetErrorString(const std::string& where, const std::string& what) const { + m_errorString = where + ": " + what; + } + + // data members + protected: + Internal::BamReaderPrivate* m_reader; // copy, not owned + mutable std::string m_errorString; }; } // namespace BamTools -#endif // BAM_INDEX_H \ No newline at end of file +#endif // BAM_INDEX_H