// ***************************************************************************
// 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 <api/api_global.h>
+#include <api/BamAux.h>
#include <string>
-#include <vector>
-#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<int64_t>& 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<int64_t>& 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<int64_t>& 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
projects / bamtools.git / blobdiff