C++ Class: SamRecord
This class is part of libbam.
Setting fields in a SAM/BAM Record
The SamRecord class contains accessors to set the fields of a SAM/BAM record. They are used for creating a record that is not read from a SAM/BAM file. By using these set methods to setup the record, they can be pulled back out using the get accessors or the record can be later written as either a SAM/BAM record. The methods found in the SamRecord class for setting fields are:
Method Name | Description |
---|---|
void SamRecord::resetRecord()
|
Resets the record to be an empty record. This is not necessary when you are reading a Sam/Bam file, but if you are setting fields, it is a good idea to clean out a record before reusing it. Clearing it allows you to not have to set any empty fields. |
bool SamRecord::setReadName(const char* readName)
|
Sets QNAME to the passed in name.
Returns true if successfully set, false if not. |
bool SamRecord::setFlag(uint16_t flag)
|
Sets the bitwise FLAG to the passed in value.
Returns true if successfully set, false if not. |
bool SamRecord::setReferenceName(SamFileHeader& header, const char* referenceName)
|
Sets the reference sequence name. The reference id is calculated using the header.
Returns true if successfully set, false if not. |
bool SamRecord::set1BasedPosition(int32_t position)
|
Sets the leftmost position. The value passed in is 1-based (SAM formatted). Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::set0BasedPosition(int32_t position)
|
Sets the leftmost position. The value passed in is 0-based (BAM formatted). Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::setMapQuality(int8_t mapQuality)
|
Sets the mapping quality.
Returns true if successfully set, false if not. |
bool SamRecord::setCigar(const char* cigar)
|
Sets the cigar string to the passed in CIGAR. This is a SAM formatted CIGAR string. Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::setMateReferenceName(SamFileHeader& header, const char* referenceName)
|
Sets the mate reference sequence name. The mate reference id is calculated using the header.
Returns true if successfully set, false if not. |
bool SamRecord::set1BasedMatePosition(int32_t matePosition)
|
Sets the leftmost mate position. The value passed in is 1-based (SAM formatted). Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::set0BasedMatePosition(int32_t matePosition)
|
Sets the leftmost mate position. The value passed in is 0-based (BAM formatted). Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::setInsertSize(int32_t insertSize)
|
Sets the inferred insert size.
Returns true if successfully set, false if not. |
bool SamRecord::setSequence(const char* seq)
|
Sets the sequence string to the passed in string. This is a SAM formatted sequence string. Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::setQuality(const char* quality)
|
Sets the quality string to the passed in string. This is a SAM formatted quality string. Internal processing handles switching between SAM/BAM formats when read/written.
Returns true if successfully set, false if not. |
bool SamRecord::addTag(const char* tag, char vtype, const char* value)
|
Adds a tag to the record with the specified tag, vtype, and value. Vtype can be SAM/BAM vtype. Internal processing handles switching between SAM/BAM vtypes when read/written.
Returns true if successfully set, false if not. |
SamStatus::Status SamRecord::setBufferFromFile(IFILE filePtr, SamFileHeader& header)
|
Reads a BAM record from the specified BAM file. |
SamStatus::Status SamRecord::setBuffer(const char* fromBuffer, uint32_t fromBufferSize, SamFileHeader& header)
|
Sets the SamRecord to contain the BAM record contents found in fromBuffer. |
Retrieving fields from a SAM/BAM Record
The SamRecord class contains accessors to access the fields of a SAM/BAM record. They assume that the class has already been populated, either by using the set commands or by calling SamFile::ReadRecord. Not all of the values that can be retrieved using these get accessors have set methods. That is because they are internally calculated values if they were not read from a file.
The methods found in the SamRecord class for setting fields are:
Method Name | Description |
---|---|
bool SamRecord::isValid(SamFileHeader& header)
|
Returns true if the record is valid. This performs validation steps. |
const void* SamRecord::getRecordBuffer()
|
Returns a const pointer to the buffer that is the BAM representation of the record. |
SamStatus::Status SamRecord::writeRecordBuffer(IFILE filePtr)
|
Returns the status of writing the BAM record into the specified, already opened IFILE. |
int32_t SamRecord::getBlockSize()
|
Returns the BAM block size of the record. |
const char* SamRecord::getReferenceName()
|
Returns the reference sequence name (SAM format). |
int32_t SamRecord::getReferenceID()
|
Returns the reference sequence ID (BAM format). |
int32_t SamRecord::get1BasedPosition()
|
Returns the 1-based (SAM formatted) leftmost position. |
int32_t SamRecord::get0BasedPosition()
|
Returns the 0-based (BAM formatted) leftmost position. |
int8_t SamRecord::getReadNameLength()
|
Returns the length of the ReadName (QNAME). |
int8_t SamRecord::getMapQuality()
|
Returns the map quality. |
int16_t SamRecord::getBin()
|
Returns the BAM bin for the record. |
int16_t SamRecord::getCigarLength()
|
Returns the length of the CIGAR in BAM format. |
uint16_t SamRecord::getFlag()
|
Returns the flag. |
int32_t SamRecord::getReadLength()
|
Returns the length of the read. |
const char* SamRecord::getMateReferenceName()
|
Returns the mate reference sequence name (SAM format). Returns the mate reference sequence name even if it is the same as the reference sequence name. |
const char* SamRecord::getMateReferenceNameOrEqual()
|
Returns the mate reference sequence name (SAM format). Returns the mate reference sequence name, unless it is the same as the reference sequence name, then an "=" is returned, unless the name is "*", then "*" is returned. |
int32_t SamRecord::getMateReferenceID()
|
Returns the mate reference sequence id (BAM format). |
int32_t SamRecord::get1BasedMatePosition()
|
Returns the 1-based (SAM formatted) mate leftmost position. |
int32_t SamRecord::get0BasedMatePosition()
|
Returns the 0-based (BAM formatted) mate leftmost position. |
int32_t SamRecord::getInsertSize()
|
Returns the insert size. |
int32_t SamRecord::get0BasedAlignmentEnd()
|
Returns the 0-based inclusive right-most position of the clipped sequence. |
int32_t SamRecord::get1BasedAlignmentEnd()
|
Returns the 1-based inclusive right-most position of the clipped sequence. |
int32_t SamRecord::getAlignmentLength()
|
Returns the length of the clipped sequence (returns 0 if the cigar is '*'). |
int32_t SamRecord::get0BasedUnclippedStart()
|
Returns the 0-based inclusive left-most position adjusted for clipped bases. |
int32_t SamRecord::get1BasedUnclippedStart()
|
Returns the 1-based inclusive left-most position adjusted for clipped bases. |
int32_t SamRecord::get0BasedUnclippedEnd()
|
Returns the 0-based inclusive right-most position adjusted for clipped bases. |
int32_t SamRecord::get1BasedUnclippedEnd()
|
Returns the 1-based inclusive right-most position adjusted for clipped bases. |
const char* SamRecord::getReadName()
|
Returns the SAM formatted Read Name (QNAME). |
const char* SamRecord::getCigar()
|
Returns the SAM formatted CIGAR string. |
const char* SamRecord::getSequence()
|
Returns the SAM formatted Sequence string. |
const char* SamRecord::getQuality()
|
Returns the SAM formatted Quality string. |
uint32_t SamRecord::getTagLength()>/code>
|
Returns the length of the tags in BAM format. |
bool SamRecord::getNextSamTag(char* tag, char& vtype, void** value)
|
Returns true if a tag was read, false if there are no more tags.
For a true return value, tag is sent to the tag of the tag, vtype is set to the vtype of the tag, and value is a pointer to the value of the tag. You will then need to use a switch to cast value to int, double, char, or String. |
void SamRecord::resetTagIter()
|
Resets the iterator that loops through the tags to the beginning of the tags. The iterator is automatically reset when a new record is read. This method is only necessary if you want to iterate over a set of tags multiple times. |
bool SamRecord::isIntegerType(char vtype)
|
Returns true if the passed in vtype is of integer ('c', 'C', 's', 'S', 'i', 'I') type. |
bool SamRecord::isDoubleType(char vtype)
|
Returns true if the passed in vtype is of double ('f') type. |
bool SamRecord::isCharType(char vtype)
|
Returns true if the passed in vtype is of char ('A') type. |
bool SamRecord::isStringType(char vtype)
|
Returns true if the passed in vtype is of String ('Z') type. |
Example of using getNextSamTag:
// record is a previously setup SamRecord.
String recordString = "";
char tag[3];
char vtype;
void* value;
// While there are more tags, write them to the recordString.
while(record.getNextSamTag(tag, vtype, &value) != false)
{
recordString += "\t";
recordString += tag;
recordString += ":";
recordString += vtype;
recordString += ":";
if(record.isIntegerType(vtype))
{
recordString += (int)*(int*)value;
}
else if(record.isDoubleType(vtype))
{
recordString += (double)*(double*)value;
}
else if(record.isCharType(vtype))
{
recordString += (char)*(char*)value;
}
else
{
// String type.
recordString += (String)*(String*)value;
}
}
recordString += "\n";