BamTools::BamReader Class Reference

Provides read access to BAM files. More...

#include <BamReader.h>

Public Member Functions
	BamReader (void)
	constructor
	~BamReader (void)
	destructor
bool	Close (void)
	Closes the current BAM file.
const std::string	GetFilename (void) const
	Returns name of current BAM file.
bool	IsOpen (void) const
	Returns `true` if a BAM file is open for reading.
bool	Jump (int refID, int position=0)
	Performs a random-access jump within BAM file.
bool	Open (const std::string &filename)
	Opens a BAM file.
bool	Rewind (void)
	Returns the internal file pointer to the first alignment record.
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, without populating the alignment's string data fields.
SamHeader	GetHeader (void) const
	Returns SAM header data.
std::string	GetHeaderText (void) const
	Returns SAM header data, as SAM-formatted text.
int	GetReferenceCount (void) const
	Returns number of reference sequences.
const 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	CreateIndex (const BamIndex::IndexType &type=BamIndex::STANDARD)
	Creates an index file for current BAM file.
bool	HasIndex (void) const
	Returns `true` if index data is available.
bool	LocateIndex (const BamIndex::IndexType &preferredType=BamIndex::STANDARD)
	Looks in BAM file's directory for a matching index file.
bool	OpenIndex (const std::string &indexFilename)
	Opens a BAM index file.
void	SetIndex (BamIndex *index)
	Sets a custom BamIndex on this reader.
std::string	GetErrorString (void) const
	Returns a human-readable description of the last error that occurred.

Detailed Description

Provides read access to BAM files.

Constructor & Destructor Documentation

BamReader::BamReader ( void )

constructor

BamReader::~BamReader ( void )

destructor

Member Function Documentation

bool BamReader::Close ( void )

Closes the current BAM file.

Also clears out all header and reference data.

Returns:: true if file closed OK

See also:: IsOpen(), Open()

bool BamReader::CreateIndex ( const BamIndex::IndexType & type = BamIndex::STANDARD )

Creates an index file for current BAM file.

Parameters:

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

Returns:: true if index created OK

See also:: LocateIndex(), OpenIndex()

string BamReader::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

const std::string BamReader::GetFilename ( void ) const

Returns name of current BAM file.

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

Returns:: name of open BAM file. If no file is open, returns an empty string.

See also:: IsOpen()

SamHeader BamReader::GetHeader ( void ) const

Returns SAM header data.

Header data is wrapped in a SamHeader object that can be conveniently queried & modified.

Note:: Modifying the retrieved SamHeader object does NOT affect the current BAM file. This file has been opened in a read-only mode. However, your modified SamHeader object can be used in conjunction with BamWriter to generate a new BAM file with the appropriate header information.

Returns:: header data object

See also:: GetHeaderText()

std::string BamReader::GetHeaderText ( void ) const

Returns SAM header data, as SAM-formatted text.

Note:: Modifying the retrieved text does NOT affect the current BAM file. This file has 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()

bool BamReader::GetNextAlignment ( BamAlignment & alignment )

Retrieves next available alignment.

Attempts to read the next alignment record from BAM file, and checks to see if it overlaps the current region. If no region is currently set, then the next alignment available is always considered valid.

If a region has been set, via Jump() or SetRegion(), an alignment is only considered valid if it overlaps the region. If the actual 'next' alignment record in the BAM file does not overlap this region, then this function will read sequentially through the file until the next alignment that overlaps this region is found. Once the region has been exhausted (i.e. the next alignment loaded is beyond the region), the function aborts and returns false. In this case, there is no point to continue reading, assuming properly sorted alignments.

This function fully populates all of the alignment's available data fields, including the string data fields (read name, bases, qualities, tags, filename). If only positional data (refID, position, CIGAR ops, alignment flags, etc.) are required, consider using GetNextAlignmentCore() for a significant performance boost.

Parameters:

[out] alignment destination for alignment record data

Returns:: true if a valid alignment was found

bool BamReader::GetNextAlignmentCore ( BamAlignment & alignment )

Retrieves next available alignment, without populating the alignment's string data fields.

Equivalent to GetNextAlignment() with respect to what is a valid overlapping alignment.

However, this method does NOT populate the alignment's string data fields (read name, bases, qualities, tags, filename). This provides a boost in speed when these fields are not required for every alignment. These fields can be populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later.

Parameters:

[out] alignment destination for alignment record data

Returns:: true if a valid alignment was found

See also:: SetRegion()

int BamReader::GetReferenceCount ( void ) const

Returns number of reference sequences.

const RefVector & BamReader::GetReferenceData ( void ) const

Returns all reference sequence entries.

See also:: RefData

int BamReader::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

bool BamReader::HasIndex ( void ) const

Returns true if index data is available.

bool BamReader::IsOpen ( void ) const

Returns true if a BAM file is open for reading.

bool BamReader::Jump	(	int	refID,
		int	position = `0`
	)

Performs a random-access jump within BAM file.

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

Parameters:

`[in]`	refID	left-bound reference ID
`[in]`	position	left-bound position

Returns:: true if jump was successful

See also:: HasIndex()

bool BamReader::LocateIndex ( const BamIndex::IndexType & preferredType = BamIndex::STANDARD )

Looks in BAM file's directory for a matching index file.

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

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 corresponds to this BAM file.

If you want precise control over which index file is loaded, use OpenIndex() with the desired index filename. If that function returns false, you can use CreateIndex() to then build an index of the exact requested format.

Parameters:

[in] preferredType desired index file format, see BamIndex::IndexType for available formats

Returns:: true if (any) index file could be found

bool BamReader::Open ( const std::string & filename )

Opens a BAM file.

If BamReader is already opened on another file, this function closes that file, then attempts to open requested filename.

Parameters:

[in] filename name of BAM file to open

Returns:: true if BAM file was opened successfully

See also:: Close(), IsOpen(), OpenIndex()

bool BamReader::OpenIndex ( const std::string & indexFilename )

Opens a BAM index file.

Parameters:

[in] indexFilename name of BAM index file to open

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

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

bool BamReader::Rewind ( void )

Returns the internal file pointer to the first alignment record.

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

Note:: This function sets the file pointer to first alignment record in the BAM file, NOT the beginning of the file.

Returns:: true if rewind operation was successful

See also:: Jump(), SetRegion()

void BamReader::SetIndex ( BamIndex * index )

Sets a custom BamIndex on this reader.

Only necessary for custom BamIndex subclasses. Most clients should never have to use this function.

Example:

        BamReader reader;
        reader.SetIndex(new MyCustomBamIndex);

Note:: BamReader takes ownership of index - i.e. the BamReader will take care of deleting it when the reader is destructed, when the current BAM file is closed, or when a new index is requested.

Parameters:

[in] index custom BamIndex subclass created by client

See also:: CreateIndex(), LocateIndex(), OpenIndex()

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

Sets a target region of interest.

This is an overloaded function.

Warning:: This function 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 reader was able to jump successfully to the region's left boundary

See also:: HasIndex(), Jump()

bool BamReader::SetRegion ( const BamRegion & region )

Sets a target region of interest.

Requires that index data be available. Attempts a random-access jump in the BAM file, near region left boundary position.

Subsequent calls to GetNextAlignment() or GetNextAlignmentCore() will only return true when alignments can be found that overlap this region.

A region with no right boundary is considered open-ended, meaning that all alignments that lie downstream of the left boundary are considered valid, continuing to the end of the BAM file.

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 reader was able to jump successfully to the region's left boundary

See also:: HasIndex(), Jump()

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

BamTools::BamReader Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation