// ***************************************************************************\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: 18 September 2010 (DB)\r
+// Last modified: 18 November 2012 (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
#define BAMREADER_H\r
\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
-#include "BamAlignment.h"\r
\r
namespace BamTools {\r
\r
-class BamReader {\r
+namespace Internal {\r
+ class BamReaderPrivate;\r
+} // namespace Internal\r
+\r
+class API_EXPORT BamReader {\r
\r
// constructor / destructor\r
public:\r
// BAM file operations\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
+ // 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 for an existing index file\r
- // @preferStandardIndex - if true, give priority in index file searching to standard BAM index\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
- // attempts a Jump() to left bound as well\r
- // returns success/failure of Jump()\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
- \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 (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 auxiliary data\r
+ // access header data\r
// ----------------------\r
\r
- // returns SAM header text\r
- const std::string GetHeaderText(void) const;\r
- // returns number of reference sequences\r
+ // returns a read-only reference to SAM header data\r
+ const SamHeader& GetConstSamHeader(void) const;\r
+ // returns an editable copy of 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 reference data\r
+ // ----------------------\r
+\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
+ // 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
+\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