// Marth Lab, Department of Biology, Boston College\r
// All rights reserved.\r
// ---------------------------------------------------------------------------\r
-// Last modified: 3 September 2010 (DB)\r
+// Last modified: 13 October 2010 (DB)\r
// ---------------------------------------------------------------------------\r
// Uses BGZF routines were adapted from the bgzf.c code developed at the Broad\r
// Institute.\r
#ifndef BAMREADER_H\r
#define BAMREADER_H\r
\r
-// C++ includes\r
#include <string>\r
-\r
-// BamTools includes\r
-#include "BamAux.h"\r
+#include "BamAlignment.h"\r
+#include "BamIndex.h"\r
\r
namespace BamTools {\r
\r
\r
// close BAM file\r
void Close(void);\r
- // returns whether index data is loaded (i.e. reader is able to Jump() or not)\r
- bool IsIndexLoaded(void) const;\r
// returns whether reader is open for reading or not\r
bool IsOpen(void) const;\r
- // performs random-access jump to reference, position\r
+ // performs random-access jump using (reference, position) as a left-bound\r
bool Jump(int refID, int position = 0);\r
// opens BAM file (and optional BAM index file, if provided)\r
- // @lookForIndex - if no indexFilename provided, look for an existing index file\r
- // @preferStandardIndex - if true, give priority in index file searching to standard BAM index\r
+ // @lookForIndex - if no indexFilename provided, look in BAM file's directory for an existing index file\r
+ // default behavior is to skip index file search if no index filename given\r
+ // @preferStandardIndex - if true, give priority in index file searching to standard BAM index (*.bai)\r
+ // default behavior is to prefer the BamToolsIndex (*.bti) if both are available\r
bool Open(const std::string& filename, \r
const std::string& indexFilename = "", \r
const bool lookForIndex = false, \r
// returns file pointer to beginning of alignments\r
bool Rewind(void);\r
// sets a region of interest (with left & right bound reference/position)\r
- // attempts a Jump() to left bound as well\r
- // returns success/failure of Jump()\r
+ // returns success/failure of seeking to left bound of region\r
bool SetRegion(const BamRegion& region);\r
bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound);\r
\r
\r
// retrieves next available alignment (returns success/fail)\r
bool GetNextAlignment(BamAlignment& bAlignment);\r
- \r
// retrieves next available alignment core data (returns success/fail)\r
- // ** DOES NOT parse any character data (read name, bases, qualities, tag data)\r
- // these can be accessed, if necessary, from the supportData \r
- // useful for operations requiring ONLY positional or other alignment-related information\r
+ // ** DOES NOT parse any character data (read name, bases, qualities, tag data) **\r
+ // useful for operations requiring ONLY aligner-related information \r
+ // (refId/position, alignment flags, CIGAR, mapQuality, etc)\r
bool GetNextAlignmentCore(BamAlignment& bAlignment);\r
\r
// ----------------------\r
// default behavior is to create the BAM standard index (".bai")\r
// set flag to false to create the BamTools-specific index (".bti")\r
bool CreateIndex(bool useStandardIndex = true);\r
+ // returns whether index data is available for reading \r
+ // (e.g. if true, BamReader should be able to seek to a region)\r
+ bool HasIndex(void) const;\r
+ // change the index caching behavior\r
+ // default BamReader/Index mode is LimitedIndexCaching\r
+ // @mode - can be either FullIndexCaching, LimitedIndexCaching, \r
+ // or NoIndexCaching. See BamIndex.h for more details\r
+ void SetIndexCacheMode(const BamIndex::BamIndexCacheMode mode);\r
+ \r
+ // deprecated methods\r
+ public:\r
+ \r
+ // deprecated (but still available): prefer HasIndex() instead\r
+ //\r
+ // Deprecated purely for API semantic clarity - HasIndex() should be clearer \r
+ // than IsIndexLoaded() in light of the new caching modes that may clear the \r
+ // index data from memory, but leave the index file open for later random access \r
+ // seeks.\r
+ //\r
+ // For example, what would (IsIndexLoaded() == true) mean when cacheMode has been \r
+ // explicitly set to NoIndexCaching? This is confusing at best, misleading about \r
+ // current memory behavior at worst.\r
+ //\r
+ // returns whether index data is available \r
+ // (e.g. if true, BamReader should be able to seek to a region)\r
+ bool IsIndexLoaded(void) const;\r
\r
// private implementation\r
private:\r