// ***************************************************************************\r
// BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg\r
// Marth Lab, Department of Biology, Boston College\r
-// All rights reserved.\r
// ---------------------------------------------------------------------------\r
-// Last modified: 19 November 2010 (DB)\r
+// Last modified: 7 October 2011 (DB)\r
// ---------------------------------------------------------------------------\r
-// Uses BGZF routines were adapted from the bgzf.c code developed at the Broad\r
-// Institute.\r
-// ---------------------------------------------------------------------------\r
-// Provides the basic functionality for reading BAM files\r
+// Provides read access to BAM files.\r
// ***************************************************************************\r
\r
#ifndef BAMREADER_H\r
#include <api/api_global.h>\r
#include <api/BamAlignment.h>\r
#include <api/BamIndex.h>\r
+#include <api/SamHeader.h>\r
#include <string>\r
\r
namespace BamTools {\r
\r
+namespace Internal {\r
+ class BamReaderPrivate;\r
+} // namespace Internal\r
+\r
class API_EXPORT BamReader {\r
\r
// constructor / destructor\r
// BAM file operations\r
// ----------------------\r
\r
- // close BAM file\r
- void Close(void);\r
- // returns whether reader is open for reading or not\r
+ // closes the current BAM file\r
+ bool Close(void);\r
+ // returns filename of current BAM file\r
+ const std::string GetFilename(void) const;\r
+ // returns true if a BAM file is open for reading\r
bool IsOpen(void) const;\r
- // performs random-access jump using (reference, position) as a left-bound\r
+ // performs random-access jump within BAM file\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 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
- const bool preferStandardIndex = false);\r
- // returns file pointer to beginning of alignments\r
+ // opens a BAM file\r
+ bool Open(const std::string& filename);\r
+ // returns internal file pointer to beginning of alignment data\r
bool Rewind(void);\r
- // sets a region of interest (with left & right bound reference/position)\r
- // returns success/failure of seeking to left bound of region\r
+ // sets the target region of interest\r
bool SetRegion(const BamRegion& region);\r
- bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound);\r
+ // sets the target region of interest\r
+ bool SetRegion(const int& leftRefID,\r
+ const int& leftPosition,\r
+ const int& rightRefID,\r
+ const int& rightPosition);\r
\r
// ----------------------\r
// access alignment data\r
// ----------------------\r
\r
- // retrieves next available alignment (returns success/fail)\r
- bool GetNextAlignment(BamAlignment& bAlignment);\r
- // retrieves next available alignment core data (returns success/fail)\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
+ // retrieves next available alignment\r
+ bool GetNextAlignment(BamAlignment& alignment);\r
+ // retrieves next available alignmnet (without populating the alignment's string data fields)\r
+ bool GetNextAlignmentCore(BamAlignment& alignment);\r
+\r
+ // ----------------------\r
+ // access header data\r
+ // ----------------------\r
+\r
+ // returns SAM header data\r
+ SamHeader GetHeader(void) const;\r
+ // returns SAM header data, as SAM-formatted text\r
+ std::string GetHeaderText(void) const;\r
\r
// ----------------------\r
- // access auxiliary data\r
+ // access reference data\r
// ----------------------\r
\r
- // returns SAM header text\r
- const std::string GetHeaderText(void) const;\r
- // returns number of reference sequences\r
+ // returns the number of reference sequences\r
int GetReferenceCount(void) const;\r
- // returns vector of reference objects\r
- const BamTools::RefVector& GetReferenceData(void) const;\r
- // returns reference id (used for BamReader::Jump()) for the given reference name\r
+ // returns all reference sequence entries\r
+ const RefVector& GetReferenceData(void) const;\r
+ // returns the ID of the reference with this name\r
int GetReferenceID(const std::string& refName) const;\r
- // returns the name of the file associated with this BamReader\r
- const std::string GetFilename(void) const;\r
\r
// ----------------------\r
// BAM index operations\r
// ----------------------\r
\r
- // creates index for BAM file, saves to file\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
+ // creates an index file for current BAM file, using the requested index type\r
+ bool CreateIndex(const BamIndex::IndexType& type = BamIndex::STANDARD);\r
+ // returns true if index data is available\r
+ bool HasIndex(void) const;\r
+ // looks in BAM file's directory for a matching index file\r
+ bool LocateIndex(const BamIndex::IndexType& preferredType = BamIndex::STANDARD);\r
+ // opens a BAM index file\r
+ bool OpenIndex(const std::string& indexFilename);\r
+ // sets a custom BamIndex on this reader\r
+ void SetIndex(BamIndex* index);\r
+ // changes the caching behavior of the index data\r
+ void SetIndexCacheMode(const BamIndex::IndexCacheMode& mode);\r
+\r
+ // ----------------------\r
+ // error handling\r
+ // ----------------------\r
+\r
+ // returns a human-readable description of the last error that occurred\r
+ std::string GetErrorString(void) const;\r
\r
// private implementation\r
private:\r
- struct BamReaderPrivate;\r
- BamReaderPrivate* d;\r
+ Internal::BamReaderPrivate* d;\r
};\r
\r
} // namespace BamTools\r
projects / bamtools.git / blobdiff