Loading...
Searching...
No Matches
BamTools::BamReader Class Reference

Provides read access to BAM files. More...

`#include <BamReader.h>`

## Public Member Functions

| BamReader ()
| constructor
| ~BamReader ()
| destructor
bool | Close ()
| Closes the current BAM file.
const std::string | GetFilename () const
| Returns name of current BAM file.
bool | IsOpen () 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 ()
| 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.
int64_t | Tell () const
bool | GetNextAlignment (BamAlignment &alignment)
| Retrieves next available alignment.
bool | GetNextAlignmentCore (BamAlignment &alignment)
| Retrieves next available alignment, without populating the alignment's string data fields.
const SamHeader & | GetConstSamHeader () const
| Returns const reference to SAM header data.
SamHeader | GetHeader () const
| Returns SAM header data.
std::string | GetHeaderText () const
| Returns SAM header data, as SAM-formatted text.
int | GetReferenceCount () const
| Returns number of reference sequences.
const RefVector & | GetReferenceData () 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 () 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 () 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::BamReader | ( |  | ) |

constructor

## ~BamReader()

BamReader::~BamReader | ( |  | ) |

destructor

## Member Function Documentation

## Close()

bool BamReader::Close | ( |  | ) |

Closes the current BAM file.

Also clears out all header and reference data.

Returns
  `true` if file closed OK

See also
  IsOpen(), Open()

## CreateIndex()

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

## GetConstSamHeader()

const SamHeader & BamReader::GetConstSamHeader | ( |  | ) | const

Returns const reference to SAM header data.

Allows for read-only queries of SAM header data.

If you do not need to modify the SAM header, use this method to avoid the potentially expensive copy used by GetHeader().

Note

Returns
  const reference to header data object

See also
  GetHeader(), GetHeaderText()

## GetErrorString()

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

## GetFilename()

const std::string BamReader::GetFilename | ( |  | ) | 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()

## GetHeader()

SamHeader BamReader::GetHeader | ( |  | ) | const

Returns SAM header data.

Header data is wrapped in a SamHeader object that can be conveniently queried and/or modified. If you only need read access, consider using GetConstSamHeader() instead.

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
  GetConstSamHeader(), GetHeaderText()

## GetHeaderText()

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

## GetNextAlignment()

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

## GetNextAlignmentCore()

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, excluding filename, 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()

## GetReferenceCount()

int BamReader::GetReferenceCount | ( |  | ) | const

Returns number of reference sequences.

## GetReferenceData()

const RefVector & BamReader::GetReferenceData | ( |  | ) | const

Returns all reference sequence entries.

See also
  RefData

## GetReferenceID()

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

## HasIndex()

bool BamReader::HasIndex | ( |  | ) | const

Returns `true` if index data is available.

## IsOpen()

bool BamReader::IsOpen | ( |  | ) | const

Returns `true` if a BAM file is open for reading.

## Jump()

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

## LocateIndex()

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

## Open()

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

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

## Rewind()

bool BamReader::Rewind | ( |  | ) |

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

## SetIndex()

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);
BamTools::BamReader::SetIndex
void SetIndex(BamIndex *index)
Sets a custom BamIndex on this reader.
Definition BamReader.cpp:345
BamTools::BamReader::BamReader
BamReader()
constructor
Definition BamReader.cpp:28

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

## SetRegion() [1/2]

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

## SetRegion() [2/2]

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

## Tell()

int64_t BamReader::Tell | ( |  | ) | const

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

- BamReader.h
- BamReader.cpp