X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamReader.cpp;h=c4f043221b5d85765488406647cf681a2ec8ba7e;hb=HEAD;hp=19dd135e7704b844b6ef46a2fb568c1dedf1df90;hpb=2e049ed7f28881bce09653e60f5aea54bfd7afbf;p=bamtools.git diff --git a/src/api/BamReader.cpp b/src/api/BamReader.cpp index 19dd135..c4f0432 100644 --- a/src/api/BamReader.cpp +++ b/src/api/BamReader.cpp @@ -2,13 +2,13 @@ // BamReader.cpp (c) 2009 Derek Barnett, Michael Str�mberg // Marth Lab, Department of Biology, Boston College // --------------------------------------------------------------------------- -// Last modified: 7 October 2011 (DB) +// Last modified: 29 July 2013 (DB) // --------------------------------------------------------------------------- // Provides read access to BAM files. // *************************************************************************** -#include -#include +#include "api/BamReader.h" +#include "api/internal/bam/BamReader_p.h" using namespace BamTools; using namespace BamTools::Internal; @@ -53,7 +53,7 @@ bool BamReader::Close(void) { /*! \fn bool BamReader::CreateIndex(const BamIndex::IndexType& type) \brief Creates an index file for current BAM file. - \param type file format to create, see BamIndex::IndexType for available formats + \param[in] type file format to create, see BamIndex::IndexType for available formats \return \c true if index created OK \sa LocateIndex(), OpenIndex() */ @@ -61,6 +61,30 @@ bool BamReader::CreateIndex(const BamIndex::IndexType& type) { return d->CreateIndex(type); } +/*! \fn const SamHeader& BamReader::GetConstSamHeader(void) const + \brief Returns const reference to SAM header data. + + Allows for read-only queries of SAM header data. + + If you do not need to modify the SAM header, use this method to avoid the + potentially expensive copy used by GetHeader(). + + \note + \returns const reference to header data object + \sa GetHeader(), GetHeaderText() +*/ +const SamHeader& BamReader::GetConstSamHeader(void) const { + return d->GetConstSamHeader(); +} + +/*! \fn std::string BamReader::GetErrorString(void) const + \brief Returns a human-readable description of the last error that occurred + + This method allows elimination of STDERR pollution. Developers of client code + may choose how the messages are displayed to the user, if at all. + + \return error description +*/ string BamReader::GetErrorString(void) const { return d->GetErrorString(); } @@ -82,15 +106,16 @@ const std::string BamReader::GetFilename(void) const { /*! \fn SamHeader BamReader::GetHeader(void) const \brief Returns SAM header data. - Header data is wrapped in a SamHeader object that can be conveniently queried & modified. + Header data is wrapped in a SamHeader object that can be conveniently queried and/or modified. + If you only need read access, consider using GetConstSamHeader() instead. - N.B. - Modifying the retrieved SamHeader object does NOT affect the + \note Modifying the retrieved SamHeader object does NOT affect the current BAM file. This file has been opened in a read-only mode. However, your modified SamHeader object can be used in conjunction with BamWriter to generate a new BAM file with the appropriate header information. \returns header data object - \sa GetHeaderText() + \sa GetConstSamHeader(), GetHeaderText() */ SamHeader BamReader::GetHeader(void) const { return d->GetSamHeader(); @@ -99,7 +124,7 @@ SamHeader BamReader::GetHeader(void) const { /*! \fn std::string BamReader::GetHeaderText(void) const \brief Returns SAM header data, as SAM-formatted text. - N.B. - Modifying the retrieved text does NOT affect the current + \note Modifying the retrieved text does NOT affect the current BAM file. This file has been opened in a read-only mode. However, your modified header text can be used in conjunction with BamWriter to generate a new BAM file with the appropriate header information. @@ -132,7 +157,7 @@ std::string BamReader::GetHeaderText(void) const { are required, consider using GetNextAlignmentCore() for a significant performance boost. - \param alignment destination for alignment record data + \param[out] alignment destination for alignment record data \returns \c true if a valid alignment was found */ bool BamReader::GetNextAlignment(BamAlignment& alignment) { @@ -146,10 +171,10 @@ bool BamReader::GetNextAlignment(BamAlignment& alignment) { However, this method does NOT populate the alignment's string data fields (read name, bases, qualities, tags, filename). This provides a boost in speed - when these fields are not required for every alignment. These fields can be - populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later. + when these fields are not required for every alignment. These fields, excluding filename, + can be populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later. - \param alignment destination for alignment record data + \param[out] alignment destination for alignment record data \returns \c true if a valid alignment was found \sa SetRegion() */ @@ -176,6 +201,8 @@ const RefVector& BamReader::GetReferenceData(void) const { \brief Returns the ID of the reference with this name. If \a refName is not found, returns -1. + + \param[in] refName name of reference to look up */ int BamReader::GetReferenceID(const std::string& refName) const { return d->GetReferenceID(refName); @@ -188,25 +215,6 @@ bool BamReader::HasIndex(void) const { return d->HasIndex(); } -/*! \fn bool BamReader::IsIndexLoaded(void) const - \brief Returns \c true if index data is available. - - \deprecated Instead use HasIndex() - \cond - Deprecated purely for API semantic clarity - HasIndex() should be clearer - than IsIndexLoaded() in light of the new caching modes that may clear the - index data from memory, but leave the index file open for later random access - seeks. - - For example, what would (IsIndexLoaded() == true) mean when cacheMode has been - explicitly set to NoIndexCaching? This is confusing at best, misleading about - current memory behavior at worst. - \endcond -*/ -bool BamReader::IsIndexLoaded(void) const { - return d->HasIndex(); -} - /*! \fn bool BamReader::IsOpen(void) const \brief Returns \c true if a BAM file is open for reading. */ @@ -220,6 +228,9 @@ bool BamReader::IsOpen(void) const { This is a convenience method, equivalent to calling SetRegion() with only a left boundary specified. + \param[in] refID left-bound reference ID + \param[in] position left-bound position + \returns \c true if jump was successful \sa HasIndex() */ @@ -242,7 +253,8 @@ bool BamReader::Jump(int refID, int position) { with the desired index filename. If that function returns false, you can use CreateIndex() to then build an index of the exact requested format. - \param preferredType desired index file format, see BamIndex::IndexType for available formats + \param[in] preferredType desired index file format, see BamIndex::IndexType for available formats + \returns \c true if (any) index file could be found */ bool BamReader::LocateIndex(const BamIndex::IndexType& preferredType) { @@ -255,7 +267,8 @@ bool BamReader::LocateIndex(const BamIndex::IndexType& preferredType) { If BamReader is already opened on another file, this function closes that file, then attempts to open requested \a filename. - \param filename name of BAM file to open + \param[in] filename name of BAM file to open + \returns \c true if BAM file was opened successfully \sa Close(), IsOpen(), OpenIndex() */ @@ -266,7 +279,7 @@ bool BamReader::Open(const std::string& filename) { /*! \fn bool BamReader::OpenIndex(const std::string& indexFilename) \brief Opens a BAM index file. - \param indexFilename name of BAM index file + \param[in] indexFilename name of BAM index file to open \returns \c true if BAM index file was opened & data loaded successfully \sa LocateIndex(), Open(), SetIndex() @@ -281,7 +294,7 @@ bool BamReader::OpenIndex(const std::string& indexFilename) { Useful for performing multiple sequential passes through a BAM file. Calling this function clears any prior region that may have been set. - N.B. - Note that this function sets the file pointer to first alignment record + \note This function sets the file pointer to first alignment record in the BAM file, NOT the beginning of the file. \returns \c true if rewind operation was successful @@ -303,30 +316,17 @@ bool BamReader::Rewind(void) { reader.SetIndex(new MyCustomBamIndex); \endcode - N.B. - BamReader takes ownership of \a index - i.e. BamReader will - take care of deleting the pointer when the reader is destructed, - when the current BAM file is closed, or when a new index is requested. + \note BamReader takes ownership of \a index - i.e. the BamReader will + take care of deleting it when the reader is destructed, when the current + BAM file is closed, or when a new index is requested. - \param index custom BamIndex subclass created by client + \param[in] index custom BamIndex subclass created by client \sa CreateIndex(), LocateIndex(), OpenIndex() */ void BamReader::SetIndex(BamIndex* index) { d->SetIndex(index); } -/*! \fn void BamReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) - \brief Changes the caching behavior of the index data. - - Default mode is BamIndex::LimitedIndexCaching. - - \param mode desired cache mode for index, see BamIndex::IndexCacheMode for - description of the available cache modes - \sa HasIndex() -*/ -void BamReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) { - d->SetIndexCacheMode(mode); -} - /*! \fn bool BamReader::SetRegion(const BamRegion& region) \brief Sets a target region of interest @@ -341,7 +341,12 @@ void BamReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) { that all alignments that lie downstream of the left boundary are considered valid, continuing to the end of the BAM file. - \param region desired region-of-interest to activate + \warning BamRegion now represents a zero-based, HALF-OPEN interval. + In previous versions of BamTools (0.x & 1.x) all intervals were treated + as zero-based, CLOSED. + + \param[in] region desired region-of-interest to activate + \returns \c true if reader was able to jump successfully to the region's left boundary \sa HasIndex(), Jump() */ @@ -357,10 +362,14 @@ bool BamReader::SetRegion(const BamRegion& region) { This is an overloaded function. - \param leftRefID referenceID of region's left boundary - \param leftPosition position of region's left boundary - \param rightRefID reference ID of region's right boundary - \param rightPosition position of region's right boundary + \warning This function expects a zero-based, HALF-OPEN interval. + In previous versions of BamTools (0.x & 1.x) all intervals were treated + as zero-based, CLOSED. + + \param[in] leftRefID referenceID of region's left boundary + \param[in] leftPosition position of region's left boundary + \param[in] rightRefID reference ID of region's right boundary + \param[in] rightPosition position of region's right boundary \returns \c true if reader was able to jump successfully to the region's left boundary \sa HasIndex(), Jump()