BamTools  2.5.2
Public Types | Public Member Functions | List of all members
BamTools::BamMultiReader Class Reference

Convenience class for reading multiple BAM files. More...

#include <BamMultiReader.h>

Public Types

enum  MergeOrder { RoundRobinMerge = 0 , MergeByCoordinate , MergeByName }
 

Public Member Functions

 BamMultiReader ()
 constructor More...
 
 ~BamMultiReader ()
 destructor More...
 
bool Close ()
 Closes all open BAM files. More...
 
bool CloseFile (const std::string &filename)
 Closes requested BAM file. More...
 
const std::vector< std::string > Filenames () const
 Returns list of filenames for all open BAM files. More...
 
BamMultiReader::MergeOrder GetMergeOrder () const
 Returns curent merge order strategy. More...
 
bool HasOpenReaders () const
 Returns true if there are any open BAM files. More...
 
bool Jump (int refID, int position=0)
 Performs a random-access jump within current BAM files. More...
 
bool Open (const std::vector< std::string > &filenames)
 Opens BAM files. More...
 
bool OpenFile (const std::string &filename)
 Opens a single BAM file. More...
 
bool Rewind ()
 Returns the internal file pointers to the beginning of alignment records. More...
 
bool SetExplicitMergeOrder (BamMultiReader::MergeOrder order)
 Sets an explicit merge order, regardless of the BAM files' SO header tag. More...
 
bool SetRegion (const BamRegion &region)
 Sets a target region of interest. More...
 
bool SetRegion (const int &leftRefID, const int &leftPosition, const int &rightRefID, const int &rightPosition)
 Sets a target region of interest. More...
 
bool GetNextAlignment (BamAlignment &alignment)
 Retrieves next available alignment. More...
 
bool GetNextAlignmentCore (BamAlignment &alignment)
 Retrieves next available alignment. More...
 
SamHeader GetHeader () const
 Returns unified SAM-format header for all files. More...
 
std::string GetHeaderText () const
 Returns unified SAM-format header text for all files. More...
 
int GetReferenceCount () const
 Returns number of reference sequences. More...
 
const BamTools::RefVector GetReferenceData () const
 Returns all reference sequence entries. More...
 
int GetReferenceID (const std::string &refName) const
 Returns the ID of the reference with this name. More...
 
bool CreateIndexes (const BamIndex::IndexType &type=BamIndex::STANDARD)
 Creates index files for the current BAM files. More...
 
bool HasIndexes () const
 Returns true if all BAM files have index data available. More...
 
bool LocateIndexes (const BamIndex::IndexType &preferredType=BamIndex::STANDARD)
 Looks for index files that match current BAM files. More...
 
bool OpenIndexes (const std::vector< std::string > &indexFilenames)
 Opens index files for current BAM files. More...
 
std::string GetErrorString () const
 Returns a human-readable description of the last error that occurred. More...
 

Detailed Description

Convenience class for reading multiple BAM files.

Member Enumeration Documentation

◆ MergeOrder

Enumerator
RoundRobinMerge 

Merge strategy when BAM files are unsorted, or their sorted status is either unknown or ignored.

MergeByCoordinate 

Merge strategy when BAM files are sorted by position ('coordinate')

MergeByName 

Merge strategy when BAM files are sorted by read name ('queryname')

Constructor & Destructor Documentation

◆ BamMultiReader()

BamMultiReader::BamMultiReader ( )

constructor

◆ ~BamMultiReader()

BamMultiReader::~BamMultiReader ( )

destructor

Member Function Documentation

◆ Close()

bool BamMultiReader::Close ( )

Closes all open BAM files.

Also clears out all header and reference data.

See also
CloseFile(), IsOpen(), Open(), BamReader::Close()

◆ CloseFile()

bool BamMultiReader::CloseFile ( const std::string &  filename)

Closes requested BAM file.

Leaves any other file(s) open, along with header and reference data.

Parameters
[in]filenamename of specific BAM file to close
See also
Close(), IsOpen(), Open(), BamReader::Close()

◆ CreateIndexes()

bool BamMultiReader::CreateIndexes ( const BamIndex::IndexType type = BamIndex::STANDARD)

Creates index files for the current BAM files.

Parameters
[in]typefile format to create, see BamIndex::IndexType for available formats
Returns
true if index files created OK
See also
LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()

◆ Filenames()

const std::vector< std::string > BamMultiReader::Filenames ( ) const

Returns list of filenames for all open BAM files.

Retrieved filenames will contain whatever was passed via Open(). If you need full directory paths here, be sure to include them when you open the BAM files.

Returns
names of open BAM files. If no files are open, returns an empty vector.
See also
IsOpen(), BamReader::GetFilename()

◆ GetErrorString()

std::string BamMultiReader::GetErrorString ( ) const

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.

Returns
error description

◆ GetHeader()

SamHeader BamMultiReader::GetHeader ( ) const

Returns unified SAM-format header for all files.

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.
Returns
header data wrapped in SamHeader object
See also
GetHeaderText(), BamReader::GetHeader()

◆ GetHeaderText()

std::string BamMultiReader::GetHeaderText ( ) const

Returns unified SAM-format header text for all files.

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.
Returns
SAM-formatted header text
See also
GetHeader(), BamReader::GetHeaderText()

◆ GetMergeOrder()

BamMultiReader::MergeOrder BamMultiReader::GetMergeOrder ( ) const

Returns curent merge order strategy.

Returns
current merge order enum value
See also
BamMultiReader::MergeOrder, SetExplicitMergeOrder()

◆ GetNextAlignment()

bool BamMultiReader::GetNextAlignment ( BamAlignment alignment)

Retrieves next available alignment.

Equivalent to BamReader::GetNextAlignment() with respect to what is a valid overlapping alignment and what data gets populated.

