BamTools::BamMultiReader Class Reference

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

#include <BamMultiReader.h>

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

Detailed Description

Convenience class for reading multiple BAM files.

Constructor & Destructor Documentation

BamMultiReader::BamMultiReader ( void )

constructor

BamMultiReader::~BamMultiReader ( void )

destructor

Member Function Documentation

bool BamMultiReader::Close ( void )

Closes all open BAM files.

Also clears out all header and reference data.

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

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] filename name of specific BAM file to close

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

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

Creates index files for the current BAM files.

Parameters:

[in] type file format to create, see BamIndex::IndexType for available formats

Returns:: true if index files created OK

See also:: LocateIndexes(), OpenIndexes(), BamReader::CreateIndex()

const std::vector< std::string > BamMultiReader::Filenames ( void ) 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()

std::string BamMultiReader::GetErrorString ( void ) 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

SamHeader BamMultiReader::GetHeader ( void ) 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()

std::string BamMultiReader::GetHeaderText ( void ) 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()

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] alignment destination for alignment record data

Returns:: true if a valid alignment was found

See also:: GetNextAlignmentCore(), SetRegion(), BamReader::GetNextAlignment()

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] alignment destination for alignment record data

Returns:: true if a valid alignment was found

See also:: GetNextAlignment(), SetRegion(), BamReader::GetNextAlignmentCore()

int BamMultiReader::GetReferenceCount ( void ) const

Returns number of reference sequences.

See also:: BamReader::GetReferenceCount()

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

Returns all reference sequence entries.

See also:: RefData, BamReader::GetReferenceData()

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] refName name of reference to look up

See also:: BamReader::GetReferenceID()

bool BamMultiReader::HasIndexes ( void ) const

Returns true if all BAM files have index data available.

See also:: BamReader::HasIndex()

bool BamMultiReader::HasOpenReaders ( void ) const

Returns true if there are any open BAM files.

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]`	refID	ID of reference to jump to
`[in]`	position	(0-based) left boundary

Returns:: true if jump was successful

See also:: HasIndex(), BamReader::Jump()

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:

        BamMultiReader reader;

        // 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...

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] preferredType desired 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()

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] filenames list of BAM filenames to open

Returns:: true if BAM files were opened successfully

See also:: Close(), HasOpenReaders(), OpenFile(), OpenIndexes(), BamReader::Open()

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] filename BAM filename to open

Returns:: true if BAM file was opened successfully

See also:: Close(), HasOpenReaders(), Open(), OpenIndexes(), BamReader::Open()

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] indexFilenames list of BAM index file names

Returns:: true if BAM index file was opened & data loaded successfully

See also:: LocateIndex(), Open(), SetIndex(), BamReader::OpenIndex()

bool BamMultiReader::Rewind ( void )

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()

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]`	leftRefID	referenceID of region's left boundary
`[in]`	leftPosition	position of region's left boundary
`[in]`	rightRefID	reference ID of region's right boundary
`[in]`	rightPosition	position of region's right boundary

Returns:: true if ALL readers set the region successfully

See also:: HasIndexes(), Jump(), BamReader::SetRegion()

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] region desired region-of-interest to activate

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:

BamTools::BamMultiReader Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation