BamFile

#include <pbbam/BamFile.h>
class PacBio::BAM::BamFile

The BamFile class represents a BAM file.

It provides access to header metadata and methods for finding/creating associated index files.

Constructors & Related Methods

BamFile(const std::string &filename)

Creates a BamFile object on the provided filename & loads header information.

Parameters
  • filename: BAM filename
Exceptions
  • std::exception: on failure to open BAM file for reading

BamFile(const BamFile &other)
BamFile(BamFile &&other)
BamFile &operator=(const BamFile &other)
BamFile &operator=(BamFile &&other)
~BamFile()

Index & Filename Methods

void CreatePacBioIndex() const

Creates a ”.pbi” file for this BAM file.

Note
Existing index file will be overwritten. Use EnsurePacBioIndexExists() if this is not desired.
Exceptions
  • if: PBI file could not be properly created and/or written to disk

void CreateStandardIndex() const

Creates a ”.bai” file for this BAM file.

Note
Existing index file will be overwritten. Use EnsureStandardIndexExists() if this is not desired.
Exceptions
  • if: BAI file could not be properly created (e.g. this BAM is not coordinate-sorted) or could not be written to disk

void EnsurePacBioIndexExists() const

Creates a ”.pbi” file if one does not exist or is older than its BAM file.

Equivalent to:

if (!file.PacBioIndexExists())
    file.CreatePacBioIndex();

Note
As of v0.4.02+, no timestamp check is performed. Previously we requr with an additional timestamp check.
Exceptions
  • if: PBI file could not be properly created and/or written to disk

void EnsureStandardIndexExists() const

Creates a ”.bai” file if one does not exist or is older than its BAM file.

Equivalent to:

if (!file.StandardIndexExists())
    file.CreateStandardIndex();

Note
As of v0.4.2, no timestamp check is performed.
Exceptions
  • if: BAI file could not be properly created (e.g. this BAM is not coordinate-sorted) or could not be written to disk

std::string Filename() const

Return
BAM filename

bool HasEOF() const

Return
true if BAM file has EOF marker (empty BGZF block). Streamed input (filename: “-”)

bool PacBioIndexExists() const

Return
true if ”.pbi” exists and is newer than this BAM file.

std::string PacBioIndexFilename() const

Return
filename of PacBio index file (”.pbi”)
Note
No guarantee is made on the existence of this file. This method simply returns the expected filename.

bool PacBioIndexIsNewer() const

Return
true if ”.pbi” has a more recent timestamp than this file

bool StandardIndexExists() const

Return
true if ”.bai” exists

std::string StandardIndexFilename() const

Note
No guarantee is made on the existence of this file. This method simply returns the expected filename.

bool StandardIndexIsNewer() const

Return
true if ”.bai” has a more recent timestamp than this file

File Header Data

bool HasReference(const std::string &name) const

Return
true if header metadata has this reference name

const BamHeader &Header() const

Return
const reference to BamHeader containing the file’s metadata

bool IsPacBioBAM() const

Return
true if file is a PacBio BAM file (i.e. has non-empty version associated with header “pb” tag)

int ReferenceId(const std::string &name) const

Return
ID for reference name (can be used for e.g. GenomicIntervalQuery), or -1 if not found

std::string ReferenceName(const int id) const

Return
name of reference matching id, empty string if not found

uint32_t ReferenceLength(const std::string &name) const

Return
length of requested reference name. 0 if not found

uint32_t ReferenceLength(const int id) const

Return
length of requested reference id. 0 if not found

Additional Attributes

int64_t FirstAlignmentOffset() const

Return
virtual offset of first alignment. Intended mostly for internal use. Note that this is a BGZF virtual offset, not a ‘normal’ file position.