BamRecordImpl

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

The BamRecordImpl class holds all data necessary for creating, querying or editing a generic BAM record.

For PacBio-specific extensions and convenience methods, see BamRecord.

Note
This class is mostly an internal implementation detail and will likely be removed from the public API in the future. Please use BamRecord as much as possible.

Constructors & Related Methods

BamRecordImpl()
BamRecordImpl(const BamRecordImpl &other)
BamRecordImpl(BamRecordImpl &&other)
BamRecordImpl &operator=(const BamRecordImpl &other)
BamRecordImpl &operator=(BamRecordImpl &&other)
virtual ~BamRecordImpl()

Core Data

uint32_t Bin() const

Return
this record’s assigned (BAI) index bin ID.

uint32_t Flag() const

Return
this record’s alignment flag, in raw integer form.

int32_t InsertSize() const

Return
this record’s insert size

uint8_t MapQuality() const

Return
this record’s mapping quality. A value of 255 indicates “unknown”

PacBio::BAM::Position MatePosition() const

Return
this record’s mate’s mapped position, or -1 if unmapped

int32_t MateReferenceId() const

Return
this record’s mate’s mapped reference ID, or -1 if unmapped

PacBio::BAM::Position Position() const

Return
this record’s mapped position, or -1 if unmapped

int32_t ReferenceId() const

Return
this record’s mate’s mapped reference ID, or -1 if unmapped

BamRecordImpl &Bin(uint32_t bin)

Sets the record’s (BAI) index bin ID.

Return
reference to this record
Parameters
  • bin: BAI index bin ID.

BamRecordImpl &Flag(uint32_t flag)

Sets this record’s alignment flag, using a raw integer.

Return
reference to this record
Parameters
  • flag: raw alignment flag

BamRecordImpl &InsertSize(int32_t iSize)

Sets this record’s insert size.

Return
reference to this record
Parameters
  • iSize: insert size

BamRecordImpl &MapQuality(uint8_t mapQual)

Sets this record’s map quality.

Return
reference to this record
Parameters
  • mapQual: mapping quality - value of 255 indicates “unknown”

BamRecordImpl &MatePosition(PacBio::BAM::Position pos)

Sets this record’s mate’s mapped position.

Return
reference to this record
Parameters
  • pos: mapped position. A value of -1 indicates unmapped.

BamRecordImpl &MateReferenceId(int32_t id)

Sets this record’s mate’s mapped reference ID

Return
reference to this record
Parameters
  • id: reference ID. A value of -1 indicates unmapped.

BamRecordImpl &Position(PacBio::BAM::Position pos)

Sets this record’s mapped position.

Return
reference to this record
Parameters
  • pos: mapped position. A value of -1 indicates unmapped.

BamRecordImpl &ReferenceId(int32_t id)

Sets this record’s mapped reference ID

Return
reference to this record
Parameters
  • id: reference ID. A value of -1 indicates unmapped.

Alignment Flags

bool IsDuplicate() const

Return
true if this record is a PCR/optical duplicate

bool IsFailedQC() const

Return
true if this record failed quality controls

bool IsFirstMate() const

Return
true if this record is the first mate of a pair

bool IsMapped() const

Return
true if this record was mapped by aligner

bool IsMateMapped() const

Return
true if this record’s mate was mapped by aligner

bool IsMateReverseStrand() const

Return
true if this record’s mate was mapped to the reverse strand

bool IsPaired() const

Return
true if this record comes from paired-end sequencing

bool IsPrimaryAlignment() const

Return
true if this record is a read’s primary alignment

bool IsProperPair() const

Return
true if this record & its mate were properly aligned

bool IsReverseStrand() const

Return
true if this record was mapped to the reverse strand

bool IsSecondMate() const

Return
true if this record is the second mate of a pair

bool IsSupplementaryAlignment() const

Return
true if this record is a supplementary alignment

BamRecordImpl &SetDuplicate(bool ok)

Sets whether this record is a PCR/optical duplicate.

BamRecordImpl &SetFailedQC(bool ok)

Sets whether this record failed quality controls.

BamRecordImpl &SetFirstMate(bool ok)

Sets whether this record is the first mate of a pair.

BamRecordImpl &SetMapped(bool ok)

Sets whether this record was aligned.

BamRecordImpl &SetMateMapped(bool ok)

Sets whether this record’s mate was aligned.

BamRecordImpl &SetMateReverseStrand(bool ok)

Sets whether this record’s mate mapped to reverse strand.

BamRecordImpl &SetPaired(bool ok)

Sets whether this record came from paired-end sequencing.

BamRecordImpl &SetPrimaryAlignment(bool ok)

Sets whether this record is a read’s primary alignment.

BamRecordImpl &SetProperPair(bool ok)

Sets whether this record & its mate were properly mapped, per the aligner.

BamRecordImpl &SetReverseStrand(bool ok)

