1 // ***************************************************************************
2 // BamMultiReader.cpp (c) 2010 Erik Garrison, Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // All rights reserved.
5 // ---------------------------------------------------------------------------
6 // Last modified: 15 March 2011 (DB)
7 // ---------------------------------------------------------------------------
8 // Convenience class for reading multiple BAM files.
10 // This functionality allows applications to work on very large sets of files
11 // without requiring intermediate merge, sort, and index steps for each file
12 // subset. It also improves the performance of our merge system as it
13 // precludes the need to sort merged files.
14 // ***************************************************************************
16 #include <api/BamMultiReader.h>
17 #include <api/internal/BamMultiReader_p.h>
18 using namespace BamTools;
24 /*! \class BamTools::BamReader
25 \brief Convenience class for reading multiple BAM files.
28 /*! \fn BamMultiReader::BamMultiReader(void)
31 BamMultiReader::BamMultiReader(void)
32 : d(new Internal::BamMultiReaderPrivate)
35 /*! \fn BamMultiReader::~BamMultiReader(void)
38 BamMultiReader::~BamMultiReader(void) {
43 /*! \fn void BamMultiReader::Close(void)
44 \brief Closes all open BAM files.
46 Also clears out all header and reference data.
48 \sa CloseFile(), IsOpen(), Open(), BamReader::Close()
50 void BamMultiReader::Close(void) {
54 /*! \fn void BamMultiReader::CloseFile(const std::string& filename)
55 \brief Closes requested BAM file.
57 Leaves any other file(s) open, along with header and reference data.
59 \sa Close(), IsOpen(), Open(), BamReader::Close()
61 void BamMultiReader::CloseFile(const std::string& filename) {
62 d->CloseFile(filename);
65 /*! \fn bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type)
66 \brief Creates index files for the current BAM files.
68 \param type file format to create, see BamIndex::IndexType for available formats
69 \return \c true if index files created OK
70 \sa LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()
72 bool BamMultiReader::CreateIndexes(const BamIndex::IndexType& type) {
73 return d->CreateIndexes(type);
76 /*! \fn const std::vector<std::string> BamMultiReader::Filenames(void) const
77 \brief Returns list of filenames for all open BAM files.
79 Retrieved filenames will contain whatever was passed via Open().
80 If you need full directory paths here, be sure to include them
81 when you open the BAM files.
83 \returns names of open BAM files. If no files are open, returns an empty vector.
84 \sa IsOpen(), BamReader::GetFilename()
86 const std::vector<std::string> BamMultiReader::Filenames(void) const {
87 return d->Filenames();
90 /*! \fn SamHeader BamMultiReader::GetHeader(void) const
91 \brief Returns unified SAM-format header for all files
93 N.B. - Modifying the retrieved text does NOT affect the current
94 BAM files. Thesse file have been opened in a read-only mode. However,
95 your modified header text can be used in conjunction with BamWriter
96 to generate a new BAM file with the appropriate header information.
98 \returns header data wrapped in SamHeader object
99 \sa GetHeaderText(), BamReader::GetHeader()
101 SamHeader BamMultiReader::GetHeader(void) const {
102 return d->GetHeader();
105 /*! \fn std::string BamMultiReader::GetHeaderText(void) const
106 \brief Returns unified SAM-format header text for all files
108 N.B. - Modifying the retrieved text does NOT affect the current
109 BAM files. Thesse file have been opened in a read-only mode. However,
110 your modified header text can be used in conjunction with BamWriter
111 to generate a new BAM file with the appropriate header information.
113 \returns SAM-formatted header text
114 \sa GetHeader(), BamReader::GetHeaderText()
116 std::string BamMultiReader::GetHeaderText(void) const {
117 return d->GetHeaderText();
120 /*! \fn bool BamMultiReader::GetNextAlignment(BamAlignment& alignment)
121 \brief Retrieves next available alignment.
123 Equivalent to BamReader::GetNextAlignment() with respect to what is a valid
124 overlapping alignment and what data gets populated.
126 This method takes care of determining which alignment actually is 'next'
127 across multiple files, depending on current SortOrder.
129 \param alignment destination for alignment record data
130 \returns \c true if a valid alignment was found
131 \sa GetNextAlignmentCore(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignment()
133 bool BamMultiReader::GetNextAlignment(BamAlignment& nextAlignment) {
134 return d->GetNextAlignment(nextAlignment);
137 /*! \fn bool BamMultiReader::GetNextAlignmentCore(BamAlignment& alignment)
138 \brief Retrieves next available alignment.
140 Equivalent to BamReader::GetNextAlignmentCore() with respect to what is a valid
141 overlapping alignment and what data gets populated.
143 This method takes care of determining which alignment actually is 'next'
144 across multiple files, depending on current SortOrder.
146 \param alignment destination for alignment record data
147 \returns \c true if a valid alignment was found
148 \sa GetNextAlignment(), SetRegion(), SetSortOrder(), BamReader::GetNextAlignmentCore()
150 bool BamMultiReader::GetNextAlignmentCore(BamAlignment& nextAlignment) {
151 return d->GetNextAlignmentCore(nextAlignment);
154 /*! \fn int BamMultiReader::GetReferenceCount(void) const
155 \brief Returns number of reference sequences.
156 \sa BamReader::GetReferenceCount()
158 int BamMultiReader::GetReferenceCount(void) const {
159 return d->GetReferenceCount();
162 /*! \fn const RefVector& BamMultiReader::GetReferenceData(void) const
163 \brief Returns all reference sequence entries.
164 \sa RefData, BamReader::GetReferenceData()
166 const BamTools::RefVector BamMultiReader::GetReferenceData(void) const {
167 return d->GetReferenceData();
170 /*! \fn int BamMultiReader::GetReferenceID(const std::string& refName) const
171 \brief Returns the ID of the reference with this name.
173 If \a refName is not found, returns -1.
175 \sa BamReader::GetReferenceID()
177 int BamMultiReader::GetReferenceID(const std::string& refName) const {
178 return d->GetReferenceID(refName);
181 /*! \fn bool BamMultiReader::HasIndexes(void) const
182 \brief Returns \c true if all BAM files have index data available.
183 \sa BamReader::HasIndex()
185 bool BamMultiReader::HasIndexes(void) const {
186 return d->HasIndexes();
189 /*! \fn bool BamMultiReader::HasOpenReaders(void) const
190 \brief Returns \c true if there are any open BAM files.
192 bool BamMultiReader::HasOpenReaders(void) const {
193 return d->HasOpenReaders();
196 /*! \fn bool BamMultiReader::IsIndexLoaded(void) const
197 \brief Returns \c true if all BAM files have index data available.
199 \deprecated Instead use HasIndexes()
201 See explanation in BamReader.cpp for more details on the deprecation decision.
205 bool BamMultiReader::IsIndexLoaded(void) const {
206 return d->HasIndexes();
209 /*! \fn bool BamMultiReader::Jump(int refID, int position)
210 \brief Performs a random-access jump within current BAM files.
212 This is a convenience method, equivalent to calling SetRegion()
213 with only a left boundary specified.
215 \returns \c true if jump was successful
216 \sa HasIndex(), BamReader::Jump()
219 bool BamMultiReader::Jump(int refID, int position) {
220 return d->Jump(refID, position);
223 /*! \fn bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType)
224 \brief Looks for index files that match current BAM files.
226 Use this function when you need index files, and perhaps have a
227 preferred index format, but do not depend heavily on which indexes
228 actually get loaded at runtime.
230 For each BAM file, this function will defer to your \a preferredType
231 whenever possible. However, if an index file of \a preferredType can
232 not be found, then it will look for any other index file that matches
235 An example case would look this:
238 BamMultiReader reader;
241 // ensure that all files have an index
242 if ( !reader.LocateIndexes() ) // opens any existing index files that match our BAM files
243 reader.CreateIndexes(); // creates index files for BAM files that still lack one
245 // do interesting stuff
250 If you want precise control over which index files are loaded, use OpenIndexes()
251 with the desired index filenames. If that function returns false, you can use
252 CreateIndexes() to then build index files of the exact requested format.
254 \param preferredType desired index file format, see BamIndex::IndexType for available formats
255 \returns \c true if index files could be found for \b ALL open BAM files
256 \sa BamReader::LocateIndex()
258 bool BamMultiReader::LocateIndexes(const BamIndex::IndexType& preferredType) {
259 return d->LocateIndexes(preferredType);
262 /*! \fn bool BamMultiReader::Open(const std::vector<std::string>& filenames)
263 \brief Opens BAM files.
265 N.B. - Opening BAM files will invalidate any current region set on the multireader.
266 All file pointers will be returned to the beginning of the alignment data.
267 Follow this with Jump() or SetRegion() to establish a region of interest.
269 \param filenames list of BAM filenames to open
270 \returns \c true if BAM files were opened successfully
271 \sa Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()
273 bool BamMultiReader::Open(const std::vector<std::string>& filenames) {
274 return d->Open(filenames);
277 /*! \fn bool BamMultiReader::OpenFile(const std::string& filename)
278 \brief Opens a single BAM file.
280 Adds another BAM file to multireader "on-the-fly".
282 N.B. - Opening a BAM file invalidates any current region set on the multireader.
283 All file pointers will be returned to the beginning of the alignment data.
284 Follow this with Jump() or SetRegion() to establish a region of interest.
286 \param filename BAM filename to open
287 \returns \c true if BAM file was opened successfully
288 \sa Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()
290 bool BamMultiReader::OpenFile(const std::string& filename) {
291 return d->OpenFile(filename);
294 /*! \fn bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames)
295 \brief Opens index files for current BAM files.
297 N.B. - Currently assumes that index filenames match the order (and number) of
298 BAM files passed to Open().
300 \param indexFilenames list of BAM index file names
301 \returns \c true if BAM index file was opened & data loaded successfully
302 \sa LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()
304 bool BamMultiReader::OpenIndexes(const std::vector<std::string>& indexFilenames) {
305 return d->OpenIndexes(indexFilenames);
308 /*! \fn void BamMultiReader::PrintFilenames(void) const
309 \brief Convenience method for printing filenames to stdout.
310 \deprecated Doesn't really belong as an API function. Clients should
311 determine how the data is reported.
312 \sa Filenames(), BamReader::GetFilename()
314 void BamMultiReader::PrintFilenames(void) const {
318 /*! \fn bool BamMultiReader::Rewind(void)
319 \brief Returns the internal file pointers to the beginning of alignment records.
321 Useful for performing multiple sequential passes through BAM files.
322 Calling this function clears any prior region that may have been set.
324 \returns \c true if rewind operation was successful
325 \sa Jump(), SetRegion(), BamReader::Rewind()
327 bool BamMultiReader::Rewind(void) {
331 /*! \fn void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode)
332 \brief Changes the caching behavior of the index data.
334 Default mode is BamIndex::LimitedIndexCaching.
336 \param mode desired cache mode for index, see BamIndex::IndexCacheMode for
337 description of the available cache modes
338 \sa HasIndex(), BamReader::SetIndexCacheMode()
340 void BamMultiReader::SetIndexCacheMode(const BamIndex::IndexCacheMode& mode) {
341 d->SetIndexCacheMode(mode);
344 /*! \fn bool BamMultiReader::SetRegion(const BamRegion& region)
345 \brief Sets a target region of interest
347 Equivalent to calling BamReader::SetRegion() on all open BAM files.
349 \param region desired region-of-interest to activate
350 \returns \c true if ALL readers set the region successfully
351 \sa HasIndexes(), Jump(), BamReader::SetRegion()
353 bool BamMultiReader::SetRegion(const BamRegion& region) {
354 return d->SetRegion(region);
357 /*! \fn bool BamMultiReader::SetRegion(const int& leftRefID,
358 const int& leftPosition,
359 const int& rightRefID,
360 const int& rightPosition)
361 \brief Sets a target region of interest
363 This is an overloaded function.
365 Equivalent to calling BamReader::SetRegion() on all open BAM files.
367 \param leftRefID referenceID of region's left boundary
368 \param leftPosition position of region's left boundary
369 \param rightRefID reference ID of region's right boundary
370 \param rightPosition position of region's right boundary
372 \returns \c true if ALL readers set the region successfully
373 \sa HasIndexes(), Jump(), BamReader::SetRegion()
375 bool BamMultiReader::SetRegion(const int& leftRefID,
376 const int& leftPosition,
377 const int& rightRefID,
378 const int& rightPosition)
380 BamRegion region(leftRefID, leftPosition, rightRefID, rightPosition);
381 return d->SetRegion(region);
384 /*! \fn void BamMultiReader::SetSortOrder(const SortOrder& order)
385 \brief Sets the expected sorting order for reading across multiple BAM files.
387 Default is BamMultiReader::SortedByPosition.
389 The SortOrder determines how the reader determines which alignment is "next"
390 from among its open readers.
392 \param order expected sort order
394 void BamMultiReader::SetSortOrder(const SortOrder& order) {
395 d->SetSortOrder(order);