X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamReader.h;h=ce04af65a9edbd364c323dba22acde565dd3ea0c;hb=2e049ed7f28881bce09653e60f5aea54bfd7afbf;hp=c93987b1a41bfbe41b7f0a10bd9d826a3514e681;hpb=0180d7256f5c781364b04559b39ed2db41585787;p=bamtools.git diff --git a/src/api/BamReader.h b/src/api/BamReader.h index c93987b..ce04af6 100644 --- a/src/api/BamReader.h +++ b/src/api/BamReader.h @@ -1,28 +1,28 @@ // *************************************************************************** // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg // Marth Lab, Department of Biology, Boston College -// All rights reserved. // --------------------------------------------------------------------------- -// Last modified: 9 July 2010 (DB) +// Last modified: 7 October 2011 (DB) // --------------------------------------------------------------------------- -// Uses BGZF routines were adapted from the bgzf.c code developed at the Broad -// Institute. -// --------------------------------------------------------------------------- -// Provides the basic functionality for reading BAM files +// Provides read access to BAM files. // *************************************************************************** #ifndef BAMREADER_H #define BAMREADER_H -// C++ includes +#include +#include +#include +#include #include -// BamTools includes -#include "BamAux.h" - namespace BamTools { -class BamReader { +namespace Internal { + class BamReaderPrivate; +} // namespace Internal + +class API_EXPORT BamReader { // constructor / destructor public: @@ -36,61 +36,87 @@ class BamReader { // BAM file operations // ---------------------- - // close BAM file - void Close(void); - // returns whether reader is open for reading or not + // closes the current BAM file + bool Close(void); + // returns filename of current BAM file + const std::string GetFilename(void) const; + // returns true if a BAM file is open for reading bool IsOpen(void) const; - // performs random-access jump to reference, position + // performs random-access jump within BAM file bool Jump(int refID, int position = 0); - // opens BAM file (and optional BAM index file, if provided) - bool Open(const std::string& filename, const std::string& indexFilename = ""); - // returns file pointer to beginning of alignments + // opens a BAM file + bool Open(const std::string& filename); + // returns internal file pointer to beginning of alignment data bool Rewind(void); - // sets a region of interest (with left & right bound reference/position) - // attempts a Jump() to left bound as well - // returns success/failure of Jump() + // sets the target region of interest bool SetRegion(const BamRegion& region); - bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound); + // sets the target region of interest + bool SetRegion(const int& leftRefID, + const int& leftPosition, + const int& rightRefID, + const int& rightPosition); // ---------------------- // access alignment data // ---------------------- - // retrieves next available alignment (returns success/fail) - bool GetNextAlignment(BamAlignment& bAlignment); - - // retrieves next available alignment core data (returns success/fail) - // ** DOES NOT parse any character data (read name, bases, qualities, tag data) - // these can be accessed, if necessary, from the supportData - // useful for operations requiring ONLY positional or other alignment-related information - bool GetNextAlignmentCore(BamAlignment& bAlignment); + // retrieves next available alignment + bool GetNextAlignment(BamAlignment& alignment); + // retrieves next available alignmnet (without populating the alignment's string data fields) + bool GetNextAlignmentCore(BamAlignment& alignment); + + // ---------------------- + // access header data + // ---------------------- + + // returns SAM header data + SamHeader GetHeader(void) const; + // returns SAM header data, as SAM-formatted text + std::string GetHeaderText(void) const; // ---------------------- - // access auxiliary data + // access reference data // ---------------------- - // returns SAM header text - const std::string GetHeaderText(void) const; - // returns number of reference sequences + // returns the number of reference sequences int GetReferenceCount(void) const; - // returns vector of reference objects - const BamTools::RefVector& GetReferenceData(void) const; - // returns reference id (used for BamReader::Jump()) for the given reference name + // returns all reference sequence entries + const RefVector& GetReferenceData(void) const; + // returns the ID of the reference with this name int GetReferenceID(const std::string& refName) const; - // returns the name of the file associated with this BamReader - const std::string GetFilename(void) const; // ---------------------- // BAM index operations // ---------------------- - // creates index for BAM file, saves to file (default = bamFilename + ".bai") - bool CreateIndex(bool useDefaultIndex = true); + // creates an index file for current BAM file, using the requested index type + bool CreateIndex(const BamIndex::IndexType& type = BamIndex::STANDARD); + // returns true if index data is available + bool HasIndex(void) const; + // looks in BAM file's directory for a matching index file + bool LocateIndex(const BamIndex::IndexType& preferredType = BamIndex::STANDARD); + // opens a BAM index file + bool OpenIndex(const std::string& indexFilename); + // sets a custom BamIndex on this reader + void SetIndex(BamIndex* index); + // changes the caching behavior of the index data + void SetIndexCacheMode(const BamIndex::IndexCacheMode& mode); + + // ---------------------- + // error handling + // ---------------------- + + // returns a human-readable description of the last error that occurred + std::string GetErrorString(void) const; + + // deprecated methods + public: + // returns true if index data is available + bool IsIndexLoaded(void) const; // private implementation private: - struct BamReaderPrivate; - BamReaderPrivate* d; + Internal::BamReaderPrivate* d; }; } // namespace BamTools