This method takes care of determining which alignment actually is 'next' across multiple files, depending on their sort order.

Parameters
[out]alignmentdestination for alignment record data
Returns
true if a valid alignment was found
See also
GetNextAlignmentCore(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignment()

◆ GetNextAlignmentCore()

bool BamMultiReader::GetNextAlignmentCore ( BamAlignment alignment)

Retrieves next available alignment.

Equivalent to BamReader::GetNextAlignmentCore() with respect to what is a valid overlapping alignment and what data gets populated.

This method takes care of determining which alignment actually is 'next' across multiple files, depending on their sort order.

Parameters
[out]alignmentdestination for alignment record data
Returns
true if a valid alignment was found
See also
GetNextAlignment(), SetExplicitMergeOrder(), SetRegion(), BamReader::GetNextAlignmentCore()

◆ GetReferenceCount()

int BamMultiReader::GetReferenceCount ( ) const

Returns number of reference sequences.

See also
BamReader::GetReferenceCount()

◆ GetReferenceData()

const BamTools::RefVector BamMultiReader::GetReferenceData ( ) const

Returns all reference sequence entries.

See also
RefData, BamReader::GetReferenceData()

◆ GetReferenceID()

int BamMultiReader::GetReferenceID ( const std::string &  refName) const

Returns the ID of the reference with this name.

If refName is not found, returns -1.

Parameters
[in]refNamename of reference to look up
See also
BamReader::GetReferenceID()

◆ HasIndexes()

bool BamMultiReader::HasIndexes ( ) const

Returns true if all BAM files have index data available.

See also
BamReader::HasIndex()

◆ HasOpenReaders()

bool BamMultiReader::HasOpenReaders ( ) const

Returns true if there are any open BAM files.

◆ Jump()

bool BamMultiReader::Jump ( int  refID,
int  position = 0 
)

Performs a random-access jump within current BAM files.

This is a convenience method, equivalent to calling SetRegion() with only a left boundary specified.

Parameters
[in]refIDID of reference to jump to
[in]position(0-based) left boundary
Returns
true if jump was successful
See also
HasIndex(), BamReader::Jump()

◆ LocateIndexes()

bool BamMultiReader::LocateIndexes ( const BamIndex::IndexType preferredType = BamIndex::STANDARD)

Looks for index files that match current BAM files.

Use this function when you need index files, and perhaps have a preferred index format, but do not depend heavily on which indexes actually get loaded at runtime.

For each BAM file, this function will defer to your preferredType whenever possible. However, if an index file of preferredType can not be found, then it will look for any other index file that matches that BAM file.

An example case would look this:

// 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 any BAM files that still lack one
// do interesting stuff using random-access...
BamMultiReader()
constructor
Definition: BamMultiReader.cpp:44

If you want precise control over which index files are loaded, use OpenIndexes() with the desired index filenames. If that function returns false, you can use CreateIndexes() to then build index files of the exact requested format.

Parameters
[in]preferredTypedesired index file format, see BamIndex::IndexType for available formats
Returns
true if index files could be found for ALL open BAM files
See also
BamReader::LocateIndex()

◆ Open()

bool BamMultiReader::Open ( const std::vector< std::string > &  filenames)

Opens BAM files.

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.
Parameters
[in]filenameslist of BAM filenames to open
Returns
true if BAM files were opened successfully
See also
Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()

◆ OpenFile()

bool BamMultiReader::OpenFile ( const std::string &  filename)

Opens a single BAM file.

Adds another BAM file to multireader "on-the-fly".

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.
Parameters
[in]filenameBAM filename to open
Returns
true if BAM file was opened successfully
See also
Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()

◆ OpenIndexes()

bool BamMultiReader::OpenIndexes ( const std::vector< std::string > &  indexFilenames)

Opens index files for current BAM files.

Note
Currently assumes that index filenames match the order (and number) of BAM files passed to Open().
Parameters
[in]indexFilenameslist of BAM index file names
Returns
true if BAM index file was opened & data loaded successfully
See also
LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()

◆ Rewind()

bool BamMultiReader::Rewind ( )

Returns the internal file pointers to the beginning of alignment records.

Useful for performing multiple sequential passes through BAM files. Calling this function clears any prior region that may have been set.

Returns
true if rewind operation was successful
See also
Jump(), SetRegion(), BamReader::Rewind()

◆ SetExplicitMergeOrder()

bool BamMultiReader::SetExplicitMergeOrder ( BamMultiReader::MergeOrder  order)

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 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 not once alignment fetching has started. There is nothing in the API to prevent you from doing so, but the results may be unexpected.
Returns
true if merge order could be successfully applied
See also
BamMultiReader::MergeOrder, GetMergeOrder(), GetNextAlignment(), GetNextAlignmentCore()

◆ SetRegion() [1/2]

bool BamMultiReader::SetRegion ( const BamRegion region)

Sets a target region of interest.

Equivalent to calling BamReader::SetRegion() on all open BAM files.

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.
Parameters
[in]regiondesired region-of-interest to activate
Returns
true if ALL readers set the region successfully
See also
HasIndexes(), Jump(), BamReader::SetRegion()

◆ SetRegion() [2/2]

bool BamMultiReader::SetRegion ( const int &  leftRefID,
const int &  leftPosition,
const int &  rightRefID,
const int &  rightPosition 
)

Sets a target region of interest.

This is an overloaded function. 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.
Parameters
[in]leftRefIDreferenceID of region's left boundary
[in]leftPositionposition of region's left boundary
[in]rightRefIDreference ID of region's right boundary
[in]rightPositionposition of region's right boundary
Returns
true if ALL readers set the region successfully
See also
HasIndexes(), Jump(), BamReader::SetRegion()

The documentation for this class was generated from the following files: