// BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
// Marth Lab, Department of Biology, Boston College
// ---------------------------------------------------------------------------
-// Last modified: 15 March 2011 (DB)
+// Last modified: 10 October 2011 (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 <api/BamMultiReader.h>
-#include <api/internal/BamMultiReader_p.h>
+#include "api/BamMultiReader.h"
+#include "api/internal/BamMultiReader_p.h"
using namespace BamTools;
#include <string>
#include <vector>
using namespace std;
-/*! \class BamTools::BamReader
+/*! \class BamTools::BamMultiReader
\brief Convenience class for reading multiple BAM files.
*/
\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)
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()
*/
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.
/*! \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.
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(), SetRegion(), BamReader::GetNextAlignment()
*/
bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
return d->GetNextAlignment(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(), SetRegion(), BamReader::GetNextAlignmentCore()
*/
bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
return d->GetNextAlignmentCore(nextAlignment);
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 {
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()
*/
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
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()
*/
/*! \fn bool BamMultiReader::Open(const std::vector<std::string>& 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()
*/
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()
*/
/*! \fn bool BamMultiReader::OpenIndexes(const std::vector<std::string>& 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()
*/
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.
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()
-*/
-void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) {
- d->SetIndexCacheMode(mode);
-}
-
/*! \fn bool BamMultiReader::SetRegion(const BamRegion& region)
\brief Sets a target region of interest
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()
*/
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()
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) );
}