src/api/BamMultiReader.cpp

   1 // ***************************************************************************
   2 // BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 7 October 2011 (DB)
   6 // ---------------------------------------------------------------------------
   7 // Convenience class for reading multiple BAM files.
   8 //
   9 // This functionality allows applications to work on very large sets of files
  10 // without requiring intermediate merge, sort, and index steps for each file
  11 // subset. It also improves the performance of our merge system as it
  12 // precludes the need to sort merged files.
  13 // ***************************************************************************
  14
  15 #include <api/BamMultiReader.h>
  16 #include <api/internal/BamMultiReader_p.h>
  17 using namespace BamTools;
  18
  19 #include <string>
  20 #include <vector>
  21 using namespace std;
  22
  23 /*! \class BamTools::BamReader
  24     \brief Convenience class for reading multiple BAM files.
  25 */
  26
  27 /*! \fn BamMultiReader::BamMultiReader(void)
  28     \brief constructor
  29 */
  30 BamMultiReader::BamMultiReader(void)
  31     : d(new Internal::BamMultiReaderPrivate)
  32 { }
  33
  34 /*! \fn BamMultiReader::~BamMultiReader(void)
  35     \brief destructor
  36 */
  37 BamMultiReader::~BamMultiReader(void) {
  38     delete d;
  39     d = 0;
  40 }
  41
  42 /*! \fn void BamMultiReader::Close(void)
  43     \brief Closes all open BAM files.
  44
  45     Also clears out all header and reference data.
  46
  47     \sa CloseFile(), IsOpen(), Open(), BamReader::Close()
  48 */
  49 bool BamMultiReader::Close(void) {
  50     return d->Close();
  51 }
  52
  53 /*! \fn void BamMultiReader::CloseFile(const std::string& filename)
  54     \brief Closes requested BAM file.
  55
  56     Leaves any other file(s) open, along with header and reference data.
  57
  58     \sa Close(), IsOpen(), Open(), BamReader::Close()
  59 */
  60 bool BamMultiReader::CloseFile(const std::string& filename) {
  61     return d->CloseFile(filename);
  62 }
  63
  64 /*! \fn bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type)
  65     \brief Creates index files for the current BAM files.
  66
  67     \param type file format to create, see BamIndex::IndexType for available formats
  68     \return \c true if index files created OK
  69     \sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()
  70 */
  71 bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type) {
  72     return d->CreateIndexes(type);
  73 }
  74
  75 /*! \fn const std::vector<std::string> BamMultiReader::Filenames(void) const
  76     \brief Returns list of filenames for all open BAM files.
  77
  78     Retrieved filenames will contain whatever was passed via Open().
  79     If you need full directory paths here, be sure to include them
  80     when you open the BAM files.
  81
  82     \returns names of open BAM files. If no files are open, returns an empty vector.
  83     \sa IsOpen(), BamReader::GetFilename()
  84 */
  85 const std::vector<std::string> BamMultiReader::Filenames(void) const {
  86     return d->Filenames();
  87 }
  88
  89 // returns a description of the last error that occurred
  90 std::string BamMultiReader::GetErrorString(void) const {
  91     return d->GetErrorString();
  92 }
  93
  94 /*! \fn SamHeader BamMultiReader::GetHeader(void) const
  95     \brief Returns unified SAM-format header for all files
  96
  97     N.B. - Modifying the retrieved text does NOT affect the current
  98     BAM files. Thesse file have been opened in a read-only mode. However,
  99     your modified header text can be used in conjunction with BamWriter
 100     to generate a new BAM file with the appropriate header information.
 101
 102     \returns header data wrapped in SamHeader object
 103     \sa GetHeaderText(), BamReader::GetHeader()
 104 */
 105 SamHeader BamMultiReader::GetHeader(void) const {
 106     return d->GetHeader();
 107 }
 108
 109 /*! \fn std::string BamMultiReader::GetHeaderText(void) const
 110     \brief Returns unified SAM-format header text for all files
 111
 112     N.B. - Modifying the retrieved text does NOT affect the current
 113     BAM files. Thesse file have been opened in a read-only mode. However,
 114     your modified header text can be used in conjunction with BamWriter
 115     to generate a new BAM file with the appropriate header information.
 116
 117     \returns SAM-formatted header text
 118     \sa GetHeader(), BamReader::GetHeaderText()
 119 */
 120 std::string BamMultiReader::GetHeaderText(void) const {
 121     return d->GetHeaderText();
 122 }
 123
 124 /*! \fn bool BamMultiReader::GetNextAlignment(BamAlignment& alignment)
 125     \brief Retrieves next available alignment.
 126
 127     Equivalent to BamReader::GetNextAlignment() with respect to what is a valid
 128     overlapping alignment and what data gets populated.
 129
 130     This method takes care of determining which alignment actually is 'next'
 131     across multiple files, depending on current SortOrder.
 132
 133     \param alignment destination for alignment record data
 134     \returns \c true if a valid alignment was found
 135     \sa GetNextAlignmentCore(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignment()
 136 */
 137 bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
 138     return d->GetNextAlignment(nextAlignment);
 139 }
 140
 141 /*! \fn bool BamMultiReader::GetNextAlignmentCore(BamAlignment& alignment)
 142     \brief Retrieves next available alignment.
 143
 144     Equivalent to BamReader::GetNextAlignmentCore() with respect to what is a valid
 145     overlapping alignment and what data gets populated.
 146
 147     This method takes care of determining which alignment actually is 'next'
 148     across multiple files, depending on current SortOrder.
 149
 150     \param alignment destination for alignment record data
 151     \returns \c true if a valid alignment was found
 152     \sa GetNextAlignment(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignmentCore()
 153 */
 154 bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
 155     return d->GetNextAlignmentCore(nextAlignment);
 156 }
 157
 158 /*! \fn int BamMultiReader::GetReferenceCount(void) const
 159     \brief Returns number of reference sequences.
 160     \sa BamReader::GetReferenceCount()
 161 */
 162 int BamMultiReader::GetReferenceCount(void) const {
 163     return d->GetReferenceCount();
 164 }
 165
 166 /*! \fn const RefVector& BamMultiReader::GetReferenceData(void) const
 167     \brief Returns all reference sequence entries.
 168     \sa RefData, BamReader::GetReferenceData()
 169 */
 170 const BamTools::RefVector BamMultiReader::GetReferenceData(void) const {
 171     return d->GetReferenceData();
 172 }
 173
 174 /*! \fn int BamMultiReader::GetReferenceID(const std::string& refName) const
 175     \brief Returns the ID of the reference with this name.
 176
 177     If \a refName is not found, returns -1.
 178
 179     \sa BamReader::GetReferenceID()
 180 */
 181 int BamMultiReader::GetReferenceID(const std::string& refName) const {
 182     return d->GetReferenceID(refName);
 183 }
 184
 185 /*! \fn bool BamMultiReader::HasIndexes(void) const
 186     \brief Returns \c true if all BAM files have index data available.
 187     \sa BamReader::HasIndex()
 188 */
 189 bool BamMultiReader::HasIndexes(void) const {
 190     return d->HasIndexes();
 191 }
 192
 193 /*! \fn bool BamMultiReader::HasOpenReaders(void) const
 194     \brief Returns \c true if there are any open BAM files.
 195 */
 196 bool BamMultiReader::HasOpenReaders(void) const {
 197     return d->HasOpenReaders();
 198 }
 199
 200 /*! \fn bool BamMultiReader::Jump(int refID, int position)
 201     \brief Performs a random-access jump within current BAM files.
 202
 203     This is a convenience method, equivalent to calling SetRegion()
 204     with only a left boundary specified.
 205
 206     \returns \c true if jump was successful
 207     \sa HasIndex(), BamReader::Jump()
 208 */
 209
 210 bool BamMultiReader::Jump(int refID, int position) {
 211     return d->Jump(refID, position);
 212 }
 213
 214 /*! \fn bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType)
 215     \brief Looks for index files that match current BAM files.
 216
 217     Use this function when you need index files, and perhaps have a
 218     preferred index format, but do not depend heavily on which indexes
 219     actually get loaded at runtime.
 220
 221     For each BAM file, this function will defer to your \a preferredType
 222     whenever possible. However, if an index file of \a preferredType can
 223     not be found, then it will look for any other index file that matches
 224     that BAM file.
 225
 226     An example case would look this:
 227     \code
 228
 229         BamMultiReader reader;
 230         // do setup
 231
 232         // ensure that all files have an index
 233         if ( !reader.LocateIndexes() )      // opens any existing index files that match our BAM files
 234             reader.CreateIndexes();         // creates index files for BAM files that still lack one
 235
 236         // do interesting stuff
 237         // ...
 238
 239     \endcode
 240
 241     If you want precise control over which index files are loaded, use OpenIndexes()
 242     with the desired index filenames. If that function returns false, you can use
 243     CreateIndexes() to then build index files of the exact requested format.
 244
 245     \param preferredType desired index file format, see BamIndex::IndexType for available formats
 246     \returns \c true if index files could be found for \b ALL open BAM files
 247     \sa BamReader::LocateIndex()
 248 */
 249 bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType) {
 250     return d->LocateIndexes(preferredType);
 251 }
 252
 253 /*! \fn bool BamMultiReader::Open(const std::vector<std::string>& filenames)
 254     \brief Opens BAM files.
 255
 256     N.B. - Opening BAM files will invalidate any current region set on the multireader.
 257            All file pointers will be returned to the beginning of the alignment data.
 258            Follow this with Jump() or SetRegion() to establish a region of interest.
 259
 260     \param filenames list of BAM filenames to open
 261     \returns \c true if BAM files were opened successfully
 262     \sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()
 263 */
 264 bool BamMultiReader::Open(const std::vector<std::string>& filenames) {
 265     return d->Open(filenames);
 266 }
 267
 268 /*! \fn bool BamMultiReader::OpenFile(const std::string& filename)
 269     \brief Opens a single BAM file.
 270
 271     Adds another BAM file to multireader "on-the-fly".
 272
 273     N.B. - Opening a BAM file invalidates any current region set on the multireader.
 274            All file pointers will be returned to the beginning of the alignment data.
 275            Follow this with Jump() or SetRegion() to establish a region of interest.
 276
 277     \param filename BAM filename to open
 278     \returns \c true if BAM file was opened successfully
 279     \sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()
 280 */
 281 bool BamMultiReader::OpenFile(const std::string& filename) {
 282     return d->OpenFile(filename);
 283 }
 284
 285 /*! \fn bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames)
 286     \brief Opens index files for current BAM files.
 287
 288     N.B. - Currently assumes that index filenames match the order (and number) of
 289     BAM files passed to Open().
 290
 291     \param indexFilenames list of BAM index file names
 292     \returns \c true if BAM index file was opened & data loaded successfully
 293     \sa LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()
 294 */
 295 bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames) {
 296     return d->OpenIndexes(indexFilenames);
 297 }
 298
 299 /*! \fn bool BamMultiReader::Rewind(void)
 300     \brief Returns the internal file pointers to the beginning of alignment records.
 301
 302     Useful for performing multiple sequential passes through BAM files.
 303     Calling this function clears any prior region that may have been set.
 304
 305     \returns \c true if rewind operation was successful
 306     \sa Jump(), SetRegion(), BamReader::Rewind()
 307 */
 308 bool BamMultiReader::Rewind(void) {
 309     return d->Rewind();
 310 }
 311
 312 /*! \fn void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode)
 313     \brief Changes the caching behavior of the index data.
 314
 315     Default mode is BamIndex::LimitedIndexCaching.
 316
 317     \param mode desired cache mode for index, see BamIndex::IndexCacheMode for
 318                 description of the available cache modes
 319     \sa HasIndex(), BamReader::SetIndexCacheMode()
 320 */
 321 void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) {
 322     d->SetIndexCacheMode(mode);
 323 }
 324
 325 /*! \fn bool BamMultiReader::SetRegion(const BamRegion& region)
 326     \brief Sets a target region of interest
 327
 328     Equivalent to calling BamReader::SetRegion() on all open BAM files.
 329
 330     \param region desired region-of-interest to activate
 331     \returns \c true if ALL readers set the region successfully
 332     \sa HasIndexes(), Jump(), BamReader::SetRegion()
 333 */
 334 bool BamMultiReader::SetRegion(const BamRegion& region) {
 335     return d->SetRegion(region);
 336 }
 337
 338 /*! \fn bool BamMultiReader::SetRegion(const int& leftRefID,
 339                                        const int& leftPosition,
 340                                        const int& rightRefID,
 341                                        const int& rightPosition)
 342     \brief Sets a target region of interest
 343
 344     This is an overloaded function.
 345
 346     Equivalent to calling BamReader::SetRegion() on all open BAM files.
 347
 348     \param leftRefID     referenceID of region's left boundary
 349     \param leftPosition  position of region's left boundary
 350     \param rightRefID    reference ID of region's right boundary
 351     \param rightPosition position of region's right boundary
 352
 353     \returns \c true if ALL readers set the region successfully
 354     \sa HasIndexes(), Jump(), BamReader::SetRegion()
 355 */
 356 bool BamMultiReader::SetRegion(const int& leftRefID,
 357                                const int& leftPosition,
 358                                const int& rightRefID,
 359                                const int& rightPosition)
 360 {
 361     BamRegion region(leftRefID, leftPosition, rightRefID, rightPosition);
 362     return d->SetRegion(region);
 363 }