Sets whether this record mapped to reverse strand.

BamRecordImpl &SetSecondMate(bool ok)

Sets whether this record is the second mate of a pair.

BamRecordImpl &SetSupplementaryAlignment(bool ok)

Sets whether this record is a supplementary alignment.

Variable-length Data (sequence, qualities, etc.)

Cigar CigarData() const

Return
the record’s CIGAR data as a Cigar object

BamRecordImpl &CigarData(const Cigar &cigar)

Sets the record’s CIGAR data using a Cigar object

Return
reference to this record
Parameters

BamRecordImpl &CigarData(const std::string &cigarString)

Sets the record’s CIGAR data using a CIGAR-formatted string.

Return
reference to this record
Parameters
  • cigarString: CIGAR-formatted string

std::string Name() const

Return
the record’s query name

BamRecordImpl &Name(const std::string &name)

Sets the record’s “query name”.

Return
reference to this record
Parameters
  • name: new name

QualityValues Qualities() const

Return
the record’s quality values (phred-style ASCII)
Note
Usually Qualities().size() == Sequence.size(). However, in some data sets, the quality values are not provided. In that case, this method will return an empty container.

std::string Sequence() const

Return
the record’s DNA sequence.

size_t SequenceLength() const
BamRecordImpl &SetSequenceAndQualities(const std::string &sequence, const std::string &qualities = std::string())

Sets the record’s DNA sequence and quality values.

This is an overloaded function. Sets the DNA sequence and quality values, using the length of sequence.

Note
When using this overload (and qualities is non-empty), the lengths of sequence and qualities must be equal.

Return
reference to this record.
See
SetSequenceAndQualities(const char* sequence, const size_t sequenceLength, const char* qualities)
Parameters
  • sequence: std::string containing DNA sequence
  • qualities: std::string containing ASCII quality values

BamRecordImpl &SetSequenceAndQualities(const char *sequence, const size_t sequenceLength, const char *qualities = nullptr)

Sets the record’s DNA sequence and quality values.

The sequence must consist of IUPAC nucleotide codes {=ACMGRSVTWYHKDBN}. The qualities, if not empty, must consist of ‘phred’-style ASCII quality values. qualities may be an empty string or NULL pointer in cases where there are no such data available.

Note
sequence does NOT have to be NULL-terminated. Length is explicitly determined by the value of sequenceLength provided.
Return
reference to this record.
Parameters
  • sequence: C-string containing DNA sequence
  • sequenceLength: length of DNA sequence
  • qualities: C-string containing ‘phred-style’ ASCII quality values

BamRecordImpl &SetPreencodedSequenceAndQualities(const char *encodedSequence, const size_t rawSequenceLength, const char *qualities = nullptr)

Sets the record’s DNA sequence and quality values.

The encodedSequence should be preencoded/packed into the BAM binary format. The qualities, if not empty, must consist of ‘phred’-style ASCII quality values. qualities may be an empty string or NULL pointer in cases where there are no such data available.

Note
encodedSequence does NOT have to be NULL-terminated. Length is explicitly determined by the value of sequenceLength provided.
Return
reference to this record.
See
SetSequenceAndQualities(const char* sequence, const size_t sequenceLength, const char* qualities)
Parameters
  • encodedSequence: C-string containing BAM-format-encoded DNA sequence
  • rawSequenceLength: length of DNA sequence (not the encoded length)
  • qualities: C-string containing ‘phred-style’ ASCII quality values

Tag Data

TagCollection Tags() const

Return
record’s full tag data as a TagCollection object

BamRecordImpl &Tags(const TagCollection &tags)

Sets the record’s full tag data via a TagCollection object.

bool AddTag(const std::string &tagName, const Tag &value)

Adds a new tag to this record.

Note
Any value that can be used to implicitly construct a Tag is valid. 
string s;
vector<uint32_t> v;
record.AddTag("XX", s); // will add a string-type tag
record.AddTag("YY", v); // will add a uint32-array-type tag
Return
true if tag was successfully added.
Parameters
  • tagName: 2-character tag name.
  • value: Tag object that describes the type & value of data to be added

bool AddTag(const BamRecordTag tag, const Tag &value)

Adds a new tag to this record.

This is an overloaded method.

Return
true if tag was successfully added.
Parameters
  • tag: BamRecordTag enum
  • value: Tag object that describes the type & value of data to be added

bool AddTag(const std::string &tagName, const Tag &value, const TagModifier additionalModifier)

Adds a new tag to this record, with an optional modifier.

Note
Any value that can be used to implicitly construct a Tag is valid. 
char c;
string h;
record.AddTag("XX", c, TagModifier::ASCII_CHAR); // will add a char-type tag
record.AddTag("YY", h, TagModifier::HEX_STRING); // will add a hex string-type tag
Return
true if tag was successfully added.
Parameters
  • tagName: 2-character tag name.
  • value: Tag object that describes the type & value of data to be added
  • additionalModifier: optional extra modifier (for explicit modification of an otherwise const Tag)

