Removed index cache mode

[bamtools.git] / src / api / BamMultiReader.cpp

diff --git a/src/api/BamMultiReader.cpp b/src/api/BamMultiReader.cpp
index d0315688ef4ef3595854ef751b3c92ac19b72533..ef38469651c292e49fdbfec9317cc903791c24f3 100644 (file)
--- a/src/api/BamMultiReader.cpp
+++ b/src/api/BamMultiReader.cpp
@@ -2,7 +2,7 @@
 // BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
 // BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------

-// Last modified: 8 October 2011 (DB)
+// Last modified: 10 October 2011 (DB)

 // ---------------------------------------------------------------------------
 // Convenience class for reading multiple BAM files.
 //
 // ---------------------------------------------------------------------------
 // Convenience class for reading multiple BAM files.
 //


@@ -12,15 +12,15 @@
 // precludes the need to sort merged files.
 // ***************************************************************************
 
 // 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;
 
 using namespace BamTools;
 
 #include <string>
 #include <vector>
 using namespace std;
 

-/*! \class BamTools::BamReader
+/*! \class BamTools::BamMultiReader

     \brief Convenience class for reading multiple BAM files.
 */
 
     \brief Convenience class for reading multiple BAM files.
 */
 


@@ -55,6 +55,8 @@ bool BamMultiReader::Close(void) {
 
     Leaves any other file(s) open, along with header and reference data.
 
 
     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()
 */
 bool BamMultiReader::CloseFile(const std::string& filename) {
     \sa Close(), IsOpen(), Open(), BamReader::Close()
 */
 bool BamMultiReader::CloseFile(const std::string& filename) {


@@ -64,7 +66,7 @@ bool BamMultiReader::CloseFile(const std::string& filename) {
 /*! \fn bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type)
     \brief Creates index files for the current BAM files.
 
 /*! \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 \c true if index files created OK
     \sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()
 */


@@ -86,7 +88,14 @@ const std::vector<std::string> BamMultiReader::Filenames(void) const {
     return d->Filenames();
 }
 
     return d->Filenames();
 }
 

-// returns a description of the last error that occurred
+/*! \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();
 }
 std::string BamMultiReader::GetErrorString(void) const {
     return d->GetErrorString();
 }


@@ -94,8 +103,8 @@ std::string BamMultiReader::GetErrorString(void) const {
 /*! \fn SamHeader BamMultiReader::GetHeader(void) const
     \brief Returns unified SAM-format header for all files
 
 /*! \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.
 
     your modified header text can be used in conjunction with BamWriter
     to generate a new BAM file with the appropriate header information.
 


@@ -109,8 +118,8 @@ SamHeader BamMultiReader::GetHeader(void) const {
 /*! \fn std::string BamMultiReader::GetHeaderText(void) const
     \brief Returns unified SAM-format header text for all files
 
 /*! \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.
 
     your modified header text can be used in conjunction with BamWriter
     to generate a new BAM file with the appropriate header information.
 


@@ -128,11 +137,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'
     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
     \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);
 */
 bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
     return d->GetNextAlignment(nextAlignment);


@@ -145,11 +154,11 @@ bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
     overlapping alignment and what data gets populated.
 
     This method takes care of determining which alignment actually is 'next'
     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
     \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);
 */
 bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
     return d->GetNextAlignmentCore(nextAlignment);


@@ -176,6 +185,7 @@ const BamTools::RefVector BamMultiReader::GetReferenceData(void) const {
 
     If \a refName is not found, returns -1.
 
 
     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 {
     \sa BamReader::GetReferenceID()
 */
 int BamMultiReader::GetReferenceID(const std::string& refName) const {


@@ -203,6 +213,9 @@ bool BamMultiReader::HasOpenReaders(void) const {
     This is a convenience method, equivalent to calling SetRegion()
     with only a left boundary specified.
 
     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()
 */
     \returns \c true if jump was successful
     \sa HasIndex(), BamReader::Jump()
 */


@@ -225,16 +238,15 @@ bool BamMultiReader::Jump(int refID, int position) {
 
     An example case would look this:
     \code
 
     An example case would look this:
     \code

-

         BamMultiReader reader;
         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
 
         // 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
 
 
     \endcode
 


@@ -242,7 +254,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.
 
     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()
 */
     \returns \c true if index files could be found for \b ALL open BAM files
     \sa BamReader::LocateIndex()
 */


@@ -253,11 +265,11 @@ bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType) {
 /*! \fn bool BamMultiReader::Open(const std::vector<std::string>& filenames)
     \brief Opens BAM files.
 
 /*! \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()
 */
     \returns \c true if BAM files were opened successfully
     \sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()
 */


@@ -270,11 +282,11 @@ bool BamMultiReader::Open(const std::vector<std::string>& filenames) {
 
     Adds another BAM file to multireader "on-the-fly".
 
 
     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()
 */
     \returns \c true if BAM file was opened successfully
     \sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()
 */


@@ -285,10 +297,10 @@ bool BamMultiReader::OpenFile(const std::string& filename) {
 /*! \fn bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames)
     \brief Opens index files for current BAM files.
 
 /*! \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().
 
     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()
 */
     \returns \c true if BAM index file was opened & data loaded successfully
     \sa LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()
 */


@@ -309,25 +321,16 @@ bool BamMultiReader::Rewind(void) {
     return d->Rewind();
 }
 
     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.
 
 /*! \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()
 */
     \returns \c true if ALL readers set the region successfully
     \sa HasIndexes(), Jump(), BamReader::SetRegion()
 */


@@ -341,14 +344,16 @@ bool BamMultiReader::SetRegion(const BamRegion& region) {
                                        const int& rightPosition)
     \brief Sets a target region of interest
 
                                        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()
 
     \returns \c true if ALL readers set the region successfully
     \sa HasIndexes(), Jump(), BamReader::SetRegion()