X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FBamMultiReader.cpp;h=57c826daa80ccd5368bc0cde3c7254d1f417f496;hb=574a2bfb36f7107529e7ccda0f75e70a493460e5;hp=854345193b3a3f51bfcd393c3543e7d49565c2ea;hpb=72f5b82ad353b4cc9d6f8153f1ad19cc387b9597;p=bamtools.git diff --git a/src/api/BamMultiReader.cpp b/src/api/BamMultiReader.cpp index 8543451..57c826d 100644 --- a/src/api/BamMultiReader.cpp +++ b/src/api/BamMultiReader.cpp @@ -2,28 +2,40 @@ // BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett // Marth Lab, Department of Biology, Boston College // --------------------------------------------------------------------------- -// Last modified: 15 March 2011 (DB) +// Last modified: 14 January 2013 (DB) // --------------------------------------------------------------------------- // Convenience class for reading multiple BAM files. // // This functionality allows applications to work on very large sets of files // without requiring intermediate merge, sort, and index steps for each file -// subset. It also improves the performance of our merge system as it +// subset. It also improves the performance of our merge system as it // precludes the need to sort merged files. // *************************************************************************** -#include -#include +#include "api/BamMultiReader.h" +#include "api/internal/bam/BamMultiReader_p.h" using namespace BamTools; #include #include using namespace std; -/*! \class BamTools::BamReader +/*! \class BamTools::BamMultiReader \brief Convenience class for reading multiple BAM files. */ +/*! \enum BamMultiReader::MergeOrder + \brief A description of the enum type. +*/ +/*! \var BamMultiReader::MergeOrder BamMultiReader::MergeByCoordinate + \brief The description of the first enum value. +*/ +/*! \var BamMultiReader::MergeOrder BamMultiReader::MergeByName + \brief BAM files are +*/ + + + /*! \fn BamMultiReader::BamMultiReader(void) \brief constructor */ @@ -46,8 +58,8 @@ BamMultiReader::~BamMultiReader(void) { \sa CloseFile(), IsOpen(), Open(), BamReader::Close() */ -void BamMultiReader::Close(void) { - d->Close(); +bool BamMultiReader::Close(void) { + return d->Close(); } /*! \fn void BamMultiReader::CloseFile(const std::string& filename) @@ -55,16 +67,18 @@ void BamMultiReader::Close(void) { Leaves any other file(s) open, along with header and reference data. + \param[in] filename name of specific BAM file to close + \sa Close(), IsOpen(), Open(), BamReader::Close() */ -void BamMultiReader::CloseFile(const std::string& filename) { - d->CloseFile(filename); +bool BamMultiReader::CloseFile(const std::string& filename) { + return d->CloseFile(filename); } /*! \fn bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type) \brief Creates index files for the current BAM files. - \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 files created OK \sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex() */ @@ -86,11 +100,23 @@ const std::vector BamMultiReader::Filenames(void) const { return d->Filenames(); } +/*! \fn std::string BamMultiReader::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 +*/ +std::string BamMultiReader::GetErrorString(void) const { + return d->GetErrorString(); +} + /*! \fn SamHeader BamMultiReader::GetHeader(void) const \brief Returns unified SAM-format header for all files - N.B. - Modifying the retrieved text does NOT affect the current - BAM files. Thesse file have been opened in a read-only mode. However, + \note Modifying the retrieved text does NOT affect the current + BAM files. These files have 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. @@ -104,8 +130,8 @@ SamHeader BamMultiReader::GetHeader(void) const { /*! \fn std::string BamMultiReader::GetHeaderText(void) const \brief Returns unified SAM-format header text for all files - N.B. - Modifying the retrieved text does NOT affect the current - BAM files. Thesse file have been opened in a read-only mode. However, + \note Modifying the retrieved text does NOT affect the current + BAM files. These files have 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. @@ -116,6 +142,16 @@ std::string BamMultiReader::GetHeaderText(void) const { return d->GetHeaderText(); } +/*! \fn BamMultiReader::MergeOrder BamMultiReader::GetMergeOrder(void) const + \brief Returns curent merge order strategy. + + \returns current merge order enum value + \sa BamMultiReader::MergeOrder, SetExplicitMergeOrder() +*/ +BamMultiReader::MergeOrder BamMultiReader::GetMergeOrder(void) const { + return d->GetMergeOrder(); +} + /*! \fn bool BamMultiReader::GetNextAlignment(BamAlignment& alignment) \brief Retrieves next available alignment. @@ -123,11 +159,11 @@ std::string BamMultiReader::GetHeaderText(void) const { overlapping alignment and what data gets populated. This method takes care of determining which alignment actually is 'next' - across multiple files, depending on current SortOrder. + across multiple files, depending on their sort order. - \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 GetNextAlignmentCore(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignment() + \sa GetNextAlignmentCore(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignment() */ bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) { return d->GetNextAlignment(nextAlignment); @@ -140,11 +176,11 @@ bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) { overlapping alignment and what data gets populated. This method takes care of determining which alignment actually is 'next' - across multiple files, depending on current SortOrder. + across multiple files, depending on their sort order. - \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 GetNextAlignment(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignmentCore() + \sa GetNextAlignment(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignmentCore() */ bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) { return d->GetNextAlignmentCore(nextAlignment); @@ -171,6 +207,7 @@ const BamTools::RefVector BamMultiReader::GetReferenceData(void) const { If \a refName is not found, returns -1. + \param[in] refName name of reference to look up \sa BamReader::GetReferenceID() */ int BamMultiReader::GetReferenceID(const std::string& refName) const { @@ -192,25 +229,15 @@ bool BamMultiReader::HasOpenReaders(void) const { return d->HasOpenReaders(); } -/*! \fn bool BamMultiReader::IsIndexLoaded(void) const - \brief Returns \c true if all BAM files have index data available. - - \deprecated Instead use HasIndexes() - \cond - See explanation in BamReader.cpp for more details on the deprecation decision. - \endcond -*/ - -bool BamMultiReader::IsIndexLoaded(void) const { - return d->HasIndexes(); -} - /*! \fn bool BamMultiReader::Jump(int refID, int position) \brief Performs a random-access jump within current BAM files. This is a convenience method, equivalent to calling SetRegion() with only a left boundary specified. + \param[in] refID ID of reference to jump to + \param[in] position (0-based) left boundary + \returns \c true if jump was successful \sa HasIndex(), BamReader::Jump() */ @@ -233,16 +260,15 @@ bool BamMultiReader::Jump(int refID, int position) { An example case would look this: \code - BamMultiReader reader; - // do setup + + // do setup... // ensure that all files have an index if ( !reader.LocateIndexes() ) // opens any existing index files that match our BAM files - reader.CreateIndexes(); // creates index files for BAM files that still lack one + reader.CreateIndexes(); // creates index files for any BAM files that still lack one - // do interesting stuff - // ... + // do interesting stuff using random-access... \endcode @@ -250,7 +276,7 @@ bool BamMultiReader::Jump(int refID, int position) { with the desired index filenames. If that function returns false, you can use CreateIndexes() to then build index files 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 index files could be found for \b ALL open BAM files \sa BamReader::LocateIndex() */ @@ -261,11 +287,11 @@ bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType) { /*! \fn bool BamMultiReader::Open(const std::vector& filenames) \brief Opens BAM files. - N.B. - Opening BAM files will invalidate any current region set on the multireader. - All file pointers will be returned to the beginning of the alignment data. - Follow this with Jump() or SetRegion() to establish a region of interest. + \note Opening BAM files will invalidate any current region set on the multireader. + All file pointers will be returned to the beginning of the alignment data. Follow + this with Jump() or SetRegion() to establish a region of interest. - \param filenames list of BAM filenames to open + \param[in] filenames list of BAM filenames to open \returns \c true if BAM files were opened successfully \sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open() */ @@ -278,11 +304,11 @@ bool BamMultiReader::Open(const std::vector& filenames) { Adds another BAM file to multireader "on-the-fly". - N.B. - Opening a BAM file invalidates any current region set on the multireader. - All file pointers will be returned to the beginning of the alignment data. - Follow this with Jump() or SetRegion() to establish a region of interest. + \note Opening a BAM file will invalidate any current region set on the multireader. + All file pointers will be returned to the beginning of the alignment data. Follow + this with Jump() or SetRegion() to establish a region of interest. - \param filename BAM filename to open + \param[in] filename BAM filename to open \returns \c true if BAM file was opened successfully \sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open() */ @@ -293,10 +319,10 @@ bool BamMultiReader::OpenFile(const std::string& filename) { /*! \fn bool BamMultiReader::OpenIndexes(const std::vector& indexFilenames) \brief Opens index files for current BAM files. - N.B. - Currently assumes that index filenames match the order (and number) of + \note Currently assumes that index filenames match the order (and number) of BAM files passed to Open(). - \param indexFilenames list of BAM index file names + \param[in] indexFilenames list of BAM index file names \returns \c true if BAM index file was opened & data loaded successfully \sa LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex() */ @@ -304,16 +330,6 @@ bool BamMultiReader::OpenIndexes(const std::vector& indexFilenames) return d->OpenIndexes(indexFilenames); } -/*! \fn void BamMultiReader::PrintFilenames(void) const - \brief Convenience method for printing filenames to stdout. - \deprecated Doesn't really belong as an API function. Clients should - determine how the data is reported. - \sa Filenames(), BamReader::GetFilename() -*/ -void BamMultiReader::PrintFilenames(void) const { - d->PrintFilenames(); -} - /*! \fn bool BamMultiReader::Rewind(void) \brief Returns the internal file pointers to the beginning of alignment records. @@ -327,17 +343,32 @@ bool BamMultiReader::Rewind(void) { return d->Rewind(); } -/*! \fn void BamMultiReader::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(), BamReader::SetIndexCacheMode() +/*! \fn void BamMultiReader::SetExplicitMergeOrder(BamMultiReader::MergeOrder order) + \brief Sets an explicit merge order, regardless of the BAM files' SO header tag. + + The default behavior of the BamMultiReader is to check the SO tag in the BAM files' + SAM header text to determine the merge strategy". The merge strategy is used to + determine from which BAM file the next alignment should come when either + GetNextAlignment() or GetNextAlignmentCore() are called. If files share a + 'coordinate' or 'queryname' value for this tag, then the merge strategy is + selected accordingly. If any of them do not match, or if any fileis marked as + 'unsorted', then the merge strategy is simply a round-robin. + + This method allows client code to explicitly override the lookup behavior. This + method can be useful when you know, for example, that your BAM files are sorted + by coordinate but upstream processes did not set the header tag properly. + + \note This method should \bold not be called while reading alignments via + GetNextAlignment() or GetNextAlignmentCore(). For proper results, you should + call this method before (or immediately after) opening files, rewinding, + jumping, etc. but \bold not once alignment fetching has started. There is + nothing in the API to prevent you from doing so, but the results may be + unexpected. + + \sa BamMultiReader::MergeOrder, GetMergeOrder(), GetNextAlignment(), GetNextAlignmentCore() */ -void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) { - d->SetIndexCacheMode(mode); +void BamMultiReader::SetExplicitMergeOrder(BamMultiReader::MergeOrder order) { + d->SetExplicitMergeOrder(order); } /*! \fn bool BamMultiReader::SetRegion(const BamRegion& region) @@ -345,7 +376,11 @@ void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) { Equivalent to calling BamReader::SetRegion() on all open BAM files. - \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 ALL readers set the region successfully \sa HasIndexes(), Jump(), BamReader::SetRegion() */ @@ -359,14 +394,16 @@ bool BamMultiReader::SetRegion(const BamRegion& region) { const int& rightPosition) \brief Sets a target region of interest - This is an overloaded function. + This is an overloaded function. Equivalent to calling BamReader::SetRegion() on all open BAM files. - Equivalent to calling BamReader::SetRegion() on all open BAM files. + \warning This function now 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 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 + \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 ALL readers set the region successfully \sa HasIndexes(), Jump(), BamReader::SetRegion() @@ -376,20 +413,5 @@ bool BamMultiReader::SetRegion(const int& leftRefID, const int& rightRefID, const int& rightPosition) { - BamRegion region(leftRefID, leftPosition, rightRefID, rightPosition); - return d->SetRegion(region); -} - -/*! \fn void BamMultiReader::SetSortOrder(const SortOrder& order) - \brief Sets the expected sorting order for reading across multiple BAM files. - - Default is BamMultiReader::SortedByPosition. - - The SortOrder determines how the reader determines which alignment is "next" - from among its open readers. - - \param order expected sort order -*/ -void BamMultiReader::SetSortOrder(const SortOrder& order) { - d->SetSortOrder(order); + return d->SetRegion( BamRegion(leftRefID, leftPosition, rightRefID, rightPosition) ); }