bool AddTag(const BamRecordTag tag, const Tag &value, const TagModifier additionalModifier)

Adds a new tag to this record, with an optional modifier.

This is an overloaded method.

Return
true if tag was successfully added.
Parameters
  • tag: BamRecordTag enum.
  • value: Tag object that describes the type & value of data to be added
  • additionalModifier: optional extra modifier (for explicit modification of an otherwise const Tag)

bool EditTag(const std::string &tagName, const Tag &newValue)

Edits an existing tag on this record.

Note
Any value that can be used to implicitly construct a Tag is valid. 
string s;
vector<uint32_t> v;
record.EditTag("XX", s); // will overwrite tag XX with a string-type tag
record.EditTag("YY", v); // will overwrite tag YY with a uint32-array-type tag
Return
true if tag was successfully edited.
Parameters
  • tagName: 2-character tag name. Name must be present (see HasTag)
  • newValue: Tag object that describes the type & value of new data to be added

bool EditTag(const BamRecordTag tag, const Tag &newValue)

Edits an existing tag on this record.

This is an overloaded method.

Return
true if tag was successfully edited.
Parameters
  • tag: BamRecordTag enum
  • newValue: Tag object that describes the type & value of new data to be added

bool EditTag(const std::string &tagName, const Tag &value, const TagModifier additionalModifier)

Edits an existing tag on this record.

Note
Any value that can be used to implicitly construct a Tag is valid. 
char c;
string h;
record.EditTag("XX", c, TagModifier::ASCII_CHAR); // will overwrite tag XX with a char-type tag
record.EditTag("YY", h, TagModifier::HEX_STRING); // will overwrite tag YY with a hex string-type tag
Return
true if tag was successfully edited.
Parameters
  • tagName: 2-character tag name. Name must be present (see HasTag)
  • value: Tag object that describes the type & value of new data to be added
  • additionalModifier: optional extra modifier (for explicit modification of an otherwise const Tag)

bool EditTag(const BamRecordTag tag, const Tag &value, const TagModifier additionalModifier)

Edits an existing tag on this record.

This is an overloaded method.

Return
true if tag was successfully edited.
Parameters
  • tag: BamRecordTag enum
  • value: Tag object that describes the type & value of new data to be added
  • additionalModifier: optional extra modifier (for explicit modification of an otherwise const Tag)

bool HasTag(const std::string &tagName) const

Return
true if a tag with this name is present in this record.

bool HasTag(const BamRecordTag tag) const

This is an overloaded method.

Return
true if this tag is present in this record.

bool RemoveTag(const std::string &tagName)

Removes an existing tag from this record.

Return
true if tag was actaully removed (i.e. false if tagName previously unknown)
See
HasTag
Parameters
  • tagName: 2-character tag name.

bool RemoveTag(const BamRecordTag tag)

Removes an existing tag from this record.

This is an overloaded method.

Return
true if tag was actaully removed (i.e. false if tagName previously unknown)
See
HasTag
Parameters
  • tag: BamRecordTag enum

Tag TagValue(const std::string &tagName) const

Fetches a tag from this record.

Return
Tag object for the requested name. If name is unknown, a default constructed Tag is returned (Tag::IsNull() is true).
Parameters
  • tagName: 2-character tag name.

Tag TagValue(const BamRecordTag tag) const

Fetches a tag from this record.

This is an overloaded method

Return
Tag object for the requested name. If name is unknown, a default constructed Tag is returned (Tag::IsNull() is true).
Parameters
  • tag: BamRecordTag enum

Public Types

enum AlignmentFlag

These flags describe the alignment status of the record.

Values:

PAIRED = 0x0001

Record comes from paired-end sequencing.

PROPER_PAIR = 0x0002

Each mate of a pair was properly aligned (“proper” as determined by aligner)

UNMAPPED = 0x0004

Record was not mapped by aligner.

MATE_UNMAPPED = 0x0008

Record’s mate was not mapped by aligner.

REVERSE_STRAND = 0x0010

Record was aligned to reverse strand (Sequence() is reverse-complemented)

MATE_REVERSE_STRAND = 0x0020

Record’s mate was aligned to reverse strand (mate’s Sequence() is reverse-complemented)

MATE_1 = 0x0040

Record is first mate of pair.

MATE_2 = 0x0080

Record is second mate of pair.

SECONDARY = 0x0100

Record is a secondary alignment.

FAILED_QC = 0x0200

Record failed quality controls.

DUPLICATE = 0x0400

Record is a PCR/optical duplicate.

SUPPLEMENTARY = 0x0800

Record is a supplementary alignment.

Friends

friend PacBio::BAM::BamRecordImpl::internal::BamRecordMemory